MEDUSA: an AI-first SAST scanner that also vets .claude/ before you clone

The problem: AI configs and chat logs are now attack surface

Two failure modes sit behind this project. The first is the repository you clone before reading it. A repo can carry a .claude/ directory with hooks that pipe curl into bash, permissions set to Bash(*) or bypassPermissions, wildcard-tool subagents, or skills that act as droppers. The README describes the v2026.7 release as vetting those structurally before you clone. The second failure mode is local: developers paste API keys into AI assistants, and the assistants keep those conversations in plaintext on disk. The README puts it bluntly, that anyone with read access to $HOME can grep for sk-, ghp_ or AKIA prefixes. MEDUSA targets both. The audience is engineers who pull in AI tooling, MCP servers and RAG pipelines faster than their existing SAST tooling understands them, and who want a check that runs before the code reaches a working directory.

How the scanning actually works

MEDUSA is a Python 3.10+ package distributed as medusa-security on PyPI. The README states it ships its own detection patterns rather than depending on an installed toolchain, which is what zero setup means here: pip install, then scan. External linters such as bandit, eslint and shellcheck are optional and auto-detected if present, per docs/OPTIONAL_TOOLS.md. Scanning is parallel across cores, and the README claims 10 to 40x faster than sequential, a number you should treat as the project's own. Results cache by content hash so unchanged files are skipped on rescan; the release notes for v2026.5.10 mention a --fail-on cached-findings bug, which tells you the cache interacts with exit codes in a way that has needed fixing. Output formats are JSON, HTML, Markdown and SARIF. Configuration lives in .medusa.yml. The v2026.7 release adds --trace-rules, which writes rule-trace.jsonl and slow_rules.csv with per-rule firing and timing plus a heartbeat, and the notes say this surfaced a catastrophic-backtracking ReDoS. That is a useful admission: the rule engine itself has had performance defects, and the diagnostics exist to catch them.

Commands you can run today

The README names four entry points. medusa scan --git <URL> scans a remote repository without cloning it, and in v2026.7 that path also vets .claude/ hooks, permissions, subagents and skills, with a context-aware screening mode for target vetting. medusa secrets scan searches AI assistant histories (Claude Code, Cursor, Copilot, Zed, Gemini) and shell histories (bash, zsh, psql, mysql, python REPL) across 21 issuer types including Anthropic, OpenAI, PyPI, GitHub PATs, AWS, GCP, Stripe and Slack. The matching purge flow uses an interactive [y/n/s/a/q] prompt, requires a byte-identical backup before redaction, and writes JSONL-safe output. The README states the secrets path is local-only with no telemetry. Project-specific settings go in .medusa.yml, and a --fail-on flag exists for CI gating. Beyond that, the supplied material does not document individual config keys, so treat the file as the place to look rather than something quoted here.

Where the coverage is thin or the tool is wrong

The pattern count is the headline and also the weakest claim. 40,000+ detection patterns were harvested from 8,466 AI-security research papers in v2026.5.12 and described as false-positive-hardened, but the README gives no per-language breakdown, no precision figure and no way to see which patterns are active on a given file. The v2026.7 notes do mention a documentation-placeholder secret false-positive fix, which is a small signal that FP tuning is ongoing rather than finished. The 200 CVE detections are enumerated by name (Log4Shell, Spring4Shell, XZ Utils, LangChain RCE, MCP remote RCE, React2Shell) rather than by coverage model, so an older or less famous CVE in your dependency set is not implied to be covered. Native rule sets are narrow by design: 22 Rust rules and 16 PHP rules, listed as TLS verification disabled, command injection, untrusted deserialization, raw SQL, unsafe memory ops, weak crypto and SSRF on the Rust side, with SQLi, eval injection, LFI/RFI, path traversal, unserialize() object injection, unrestricted upload, reflected XSS and SSRF on the PHP side. If your stack is Java or Go, those lists are not your coverage. And if you need dataflow or taint analysis rather than pattern matching, this is the wrong class of tool.

Compared with Semgrep on the AI-config question

Semgrep is the obvious reference point for pattern-based scanning, and the difference is not speed. Semgrep's model is that you write or import rules in its own syntax and tune them to your codebase; it is a general engine that you aim at a target. MEDUSA's model is closer to a fixed corpus: the patterns ship with the package, the AI-config file types are enumerated (28+ editor config types across Cursor, Cline, Copilot, Claude Code, Gemini and Kiro), and the .claude/ vetting is a built-in structural check rather than something you author. That means less setup and less control. If you already maintain Semgrep rules for your organisation, MEDUSA will not replace them, because you cannot express arbitrary project-specific logic in .medusa.yml the way you can with a rule file. Conversely, if you have no rule-writing capacity and want a pre-clone check on an unfamiliar AI repo, the built-in .claude/ path is the part Semgrep does not give you out of the box. The honest framing is that they overlap on generic pattern matching and diverge on who writes the rules.

Licence and the cost of keeping up

MEDUSA is AGPL-3.0. For internal scanning that is usually unremarkable, but if you embed it in a network-facing service or a distributed product, the copyleft terms are worth reading with your own counsel rather than inferred from this article. The maintenance picture visible in the material is fast-moving: three releases between late May and late June 2026, with v2026.5.12 described as the biggest pattern release (9,600 to 40,000+ patterns) and v2026.7.0 adding Claude Code detection, the attack-signature scanner, Rust and PHP rules and rule diagnostics. That cadence has two costs. First, the pattern set changes under you, so a clean scan today and a finding tomorrow may reflect new rules rather than new code. Second, several recent entries are security fixes to MEDUSA itself: a VS Code extension command-injection fix, argv injection defences, git SSRF, HMAC cache integrity, a markdown XSS fix. A scanner that has needed that many self-fixes is one to keep current rather than pin for a year.

Who should adopt it, and what to check first

The fit is a team that regularly clones AI-adjacent repositories, runs MCP servers, or wants a local sweep of assistant and shell history for leaked credentials, and that is comfortable with an AGPL-3.0 dependency. The misfit is a team looking for deep dataflow analysis on a Java or Go codebase, or one that needs auditable, hand-written rules for regulatory reasons. If you are in the first group, start with medusa scan --git against a repository you already trust and read the .claude/ findings against the actual files, then run medusa secrets scan and confirm every reported path is one you expected. Use --trace-rules on a large repo to see which rules fire and how long they take before you wire --fail-on into CI. The specific thing to verify is that a known-clean repository exits zero under --fail-on; if it does not, the false-positive rate is your first problem, not your code.

Editorial conclusion

Adopt MEDUSA if you clone third-party repos containing AI editor configs or MCP servers and want a pre-clone structural check plus a local secrets sweep of AI chat and shell history, and if AGPL-3.0 fits how you ship. Do not adopt it as your only scanner for a conventional Java or Go service, where its 200 CVE detections and native rule sets are not the coverage you need. Before trusting a run, verify three things: that the .claude/ findings map to files you can actually read, that the secrets scan reports only paths you expected, and that a --fail-on run on a known-clean repo exits zero.

Official sources

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