DOCUMENTATION

MORPHEX Docs

Everything you need to install, configure, and deploy MORPHEX — from first scan to enterprise-scale secret detection across your entire organization.

Quick Start

Get MORPHEX running in under 60 seconds. No configuration files, no API keys, no setup wizard.

Install

TERMINAL

# macOS / Linux (Homebrew)
brew install pkmdev-sec/tap/morphex

# Or build from source
git clone https://github.com/pkmdev-sec/morphex.sh.git
cd morphex.sh && make build

First Scan

TERMINAL

# Scan a directory
morphex scan .

# Scan git history
morphex scan-git .

# Scan from stdin
cat .env | morphex stdin

# Deep scan (obfuscation detection)
morphex scan --deep .

WHAT HAPPENS DURING A SCAN

MORPHEX extracts candidate tokens, evaluates them through 5 contextual signals, eliminates false positives with 7 independent filters, and optionally verifies surviving credentials against live APIs. Only confirmed secrets are reported.

How It Works

Most secret scanners operate on a simple loop: regex match → report finding. MORPHEX uses provenance-based classification. It doesn't ask “does this look like a secret?” It asks “what is this value's origin story?”

The Pipeline

EXTRACT CANDIDATE

ANALYZE SYNTACTIC ROLE

ANALYZE MORPHOLOGY

ANALYZE FILE CONTEXT

ANALYZE LINE CONTEXT

ANALYZE ENTROPY

ELIMINATE FALSE POSITIVES (7 FILTERS)

VERIFY AGAINST SERVICE API

REPORT CONFIRMED SECRETS

The Five Signals

SIGNAL	MEASURES	EXAMPLE
Syntactic Role	Is the variable name a credential term?	api_key vs version_string
Morphology	Structural fingerprint of the value	sk_live_abc123 vs SUBSCRIPTION_SID
File Provenance	What kind of file is this?	production.yaml vs test_fixtures/
Line Context	What's happening on this line?	assignment vs "replace this"
Entropy	How random is the value?	machine-generated vs human-typed

False Positive Filters

Template References

Catches ${DB_PASSWORD}, process.env.TOKEN

Known Dead Values

Exact-match database of vendor example keys

Inline Instructions

Detects "TODO: replace with your key" comments

Crypto Domain

Distinguishes encryption keys from API keys

Allowlist Context

Values inside exception/allowlist structures

Path Suppression

Test fixtures, mocks, examples, templates

Revocation Detection

Values in files discussing credential rotation

CLI Reference

Commands

FLAG	DESCRIPTION
morphex scan <path>	Scan a file or directory
morphex scan-git <repo>	Scan full git history
morphex stdin	Scan piped input from stdin
morphex version	Show version information
morphex generate-key	Generate API keys for the server
morphex serve	Start the MORPHEX API server

Scan Flags

FLAG	DESCRIPTION
--json	Output results as JSON
--sarif	Output SARIF v2.1.0 (GitHub Code Scanning)
--threshold N	Confidence threshold (default: 0.7)
--deep	Enable deep obfuscation detection
--fail	Exit code 1 if secrets found (CI gating)
--baseline PATH	Suppress known findings from a baseline file
--policy PATH	Custom scan policy JSON file
--workers N	Concurrent workers (default: auto)
--redact N	Redaction level 0–100 (default: 100)
--include GLOBS	File patterns to include
--exclude GLOBS	File patterns to exclude

Configuration

MORPHEX works out of the box with zero configuration. For advanced use, create a morphex.yaml or use policy JSON files to customize scan behavior.

Scan Policies

Policies control confidence thresholds, file filters, severity mapping, and allowlists. Use the built-in policies or create your own.

config/policies/strict-ci.json

{
  "min_confidence": 0.8,
  "include_patterns": ["*.py", "*.go", "*.js", "*.ts",
    "*.env", "*.yaml", "Dockerfile"],
  "exclude_patterns": ["*.test.*", "*_test.go",
    "*.example", "*.sample"],
  "severity_map": {
    "AUTH_CREDENTIAL": "critical",
    "UNCERTAIN": "high"
  },
  "block_on_findings": true,
  "allow_list": [
    {
      "pattern": "AKIAIOSFODNN7EXAMPLE",
      "reason": "AWS official example key"
    },
    {
      "pattern": "sk_test_",
      "reason": "Stripe test-mode keys"
    }
  ]
}

Default Policy

FLAG	DESCRIPTION
min_confidence	0.7 — minimum confidence score to report
max_file_size	1MB — files larger than this are skipped
require_verification	false — don't require API verification
block_on_findings	false — don't fail CI by default

CI/CD Integration

GitHub Actions

.github/workflows/morphex.yml

name: Secret Scan
on: [push, pull_request]
jobs:
  morphex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pkmdev-sec/morphex-action@v1
        with:
          args: scan --sarif --fail .
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Pre-commit Hook

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pkmdev-sec/morphex.sh
    rev: v1.0.0
    hooks:
      - id: morphex
        args: ["scan", "--fail", "--threshold", "0.8"]

CI GATING

Use --fail to make MORPHEX exit with code 1 when secrets are found. Combine with --sarif to upload results directly to GitHub Code Scanning.

Deep Scan Mode

Developers and attackers hide secrets in ways that break traditional regex scanners. The --deep flag enables AST-level parsing that reconstructs obfuscated secrets before classification.

Detected Patterns

OBFUSCATION EXAMPLES

# String concatenation
prefix = "sk_live_"
key = prefix + "4eC39HqLyjWDarjtT1zdp7dc"

# Variable interpolation
base = "ghp_"
token = f"{base}ABCDEFghijklmnop1234567890"

# Reversed string
secret = "cd7pdz1TjraDjWyL9qH3Ce4_evil_ks"[::-1]

TERMINAL

# Enable deep scan
morphex scan --deep /path/to/code

Active Verification

Every surviving candidate is verified against the actual service API using read-only HTTP calls. If a credential is verified as active, it's reported as CONFIRMED. If inactive, expired, or test — it's dropped silently.

Supported Verifiers

GitHub

GitLab

Slack

Stripe

SendGrid

HuggingFace

SAFETY

All verification calls are strictly read-only. MORPHEX never writes, modifies, or deletes anything via verified credentials. It only checks if the credential authenticates.

Enterprise

MORPHEX Enterprise extends the open-source engine with continuous monitoring across your entire infrastructure — version control, cloud storage, container registries, CI/CD platforms, and communication tools.

Source Integrations

GITHUB

GITLAB

BITBUCKET

AZURE REPOS

AWS S3

GCS

AZURE STORAGE

DOCKER / ECR

SLACK

TEAMS

CONFLUENCE

JIRA

CIRCLECI

JENKINS

BUILDKITE

TRAVISCI

Notification Channels

SLACK

JIRA

SPLUNK

PAGERDUTY

OPSGENIE

TEAMS

WEBHOOK

Scheduling

Enterprise supports cron-based scheduling with per-source overrides, real-time monitoring for Slack, and configurable scan timeouts with automatic retry.

morphex.yaml (excerpt)

scheduler:
  default_schedule: "0 2 * * *"   # Daily at 2 AM
  schedules:
    github: "0 */4 * * *"         # Every 4 hours
    slack_realtime: "always_on"   # Continuous
    filesystem: "0 * * * *"       # Hourly
  scan_timeout: 6h
  retry_failed: true