# athenasec/project-typhon architecture

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

- Interactive diagram: https://gitdiagram.com/athenasec/project-typhon
- Repository: https://github.com/athenasec/project-typhon

## Overview

#### Purpose and execution model
Project Typhon is a proof-of-concept LLM red-team and EU AI Act audit workflow. A CLI executes curated attacks against an HTTP chatbot, uses an LLM judge to classify outcomes, and is structured to persist findings, map them to regulations, and render an HTML report. The current working path is the target agent plus red-team runner/judge; downstream persistence and reporting are planned.

#### Primary entry points
- The orchestrator is `cli.py`, invoked as `python cli.py run --target <URL> --packs <dir>`.
- The mock target is a FastAPI application served from `target_agent/main.py` via Uvicorn.
- Container-oriented local deployment is represented by `docker-compose.yml`.
- Provider credentials, target model, and target prompt location are environment-controlled through `.env.example`.

#### Target-agent boundary
The target is deliberately isolated as an HTTP-served chatbot, allowing the attack engine to target either the bundled mock or a partner staging endpoint without changing core attack logic.
- `target_agent/main.py` exposes the FastAPI target behavior.
- `target_agent/system_prompt.txt` supplies the intentionally weak system prompt.
- `llm_client.py` is the provider-agnostic model access layer, supporting DeepSeek, OpenAI, and Anthropic configurations.

#### Red-team execution pipeline
The engine loads attack definitions, sends their prompts to the target URL, gathers responses, and judges whether each attempt exposed a vulnerability.
- `redteam_engine/runner.py` owns attack-pack execution and target interaction.
- `redteam_engine/judge.py` performs LLM-as-judge pass/fail assessment.
- `redteam_engine/schemas.py` defines the typed contracts between packs, runner, and judge.
This separates untrusted target output and attack content from the evaluator’s structured finding decision.

#### Attack-pack content boundary
Attack scenarios are data-driven YAML assets rather than hard-coded workflows, so categories can be expanded without redesigning the runner.
- `redteam_engine/attack_packs/prompt_injection.yaml`
- `redteam_engine/attack_packs/impersonation.yaml`
The packs directory passed to the CLI is the discovery boundary for a run.

#### Findings, compliance, and reporting path
The intended downstream flow is: judged findings → run/finding storage → AI Act article mapping → audit-style HTML report.
- `observability/store.py` is the planned SQLite persistence boundary.
- `compliance/mapper.py` and `compliance/article_map.yaml` map findings to EU AI Act articles.
- `compliance/report_generator.py` renders output using `compliance/templates/report.html`, with generated artifacts intended for `reports/`.
These components exist in the repository but are identified as not yet implemented in the project status.

#### Runtime and external dependencies
The runtime is Python 3.14 with `uv` dependency management (`pyproject.toml`, `uv.lock`). The target is FastAPI/Uvicorn; target and judge model calls depend on configured external LLM providers and their API keys. SQLite is the planned local observability store, avoiding a required remote database for the PoC.

Main entry points: [`redteam_engine/runner.py`](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/runner.py) (Attack runner), [`target_agent/main.py`](https://github.com/athenasec/project-typhon/blob/main/target_agent/main.py) (Mock target API), [`redteam_engine/attack_packs`](https://github.com/athenasec/project-typhon/tree/main/redteam_engine/attack_packs) (Attack-pack directory), [`redteam_engine/judge.py`](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/judge.py) (LLM judge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Red-team execution"]
  node_cli["CLI orchestrator<br/>Python CLI<br/>[cli.py]"]
  node_packs["Attack-pack directory<br/>YAML scenarios"]
  node_prompt_injection["Prompt injection pack<br/>attack pack"]
  node_impersonation["Impersonation pack<br/>attack pack<br/>[impersonation.yaml]"]
  node_runner["Attack runner<br/>execution engine<br/>[runner.py]"]
  node_schemas["Typed contracts<br/>schemas<br/>[schemas.py]"]
  node_judge["LLM judge<br/>evaluator<br/>[judge.py]"]
end

subgraph group_target["Target boundary"]
  node_target_api["Mock target API<br/>FastAPI service<br/>[main.py]"]
  node_system_prompt["Weak system prompt<br/>prompt asset<br/>[system_prompt.txt]"]
  node_llm_client["Model access layer<br/>LLM client<br/>[llm_client.py]"]
  node_compose["Local deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
end

subgraph group_audit["Planned audit output"]
  node_store[("Findings store<br/>SQLite persistence<br/>[store.py]")]
  node_mapper["AI Act mapper<br/>compliance mapping<br/>[mapper.py]"]
  node_article_map["AI Act article map<br/>mapping data<br/>[article_map.yaml]"]
  node_report_generator["HTML report generator<br/>reporting"]
  node_report_template["Report template<br/>HTML template<br/>[report.html]"]
  node_reports["Generated reports<br/>report artifacts"]
end

node_providers{{"LLM providers<br/>external APIs"}}

node_cli -->|"selects"| node_packs
node_packs -->|"contains"| node_prompt_injection
node_packs -->|"contains"| node_impersonation
node_cli -->|"starts"| node_runner
node_runner -->|"uses"| node_schemas
node_runner -->|"sends attack prompts over HTTP"| node_target_api
node_target_api -->|"uses"| node_system_prompt
node_target_api -->|"requests model output"| node_llm_client
node_judge -->|"requests evaluation"| node_llm_client
node_llm_client -->|"calls"| node_providers
node_runner -->|"submits target responses"| node_judge
node_compose -->|"deploys"| node_target_api
node_judge -.->|"judged findings"| node_store
node_store -.->|"stored findings"| node_mapper
node_article_map -.->|"article rules"| node_mapper
node_mapper -.->|"mapped findings"| node_report_generator
node_report_template -.->|"renders with"| node_report_generator
node_report_generator -.->|"writes HTML"| node_reports

click node_cli "https://github.com/athenasec/project-typhon/blob/main/cli.py"
click node_packs "https://github.com/athenasec/project-typhon/tree/main/redteam_engine/attack_packs"
click node_prompt_injection "https://github.com/athenasec/project-typhon/blob/main/redteam_engine/attack_packs/prompt_injection.yaml"
click node_impersonation "https://github.com/athenasec/project-typhon/blob/main/redteam_engine/attack_packs/impersonation.yaml"
click node_runner "https://github.com/athenasec/project-typhon/blob/main/redteam_engine/runner.py"
click node_schemas "https://github.com/athenasec/project-typhon/blob/main/redteam_engine/schemas.py"
click node_judge "https://github.com/athenasec/project-typhon/blob/main/redteam_engine/judge.py"
click node_target_api "https://github.com/athenasec/project-typhon/blob/main/target_agent/main.py"
click node_system_prompt "https://github.com/athenasec/project-typhon/blob/main/target_agent/system_prompt.txt"
click node_llm_client "https://github.com/athenasec/project-typhon/blob/main/llm_client.py"
click node_compose "https://github.com/athenasec/project-typhon/blob/main/docker-compose.yml"
click node_store "https://github.com/athenasec/project-typhon/blob/main/observability/store.py"
click node_mapper "https://github.com/athenasec/project-typhon/blob/main/compliance/mapper.py"
click node_article_map "https://github.com/athenasec/project-typhon/blob/main/compliance/article_map.yaml"
click node_report_generator "https://github.com/athenasec/project-typhon/blob/main/compliance/report_generator.py"
click node_report_template "https://github.com/athenasec/project-typhon/blob/main/compliance/templates/report.html"

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_cli,node_packs,node_prompt_injection,node_impersonation,node_runner,node_schemas,node_judge toneBlue
class node_target_api,node_system_prompt,node_llm_client,node_compose toneAmber
class node_store,node_mapper,node_article_map,node_report_generator,node_report_template,node_reports toneMint
class node_providers toneNeutral
```

## Components

### Red-team execution

- [CLI orchestrator](https://github.com/athenasec/project-typhon/blob/main/cli.py): Python CLI · Runs attacks against a target URL and packs directory. · `cli.py`
- [Attack-pack directory](https://github.com/athenasec/project-typhon/tree/main/redteam_engine/attack_packs): YAML scenarios · Discovery boundary for data-driven attacks. · `redteam_engine/attack_packs`
- [Prompt injection pack](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/attack_packs/prompt_injection.yaml): attack pack · `redteam_engine/attack_packs/prompt_injection.yaml`
- [Impersonation pack](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/attack_packs/impersonation.yaml): attack pack · `redteam_engine/attack_packs/impersonation.yaml`
- [Attack runner](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/runner.py): execution engine · Loads packs, calls the target, and gathers responses. · `redteam_engine/runner.py`
- [Typed contracts](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/schemas.py): schemas · Contracts shared by packs, runner, and judge. · `redteam_engine/schemas.py`
- [LLM judge](https://github.com/athenasec/project-typhon/blob/main/redteam_engine/judge.py): evaluator · Classifies attack outcomes into findings. · `redteam_engine/judge.py`

### Target boundary

HTTP chatbot can be bundled or remote.

- [Mock target API](https://github.com/athenasec/project-typhon/blob/main/target_agent/main.py): FastAPI service · HTTP-served intentionally weak chatbot. · `target_agent/main.py`
- [Weak system prompt](https://github.com/athenasec/project-typhon/blob/main/target_agent/system_prompt.txt): prompt asset · `target_agent/system_prompt.txt`
- [Model access layer](https://github.com/athenasec/project-typhon/blob/main/llm_client.py): LLM client · Provider-agnostic access for target and judge models. · `llm_client.py`
- [Local deployment](https://github.com/athenasec/project-typhon/blob/main/docker-compose.yml): Docker Compose · Container-oriented local target deployment. · `docker-compose.yml`

### Planned audit output

Present but not yet implemented.

- [Findings store](https://github.com/athenasec/project-typhon/blob/main/observability/store.py): SQLite persistence · Planned run and finding storage boundary. · `observability/store.py`
- [AI Act mapper](https://github.com/athenasec/project-typhon/blob/main/compliance/mapper.py): compliance mapping · Planned finding-to-article mapping. · `compliance/mapper.py`
- [AI Act article map](https://github.com/athenasec/project-typhon/blob/main/compliance/article_map.yaml): mapping data · `compliance/article_map.yaml`
- [HTML report generator](https://github.com/athenasec/project-typhon/blob/main/compliance/report_generator.py): reporting · Planned audit-style report renderer. · `compliance/report_generator.py`
- [Report template](https://github.com/athenasec/project-typhon/blob/main/compliance/templates/report.html): HTML template · `compliance/templates/report.html`
- **Generated reports**: report artifacts

### Other components

- **LLM providers**: external APIs · DeepSeek, OpenAI, or Anthropic.

## Connections

- CLI orchestrator → Attack-pack directory: selects
- Attack-pack directory → Prompt injection pack: contains
- Attack-pack directory → Impersonation pack: contains
- CLI orchestrator → Attack runner: starts
- Attack runner → Typed contracts: uses
- Attack runner → Mock target API: sends attack prompts over HTTP
- Mock target API → Weak system prompt: uses
- Mock target API → Model access layer: requests model output
- LLM judge → Model access layer: requests evaluation
- Model access layer → LLM providers: calls
- Attack runner → LLM judge: submits target responses
- Local deployment → Mock target API: deploys
- LLM judge → Findings store: judged findings
- Findings store → AI Act mapper: stored findings
- AI Act article map → AI Act mapper: article rules
- AI Act mapper → HTML report generator: mapped findings
- Report template → HTML report generator: renders with
- HTML report generator → Generated reports: writes HTML