How pantheon-security/medusa works
1. What the repository is
- MEDUSA is a Python 3.10+ CLI application for static security scanning, with the core product boundary centered around medusa scan, medusa init, medusa install, and related management commands.
- The repository is split into a thin command/config layer, a large scanner/rules corpus, and shared core services for orchestration, filtering, and reporting.
2. Primary runtime entrypoints
- medusa/__main__.py and medusa/cli.py provide the command-line interface.
- medusa/config.py loads project settings from .medusa.yml, which controls enabled/disabled scanners, exclusions, workers, caching, and IDE integration.
- medusa/__init__.py and setup.py/pyproject.toml package the tool as medusa-security.
3. Scan orchestration flow
- A scan starts from the CLI, resolves the target path or git repo, applies project exclusions, and fans out work across workers in medusa/core/parallel.py.
- Core scan coordination lives in medusa/core/system.py, with system-load-aware worker sizing and scan boundary enforcement.
- Results are aggregated into a normalized internal issue model before filtering and reporting.
4. Scanner architecture
- medusa/scanners/base.py defines the common scanner contract.
- Each scanner module under medusa/scanners/ targets a file type, language, or security domain, using a shared pattern: declare supported extensions, run a tool or pattern matcher, parse results, and emit structured findings.
- medusa/scanners/__init__.py auto-registers scanners into a registry so the engine can select them by file type or rule category.
5. Two scanner families
- Language/tool wrappers: scanners such as python_scanner.py, javascript_scanner.py, bash_scanner.py, trivy_scanner.py, semgrep_scanner.py, and gitleaks_scanner.py wrap external security/lint tools when present.
- AI/security domain scanners: modules like prompt_injection_code_scanner.py, mcp_server_scanner.py, rag_security_scanner.py, agent_memory_scanner.py, tool_callback_scanner.py, and critical_cve_scanner.py focus on AI/LLM, agent, MCP, repo-poisoning, and CVE detection.
- This split matters architecturally: one side is file/type-driven analysis, the other is threat-model-driven content analysis.
6. Rule and pattern corpus
- The bulk of detection logic is encoded as YAML rules in medusa/rules/, organized by threat area such as prompt injection, agent security, RAG, MCP, model poisoning, supply chain, jailbreaks, and code-gen security.
- medusa/core/fp_patterns/ holds false-positive suppression patterns that are applied after raw findings are produced.
- medusa/core/pattern_analyzer.py and medusa/scanners/yaml_rule_scanner.py support rule interpretation and rule-file scanning.
7. False-positive handling and safety normalization
- medusa/core/fp_filter.py applies repo-specific and universal suppression logic to reduce noisy detections.
- medusa/core/output_sanitizer.py and medusa/core/payload_sanitizer.py protect downstream report rendering by obfuscating dangerous content by default.
- medusa/core/rule_integrity.py and medusa/core/constants.py support trust/consistency checks around rules and output semantics.
8. Reporting pipeline
- medusa/core/reporter.py turns normalized findings into user-facing outputs.
- medusa/core/report_assets.py bundles assets for richer reports, especially HTML output.
- The reporting layer supports multiple export formats called out in the README: JSON, HTML, Markdown, SARIF, JUnit, and text, making reports usable in CI, dashboards, and terminal workflows.
9. Git, cache, and incremental scanning
- The CLI supports scanning local paths and remote git repositories; the remote path is cloned and then treated as a local scan target.
- medusa/platform/tool_cache.py and the core caching flow use content-based keys so unchanged files can be skipped safely across CI and Docker environments.
- The project also has safeguards for scan boundaries and large-file handling, which are important for architecture because they constrain what the scanner may traverse.
10. Platform, installation, and IDE integration
- medusa/platform/ is the bootstrap/management subsystem: detector.py detects environment details, version_manager.py handles tool/version state, and install_manifest.py describes installable capabilities.
- medusa/platform/installers/ contains OS-specific installers for Linux, macOS, Windows, plus a cross-platform/simple path; this mainly supports first-run setup and optional tool availability checks.
- medusa/ide/ contains integration helpers such as claude_code.py and backup.py for generating or preserving AI assistant context files.
11. Packaging and distribution boundaries
- The repo is built for PyPI distribution, Homebrew (Formula/medusa-security.rb), and Docker (Dockerfile.simple, docs/docker/), so the runtime is intentionally self-contained and cross-platform.
- medusa/tool-versions.lock, .medusa.yml, and .github/actions/medusa-scan / workflow files show that the project is also intended to be consumed in CI/CD and as a reusable GitHub Action.
- Optional external tools are detected at runtime rather than being mandatory dependencies, which keeps the base scanner portable.
12. Testing and quality gates
- tests/ covers core scanning behavior, reporter output, false-positive filtering, git scanning, hardening, installer behavior, and rule coverage.
- tests/benchmark_corpus/ provides representative inputs for performance and regression testing across AI config files, web code, Kubernetes, Docker, and MCP artifacts.
- The test suite is a key architectural boundary: it validates that the large rule corpus and many scanner types remain consistent as the system evolves.
13. Overall data flow to diagram
- Input arrives as a local path, a git repo, or a configured project workspace.
- The engine discovers candidate files, selects scanners by file type/threat domain, optionally invokes external analyzers, aggregates and normalizes findings, applies false-positive filters and sanitization, then emits one or more report formats.
- The main trust boundaries are: repository contents, optional external tools, cached results, and rendered reports.
Main entry points: cli.py CLI · __init__.py Scanner registry · system.py System · fp_filter.py FP filter
Components 21
CLI & config
Command entrypoints and project configuration
Scan engine
Orchestration, filtering, normalization, and reporting
- System · Coordinates scan boundaries, sizing, and execution
medusa/core/system.py - Parallel · Dispatches scan work across workers
medusa/core/parallel.py - FP filter · Applies repo-specific and universal false-positive filtering
medusa/core/fp_filter.py - FP patterns · Suppression pattern corpus applied after raw findings
medusa/core/fp_patterns/_universal.yaml - Sanitizers · Obfuscates dangerous payloads and normalizes output for reporting
medusa/core/output_sanitizer.py - Reporter · Turns normalized findings into user-facing outputs
medusa/core/reporter.py - Report assets · Bundles static assets used by richer reports
medusa/core/report_assets.py
Scanners
Representative scanner families and registry
- Scanner registry · Registers scanners for selection by file type or threat area
medusa/scanners/__init__.py - Scanner base · Defines the common scanner interface
medusa/scanners/base.py - Lang scanners · Representative wrappers for code, config, and supply-chain formats
medusa/scanners/python_scanner.py - AI scanners · Threat-model-driven scanners for prompts, agents, MCP, RAG, and tool use
medusa/scanners/prompt_injection_code_scanner.py - External tools · Wraps tools like semgrep, trivy, gitleaks, and others when available
medusa/scanners/semgrep_scanner.py - YAML rules · Interprets and scans YAML-based rule content
medusa/scanners/yaml_rule_scanner.py
Rules corpus
YAML-driven detection content and suppression patterns
- Rules corpus · Threat-area rule sets for AI security, CVEs, RAG, MCP, jailbreaks, and more
medusa/rules/__init__.py
Platform & install
Environment detection, installation, caching, and IDE support
- Tool cache · Content-based cache for skipping unchanged work
medusa/platform/tool_cache.py - Platform · Environment detection and version management
medusa/platform/detector.py - Installers · Cross-platform and OS-specific install flows for optional tools
medusa/platform/installers/base.py - IDE helpers · Helpers for Claude Code and workspace backups
medusa/ide/claude_code.py
Connections 22
- medusa → CLI: starts · CLI entrypoint hands control to command parsing
- CLI → Config: loads · Commands read workspace configuration and scan settings
- CLI → Platform: bootstraps · Initializes environment and tool availability checks
- CLI → System: runs · Scan commands enter the core orchestration layer
- System → Parallel: fans out · Scan coordination distributes work across workers
- System → Scanner registry: selects · Uses the registry to choose relevant scanners
- Scanner registry → Scanner base: implements · Registered scanners conform to the scanner contract
- Scanner registry → Lang scanners: registers · File/type-driven analyzers are auto-registered
- Scanner registry → AI scanners: registers · Threat-model-driven analyzers are auto-registered
- Scanner registry → External tools: registers · Optional external-tool wrappers are available through the same registry
- Scanner registry → YAML rules: registers · Rule-file scanning is also exposed as a scanner
- YAML rules → Rules corpus: reads · Scans and interprets rule content from the corpus
- Lang scanners → External tools: invokes · Some language scanners delegate to optional tools
- AI scanners → Rules corpus: uses · AI/security scanners are largely driven by YAML rules
- System → Tool cache: skips · Incremental scanning can reuse cached results
- System → FP filter: filters · Raw findings are reduced by false-positive logic
- FP filter → FP patterns: applies · Filter logic uses suppression pattern packs
- FP filter → Sanitizers: normalizes · Filtered findings are sanitized before reporting
- Sanitizers → Reporter: feeds · Safe normalized issues are rendered into reports
- Reporter → Report assets: packages · HTML-style reporting can bundle static assets
- CLI → Installers: manages · Install commands manage optional tool setup
- CLI → IDE helpers: integrates · CLI can support IDE assistant integration workflows