# pantheon-security/medusa architecture

> Architecture diagram of the GitHub repository pantheon-security/medusa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pantheon-security/medusa
- Repository: https://github.com/pantheon-security/medusa

## Overview

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: [`medusa/cli.py`](https://github.com/pantheon-security/medusa/blob/main/medusa/cli.py) (CLI), [`medusa/scanners/__init__.py`](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/__init__.py) (Scanner registry), [`medusa/core/system.py`](https://github.com/pantheon-security/medusa/blob/main/medusa/core/system.py) (System), [`medusa/core/fp_filter.py`](https://github.com/pantheon-security/medusa/blob/main/medusa/core/fp_filter.py) (FP filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI & config"]
  node_n_main(("medusa<br/>entrypoint<br/>[__main__.py]"))
  node_n_cli["CLI<br/>commands<br/>[cli.py]"]
  node_n_config["Config<br/>[config.py]"]
end

subgraph group_grp_engine["Scan engine"]
  node_n_system["System<br/>scan coordinator<br/>[system.py]"]
  node_n_parallel["Parallel<br/>worker fanout<br/>[parallel.py]"]
  node_n_fp["FP filter<br/>suppression<br/>[fp_filter.py]"]
  node_n_patterns["FP patterns<br/>pattern packs<br/>[_universal.yaml]"]
  node_n_sanitize["Sanitizers<br/>output safety"]
  node_n_reporter["Reporter<br/>rendering<br/>[reporter.py]"]
  node_n_assets["Report assets<br/>html assets<br/>[report_assets.py]"]
end

subgraph group_grp_scanners["Scanners"]
  node_n_registry["Scanner registry<br/>auto-registry<br/>[__init__.py]"]
  node_n_base["Scanner base<br/>contract<br/>[base.py]"]
  node_n_lang["Lang scanners<br/>file analyzers<br/>[python_scanner.py]"]
  node_n_ai["AI scanners<br/>threat analyzers"]
  node_n_external["External tools<br/>optional analyzers<br/>[semgrep_scanner.py]"]
  node_n_yamlrule["YAML rules<br/>rule scanner"]
end

subgraph group_grp_rules["Rules corpus"]
  node_n_rules[("Rules corpus<br/>yaml detections<br/>[__init__.py]")]
end

subgraph group_grp_platform["Platform & install"]
  node_n_cache[("Tool cache<br/>incremental cache<br/>[tool_cache.py]")]
  node_n_platform["Platform<br/>bootstrap<br/>[detector.py]"]
  node_n_install["Installers<br/>[base.py]"]
  node_n_ide["IDE helpers<br/>integration<br/>[claude_code.py]"]
end

node_n_main -->|"starts"| node_n_cli
node_n_cli -->|"loads"| node_n_config
node_n_cli -->|"bootstraps"| node_n_platform
node_n_cli -->|"runs"| node_n_system
node_n_system -->|"fans out"| node_n_parallel
node_n_system -->|"selects"| node_n_registry
node_n_registry -->|"implements"| node_n_base
node_n_registry -->|"registers"| node_n_lang
node_n_registry -->|"registers"| node_n_ai
node_n_registry -->|"registers"| node_n_external
node_n_registry -->|"registers"| node_n_yamlrule
node_n_yamlrule -->|"reads"| node_n_rules
node_n_lang -->|"invokes"| node_n_external
node_n_ai -->|"uses"| node_n_rules
node_n_system -->|"skips"| node_n_cache
node_n_system -->|"filters"| node_n_fp
node_n_fp -->|"applies"| node_n_patterns
node_n_fp -->|"normalizes"| node_n_sanitize
node_n_sanitize -->|"feeds"| node_n_reporter
node_n_reporter -->|"packages"| node_n_assets
node_n_cli -->|"manages"| node_n_install
node_n_cli -->|"integrates"| node_n_ide

click node_n_main "https://github.com/pantheon-security/medusa/blob/main/medusa/__main__.py"
click node_n_cli "https://github.com/pantheon-security/medusa/blob/main/medusa/cli.py"
click node_n_config "https://github.com/pantheon-security/medusa/blob/main/medusa/config.py"
click node_n_system "https://github.com/pantheon-security/medusa/blob/main/medusa/core/system.py"
click node_n_parallel "https://github.com/pantheon-security/medusa/blob/main/medusa/core/parallel.py"
click node_n_registry "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/__init__.py"
click node_n_base "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/base.py"
click node_n_lang "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/python_scanner.py"
click node_n_ai "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/prompt_injection_code_scanner.py"
click node_n_external "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/semgrep_scanner.py"
click node_n_yamlrule "https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/yaml_rule_scanner.py"
click node_n_rules "https://github.com/pantheon-security/medusa/blob/main/medusa/rules/__init__.py"
click node_n_fp "https://github.com/pantheon-security/medusa/blob/main/medusa/core/fp_filter.py"
click node_n_patterns "https://github.com/pantheon-security/medusa/blob/main/medusa/core/fp_patterns/_universal.yaml"
click node_n_sanitize "https://github.com/pantheon-security/medusa/blob/main/medusa/core/output_sanitizer.py"
click node_n_reporter "https://github.com/pantheon-security/medusa/blob/main/medusa/core/reporter.py"
click node_n_assets "https://github.com/pantheon-security/medusa/blob/main/medusa/core/report_assets.py"
click node_n_cache "https://github.com/pantheon-security/medusa/blob/main/medusa/platform/tool_cache.py"
click node_n_platform "https://github.com/pantheon-security/medusa/blob/main/medusa/platform/detector.py"
click node_n_install "https://github.com/pantheon-security/medusa/blob/main/medusa/platform/installers/base.py"
click node_n_ide "https://github.com/pantheon-security/medusa/blob/main/medusa/ide/claude_code.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_cli,node_n_config toneBlue
class node_n_system,node_n_parallel,node_n_fp,node_n_patterns,node_n_sanitize,node_n_reporter,node_n_assets toneAmber
class node_n_registry,node_n_base,node_n_lang,node_n_ai,node_n_external,node_n_yamlrule toneMint
class node_n_rules toneRose
class node_n_cache,node_n_platform,node_n_install,node_n_ide toneIndigo
```

## Components

### CLI & config

Command entrypoints and project configuration

- [medusa](https://github.com/pantheon-security/medusa/blob/main/medusa/__main__.py): entrypoint · Package entrypoint for the CLI app · `medusa/__main__.py`
- [CLI](https://github.com/pantheon-security/medusa/blob/main/medusa/cli.py): commands · Parses commands like scan, init, and install · `medusa/cli.py`
- [Config](https://github.com/pantheon-security/medusa/blob/main/medusa/config.py): project config · Loads .medusa.yml and scan settings · `medusa/config.py`

### Scan engine

Orchestration, filtering, normalization, and reporting

- [System](https://github.com/pantheon-security/medusa/blob/main/medusa/core/system.py): scan coordinator · Coordinates scan boundaries, sizing, and execution · `medusa/core/system.py`
- [Parallel](https://github.com/pantheon-security/medusa/blob/main/medusa/core/parallel.py): worker fanout · Dispatches scan work across workers · `medusa/core/parallel.py`
- [FP filter](https://github.com/pantheon-security/medusa/blob/main/medusa/core/fp_filter.py): suppression · Applies repo-specific and universal false-positive filtering · `medusa/core/fp_filter.py`
- [FP patterns](https://github.com/pantheon-security/medusa/blob/main/medusa/core/fp_patterns/_universal.yaml): pattern packs · Suppression pattern corpus applied after raw findings · `medusa/core/fp_patterns/_universal.yaml`
- [Sanitizers](https://github.com/pantheon-security/medusa/blob/main/medusa/core/output_sanitizer.py): output safety · Obfuscates dangerous payloads and normalizes output for reporting · `medusa/core/output_sanitizer.py`
- [Reporter](https://github.com/pantheon-security/medusa/blob/main/medusa/core/reporter.py): rendering · Turns normalized findings into user-facing outputs · `medusa/core/reporter.py`
- [Report assets](https://github.com/pantheon-security/medusa/blob/main/medusa/core/report_assets.py): html assets · Bundles static assets used by richer reports · `medusa/core/report_assets.py`

### Scanners

Representative scanner families and registry

- [Scanner registry](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/__init__.py): auto-registry · Registers scanners for selection by file type or threat area · `medusa/scanners/__init__.py`
- [Scanner base](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/base.py): contract · Defines the common scanner interface · `medusa/scanners/base.py`
- [Lang scanners](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/python_scanner.py): file analyzers · Representative wrappers for code, config, and supply-chain formats · `medusa/scanners/python_scanner.py`
- [AI scanners](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/prompt_injection_code_scanner.py): threat analyzers · Threat-model-driven scanners for prompts, agents, MCP, RAG, and tool use · `medusa/scanners/prompt_injection_code_scanner.py`
- [External tools](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/semgrep_scanner.py): optional analyzers · Wraps tools like semgrep, trivy, gitleaks, and others when available · `medusa/scanners/semgrep_scanner.py`
- [YAML rules](https://github.com/pantheon-security/medusa/blob/main/medusa/scanners/yaml_rule_scanner.py): rule scanner · Interprets and scans YAML-based rule content · `medusa/scanners/yaml_rule_scanner.py`

### Rules corpus

YAML-driven detection content and suppression patterns

- [Rules corpus](https://github.com/pantheon-security/medusa/blob/main/medusa/rules/__init__.py): yaml detections · 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](https://github.com/pantheon-security/medusa/blob/main/medusa/platform/tool_cache.py): incremental cache · Content-based cache for skipping unchanged work · `medusa/platform/tool_cache.py`
- [Platform](https://github.com/pantheon-security/medusa/blob/main/medusa/platform/detector.py): bootstrap · Environment detection and version management · `medusa/platform/detector.py`
- [Installers](https://github.com/pantheon-security/medusa/blob/main/medusa/platform/installers/base.py): os installers · Cross-platform and OS-specific install flows for optional tools · `medusa/platform/installers/base.py`
- [IDE helpers](https://github.com/pantheon-security/medusa/blob/main/medusa/ide/claude_code.py): integration · Helpers for Claude Code and workspace backups · `medusa/ide/claude_code.py`

## Connections

- 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