# google/mantis architecture

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

- Interactive diagram: https://gitdiagram.com/google/mantis
- Repository: https://github.com/google/mantis

## Overview

Mantis is an ADK-based harness for autonomous, human-reviewed security research. Its main workflow accepts a file or repository and optional focus, plans and executes agent research, records findings, then supports verification, remediation, and reporting. The README also describes history review, semantic navigation, threat modeling, exploit chaining, iteration learning, and secure-development advice. Relationships shown from source are limited by partial excerpts; other capability links use the README’s documented workflow rather than implying unsampled calls.

Main entry points: [`reference/main.py`](https://github.com/google/mantis/blob/main/reference/main.py) (Campaign orchestrator), [`reference/tools/research_tools.py`](https://github.com/google/mantis/blob/main/reference/tools/research_tools.py) (Research agents and tools), [`reference/scripts/launch.py`](https://github.com/google/mantis/blob/main/reference/scripts/launch.py) (Campaign launcher), [`reference/core/synthesizer.py`](https://github.com/google/mantis/blob/main/reference/core/synthesizer.py) (Graph synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Campaign entry"]
  node_launcher["Campaign launcher<br/>[launch.py]"]
  node_campaign["Campaign orchestrator<br/>[main.py]"]
  node_configuration["Configuration<br/>[config.py]"]
end

subgraph group_research["Research planning"]
  node_surveyor["Code survey<br/>[surveyor.py]"]
  node_planner["Research planner<br/>[planner.py]"]
  node_graph_synthesis["Graph synthesis<br/>[synthesizer.py]"]
  node_graph_loader["Agent graph loader<br/>[graph_loader.py]"]
end

subgraph group_execution["Agent execution"]
  node_research_agents["Research agents and tools<br/>[research_tools.py]"]
  node_llm["LLM gateway<br/>[llm_gateway.py]"]
  node_sandbox_tools["Sandbox tools<br/>[sandbox_tools.py]"]
  node_environments["Execution environments"]
  node_run_context["Run context<br/>[context.py]"]
end

subgraph group_validation["Finding validation"]
  node_evidence["Evidence capture<br/>[evidence.py]"]
  node_finding_store[("Finding store<br/>[database.py]")]
  node_deduplication["Finding deduplication<br/>[database.py]"]
  node_correlation["Vulnerability correlation<br/>[correlator.py]"]
  node_risk_calibration["Risk calibration<br/>[cost.py]"]
end

subgraph group_outcomes["Remediation and learning"]
  node_patching["Patch and verification<br/>[sandbox_tools.py]"]
  node_reporting["Reports and SARIF<br/>[sarif.py]"]
  node_memory[("Iteration memory<br/>[memory.py]")]
  node_secure_advice["Secure-development advice<br/>[advise.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts campaign"| node_launcher
node_launcher -->|"launches"| node_campaign
node_campaign -->|"loads settings"| node_configuration
node_campaign -->|"surveys target"| node_surveyor
node_campaign -->|"plans research"| node_planner
node_campaign -->|"synthesizes graph"| node_graph_synthesis
node_graph_synthesis -->|"loads topology"| node_graph_loader
node_campaign -->|"loads agents"| node_graph_loader
node_campaign -->|"runs research"| node_research_agents
node_research_agents -->|"requests analysis"| node_llm
node_research_agents -->|"records findings"| node_finding_store
node_research_agents -->|"requests execution"| node_sandbox_tools
node_sandbox_tools -->|"executes in"| node_environments
node_environments -->|"uses active context"| node_run_context
node_campaign -.->|"verifies findings"| node_evidence
node_campaign -.->|"deduplicates findings"| node_deduplication
node_campaign -.->|"builds exploit chains"| node_correlation
node_campaign -.->|"calibrates severity"| node_risk_calibration
node_campaign -.->|"patches and verifies"| node_patching
node_campaign -.->|"produces reports"| node_reporting
node_campaign -.->|"reflects learnings"| node_memory
node_operator -.->|"requests advice"| node_secure_advice

click node_launcher "https://github.com/google/mantis/blob/main/reference/scripts/launch.py"
click node_campaign "https://github.com/google/mantis/blob/main/reference/main.py"
click node_configuration "https://github.com/google/mantis/blob/main/reference/core/config.py"
click node_surveyor "https://github.com/google/mantis/blob/main/reference/core/surveyor.py"
click node_planner "https://github.com/google/mantis/blob/main/reference/core/planner.py"
click node_graph_synthesis "https://github.com/google/mantis/blob/main/reference/core/synthesizer.py"
click node_graph_loader "https://github.com/google/mantis/blob/main/reference/core/graph_loader.py"
click node_research_agents "https://github.com/google/mantis/blob/main/reference/tools/research_tools.py"
click node_llm "https://github.com/google/mantis/blob/main/reference/core/llm_gateway.py"
click node_sandbox_tools "https://github.com/google/mantis/blob/main/reference/tools/sandbox_tools.py"
click node_environments "https://github.com/google/mantis/tree/main/reference/core/environments"
click node_run_context "https://github.com/google/mantis/blob/main/reference/core/context.py"
click node_evidence "https://github.com/google/mantis/blob/main/reference/core/evidence.py"
click node_finding_store "https://github.com/google/mantis/blob/main/reference/core/database.py"
click node_deduplication "https://github.com/google/mantis/blob/main/reference/core/database.py"
click node_correlation "https://github.com/google/mantis/blob/main/reference/core/correlator.py"
click node_risk_calibration "https://github.com/google/mantis/blob/main/reference/core/cost.py"
click node_patching "https://github.com/google/mantis/blob/main/reference/tools/sandbox_tools.py"
click node_reporting "https://github.com/google/mantis/blob/main/reference/core/sarif.py"
click node_memory "https://github.com/google/mantis/blob/main/reference/core/memory.py"
click node_secure_advice "https://github.com/google/mantis/blob/main/reference/scripts/advise.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_launcher,node_campaign,node_configuration toneBlue
class node_surveyor,node_planner,node_graph_synthesis,node_graph_loader toneAmber
class node_research_agents,node_llm,node_sandbox_tools,node_environments,node_run_context toneMint
class node_evidence,node_finding_store,node_deduplication,node_correlation,node_risk_calibration toneRose
class node_patching,node_reporting,node_memory,node_secure_advice,node_operator toneIndigo
```

## Components

### Campaign entry

- [Campaign launcher](https://github.com/google/mantis/blob/main/reference/scripts/launch.py): `reference/scripts/launch.py`
- [Campaign orchestrator](https://github.com/google/mantis/blob/main/reference/main.py): `reference/main.py`
- [Configuration](https://github.com/google/mantis/blob/main/reference/core/config.py): `reference/core/config.py`

### Research planning

- [Code survey](https://github.com/google/mantis/blob/main/reference/core/surveyor.py): `reference/core/surveyor.py`
- [Research planner](https://github.com/google/mantis/blob/main/reference/core/planner.py): `reference/core/planner.py`
- [Graph synthesis](https://github.com/google/mantis/blob/main/reference/core/synthesizer.py): `reference/core/synthesizer.py`
- [Agent graph loader](https://github.com/google/mantis/blob/main/reference/core/graph_loader.py): `reference/core/graph_loader.py`

### Agent execution

- [Research agents and tools](https://github.com/google/mantis/blob/main/reference/tools/research_tools.py): `reference/tools/research_tools.py`
- [LLM gateway](https://github.com/google/mantis/blob/main/reference/core/llm_gateway.py): `reference/core/llm_gateway.py`
- [Sandbox tools](https://github.com/google/mantis/blob/main/reference/tools/sandbox_tools.py): `reference/tools/sandbox_tools.py`
- [Execution environments](https://github.com/google/mantis/tree/main/reference/core/environments): `reference/core/environments`
- [Run context](https://github.com/google/mantis/blob/main/reference/core/context.py): `reference/core/context.py`

### Finding validation

- [Evidence capture](https://github.com/google/mantis/blob/main/reference/core/evidence.py): `reference/core/evidence.py`
- [Finding store](https://github.com/google/mantis/blob/main/reference/core/database.py): `reference/core/database.py`
- [Finding deduplication](https://github.com/google/mantis/blob/main/reference/core/database.py): `reference/core/database.py`
- [Vulnerability correlation](https://github.com/google/mantis/blob/main/reference/core/correlator.py): `reference/core/correlator.py`
- [Risk calibration](https://github.com/google/mantis/blob/main/reference/core/cost.py): `reference/core/cost.py`

### Remediation and learning

- [Patch and verification](https://github.com/google/mantis/blob/main/reference/tools/sandbox_tools.py): `reference/tools/sandbox_tools.py`
- [Reports and SARIF](https://github.com/google/mantis/blob/main/reference/core/sarif.py): `reference/core/sarif.py`
- [Iteration memory](https://github.com/google/mantis/blob/main/reference/core/memory.py): `reference/core/memory.py`
- [Secure-development advice](https://github.com/google/mantis/blob/main/reference/scripts/advise.py): `reference/scripts/advise.py`

### Other components

- **Operator**

## Connections

- Operator → Campaign launcher: starts campaign
- Campaign launcher → Campaign orchestrator: launches (evidence: `reference/scripts/launch.py`)
- Campaign orchestrator → Configuration: loads settings (evidence: `reference/main.py`)
- Campaign orchestrator → Code survey: surveys target (evidence: `reference/main.py`)
- Campaign orchestrator → Research planner: plans research (evidence: `reference/main.py`)
- Campaign orchestrator → Graph synthesis: synthesizes graph (evidence: `reference/main.py`)
- Graph synthesis → Agent graph loader: loads topology (evidence: `reference/core/synthesizer.py`)
- Campaign orchestrator → Agent graph loader: loads agents (evidence: `reference/main.py`)
- Campaign orchestrator → Research agents and tools: runs research (evidence: `reference/main.py`)
- Research agents and tools → LLM gateway: requests analysis (evidence: `reference/tools/research_tools.py`)
- Research agents and tools → Finding store: records findings (evidence: `reference/tools/research_tools.py`)
- Research agents and tools → Sandbox tools: requests execution (evidence: `reference/tools/__init__.py`)
- Sandbox tools → Execution environments: executes in (evidence: `reference/tools/sandbox_tools.py`)
- Execution environments → Run context: uses active context (evidence: `reference/core/environments/base.py`)
- Campaign orchestrator → Evidence capture: verifies findings (evidence: `reference/main.py`)
- Campaign orchestrator → Finding deduplication: deduplicates findings (evidence: `reference/main.py`)
- Campaign orchestrator → Vulnerability correlation: builds exploit chains (evidence: `reference/main.py`)
- Campaign orchestrator → Risk calibration: calibrates severity (evidence: `reference/main.py`)
- Campaign orchestrator → Patch and verification: patches and verifies
- Campaign orchestrator → Reports and SARIF: produces reports (evidence: `reference/main.py`)
- Campaign orchestrator → Iteration memory: reflects learnings (evidence: `reference/main.py`)
- Operator → Secure-development advice: requests advice
