Pantheon-Security/medusa: an AI-first security scanner that vets .claude/ before you clone

What MEDUSA scans that a normal SAST tool does not

Most static analysis tools were built for application code: imports, sinks, tainted data. MEDUSA is built for the layer that appeared underneath that code in the last two years. The README describes 40,000+ detection patterns covering AI/ML applications, LLM agents, MCP servers and RAG pipelines, alongside 200 CVE detections that include Log4Shell, Spring4Shell, the XZ Utils backdoor, LangChain RCE, MCP remote code execution and React2Shell. Some of those are ordinary dependency and pattern checks. The interesting ones are not.

The project's stated audience is developers who pull in agent configuration files and MCP servers from repositories they did not write. A .claude/ directory can contain hooks, permission grants, subagent definitions and skills. According to the README, the v2026.7.0 release added structural vetting of that directory for poisoned hooks (curl piped to bash, base64 to exec, credential exfiltration, reverse shells), over-broad permissions such as Bash(*) or bypassPermissions, wildcard-tool subagents and dropper skills. Repo poisoning detection covers 28+ file types across Cursor, Cline, Copilot, Claude Code, Gemini and Kiro.

That is a narrow problem, and it is a real one. The failure mode is not a bug in your code. It is a config file that runs something on your machine the moment you open the project.

How the scan pipeline is put together

The package metadata in pyproject.toml describes 79 analyzers. The README says MEDUSA works out of the box with no external tool installation, and that optional linters such as bandit, eslint and shellcheck are auto-detected if present. That distinction matters for how you read results: the built-in rule set is what always runs, and the external linters are a bonus layer that only fires when the binaries exist on the host.

Scanning is parallel across cores, which the README describes as 10-40x faster than sequential, and results are cached by content hash so unchanged files are skipped on rescans. The caching claim is qualified as correct in CI, which is the case worth caring about: a cache keyed on file content rather than timestamps is what stops a stale result from masking a changed file.

v2026.7.0 added native Rust and PHP rules. The Rust set is 22 rules (TLS verification disabled, command injection, untrusted deserialization, raw SQL, unsafe memory operations, weak crypto, SSRF) and the PHP set is 16 (SQL injection, command and eval injection, LFI/RFI, path traversal, unserialize object injection, unrestricted upload, reflected XSS, SSRF, weak crypto). The README is explicit that these need no toolchain, which is the point: you get Rust and PHP coverage without installing cargo or a PHP runtime.

The same release added --trace-rules, which writes a per-rule firing log and timing to rule-trace.jsonl and slow_rules.csv. The release notes say this surfaced a real catastrophic-backtracking ReDoS, and that a ReDoS and nested-set lint now blocks bad patterns at author time. That is a diagnostic feature aimed at rule authors more than at end users, and it is the kind of thing you want in a tool whose value is a large regex corpus.

Installing MEDUSA and running a first scan

The README states the package requires Python 3.10 or newer and installs from PyPI under the name medusa-security. The repository also ships a Dockerfile.simple and a Homebrew Formula/ directory, so container and macOS package routes exist, but the README leads with pip.

pip install medusa-security

After installation the medusa command is on your PATH. The README's headline example is a scan of a remote repository, which clones and inspects the target before you do.

medusa scan --git <URL>

The output is terminal text with progress reporting. For a repository you already have locally, the same command runs against the working tree, and the README lists JSON, HTML, Markdown and SARIF as export formats for CI and code-scanning workflows.

The second command worth knowing is the secrets scan. It looks for leaked credentials in AI assistant chat histories (Claude Code, Cursor, Copilot, Zed, Gemini) and in shell histories including bash, zsh, psql, mysql and the Python REPL, across 21 issuer types such as Anthropic, OpenAI, PyPI, GitHub PATs, AWS, GCP, Stripe and Slack.

medusa secrets scan

According to the README, the interactive purge prompt accepts [y/n/s/a/q] and takes a byte-identical backup before redacting, and the whole path is local-only with no telemetry. Project-level settings live in .medusa.yml, and examples/medusa.example.yml is the reference file to copy from.

The secrets scanner and its redaction promise

The secrets feature is the part of MEDUSA with the sharpest design constraints, and the README is unusually specific about them. It scans plaintext conversation stores and shell histories, which means it reads files most tools never open. The stated threat is not exotic: a developer pastes a PyPI token or an AWS key into an assistant, the assistant writes the conversation to disk, and anything with read access to $HOME can grep for it later. The README's own framing is that a token might be sitting in a chat history right now.

The purge flow is where the engineering shows. A byte-identical backup is mandatory before redaction, and the redaction is described as JSONL-safe, meaning the tool does not corrupt the line-delimited structure of a history file when it rewrites an entry. That is the correct concern. A naive in-place edit of a JSONL file can leave a trailing comma or a broken line and silently destroy the rest of the file. The [y/n/s/a/q] prompt implies per-finding decisions rather than a blanket wipe, with an option to skip and an option to quit.

Two limits are worth stating plainly. First, the tool reports what its 21 issuer patterns match. A credential format it does not know, or a key stored in a format that does not resemble the issuer's prefix, will not be flagged. Second, redacting a secret from a local file does not revoke it. The README does not claim otherwise, but the sequence matters: rotate first if the key was live, then clean the history.

Where MEDUSA is the wrong tool

MEDUSA is a pattern scanner. Its coverage comes from a rule corpus, and a rule corpus has a shape: it is strong on things that look like a known string and weak on logic that only a human or a dataflow engine will see. If your problem is an authorization flaw in a handler that takes an object ID from a request, no regex in a 40,000-pattern set is going to find it. For that class of bug you want a tool that builds a call graph and tracks taint, and MEDUSA is not that tool.

The rule count itself is a number to treat with care. The README says v2026.5.12 grew the pattern set from 9,600 to 40,000+ patterns harvested from 8,466 AI-security research papers, and describes them as false-positive-hardened. Harvesting patterns from papers is a reasonable way to bootstrap coverage, but it also means a large share of the corpus encodes research findings rather than vulnerabilities observed in shipped code. The release notes acknowledge the flip side directly: v2026.7.0 includes a fix for a documentation-placeholder secret false positive, and the trace tooling exists because a rule caused catastrophic backtracking. A corpus that size will keep producing both kinds of defect.

The name is the other practical problem. Searching for MEDUSA returns the myth, the tattoo, the restaurant, and a Node.js e-commerce platform. The README's own keywords and the package name medusa-security are the disambiguators. Budget for that when you write internal docs or search your own issue tracker.

Finally, the repository's last push was on 2026-08-10. That is recent enough that the project is not dormant, but it is not a statement about support responsiveness, and the README does not document a support SLA or a deprecation policy for rules.

How it differs from Semgrep and Trivy

Semgrep is the closest comparison on the scanning side, and the difference is in what each one is optimized for. Semgrep gives you a pattern language you write and tune yourself, with a large community rule registry and a focus on your own code's semantics. MEDUSA gives you a fixed corpus you do not author, weighted toward AI, agent and MCP artifacts, with a --git mode designed to inspect a repository you have not cloned yet. If your team already maintains Semgrep rules, MEDUSA does not replace that workflow; it adds a check for config files and agent tooling that a Semgrep rule set probably does not cover.

Trivy is the other useful reference point, and the split is cleaner. Trivy is built around dependency manifests, lockfiles, container images and SBOMs, and it answers what known CVEs your shipped artifacts contain. MEDUSA's 200 CVE detections overlap with that, but its center of gravity is source and configuration patterns, not resolved dependency graphs. If your question is which of your container images contains a vulnerable library, Trivy is the right shape of tool. If your question is whether the .claude/settings.json in a repository you are about to open grants Bash(*), Trivy will not answer it and MEDUSA is aimed at exactly that.

Neither comparison is a ranking. The three tools answer different questions, and running more than one is normal.

Licence and the cost of keeping rules current

MEDUSA is licensed AGPL-3.0-or-later according to pyproject.toml, with the README badge pointing at the same identifier. AGPL is a copyleft licence with a network clause. If you modify the tool and let users interact with it over a network, the licence's terms reach that interaction in a way plain GPL does not. Running the unmodified scanner over your own code in CI is a different situation from embedding it in a service you offer. This is not legal advice, and if your organization has a policy on copyleft, the licence text is the thing to read, not this paragraph.

The upgrade cost is the part the README does not document. There is a CHANGELOG.md and a RULE_PROMOTION.md at the repository root, which suggests rules move through a promotion process before they ship, but the README does not describe a rule deprecation policy, a stability guarantee for rule identifiers, or what happens to a suppressed finding when a rule is renamed. If you build CI gates on specific rule IDs, that is the gap to watch. The --fail-on flag exists, and the release notes mention a cached-findings bug fixed in v2026.5.10, so the gating path has had at least one correctness fix already.

The versioning is calendar-based (2026.7.0, 2026.6.0, 2026.5.11), which makes it easy to see how far behind a pinned install is, but tells you nothing about whether a given release changed rule behaviour.

Editorial conclusion

Adopt MEDUSA if you review AI-generated or agent-assisted repositories and want a pre-clone look at .claude/ hooks, permissions and skills, or if you need a local-only pass over shell and AI chat histories for leaked keys. Skip it if you need a general-purpose SAST suite for a large polyglot codebase, or if AGPL-3.0 is incompatible with how you ship. Before trusting it, run medusa scan --git against a repository whose problems you already know, and read .medusa.yml to see which rules and paths are actually in scope.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Pantheon-Security/medusa on GitHub
3. Project website
4. README
5. Releases