# pdmiv/harp architecture

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

- Interactive diagram: https://gitdiagram.com/pdmiv/harp
- Repository: https://github.com/pdmiv/harp

## Overview

HARP is an authorized-lab penetration-testing prototype. Operators configure a target and runtime in the dashboard or connect Codex through MCP; the runner performs reconnaissance, coordinates oracle planning and proxy actions, validates and executes commands in Kali, and retains evidence and outcomes. Additional branches support Whippet AD analysis, bounded CVE/web research, replay, and settings snapshots. The graph follows README workflows and shown import/reference evidence; several subsystem internals are unsampled, so uncertain links are omitted.

Main entry points: [`harp.py`](https://github.com/pdmiv/harp/blob/main/harp.py) (Lab runner), [`harp_web.py`](https://github.com/pdmiv/harp/blob/main/harp_web.py) (HARP dashboard), [`harp_mcp.py`](https://github.com/pdmiv/harp/blob/main/harp_mcp.py) (Codex MCP), [`harp_whippet.py`](https://github.com/pdmiv/harp/blob/main/harp_whippet.py) (Whippet AD analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Operator interfaces"]
  node_dashboard["HARP dashboard<br/>[harp_web.py]"]
  node_codex["Codex MCP<br/>[harp_mcp.py]"]
end

subgraph group_session["Session orchestration"]
  node_runner["Lab runner<br/>[harp.py]"]
  node_recon["Deterministic recon<br/>[harp.py]"]
  node_command_guard["Command validation<br/>[harp.py]"]
  node_kali["Kali runtime"]
end

subgraph group_analysis["Evidence and research"]
  node_evidence["Capability evidence<br/>[harp_evidence.py]"]
  node_strategy["Planning checks<br/>[harp_strategy.py]"]
  node_research["CVE and web research<br/>[harp_research.py]"]
  node_whippet["Whippet AD analysis<br/>[harp_whippet.py]"]
  node_batch["Whippet batch queries"]
end

subgraph group_models["Model integrations"]
  node_oracle["Oracle planning<br/>[harp_nim.py]"]
  node_proxy["Proxy model<br/>[harp.py]"]
  node_openai["OpenAI transport<br/>[harp_openai.py]"]
  node_zai["Z.AI transport<br/>[harp_zai.py]"]
  node_nim["NVIDIA NIM transport<br/>[harp_nim.py]"]
end

subgraph group_records["Session records"]
  node_artifacts["Flags and artifacts<br/>[harp_artifacts.py]"]
  node_replay["Session replay<br/>[harp_replay.py]"]
  node_snapshots["Settings snapshots<br/>[harp_snapshots.py]"]
  node_archive["Session archive"]
end

node_operator(("Operator"))

node_operator -->|"configures and starts"| node_dashboard
node_operator -->|"connects via"| node_codex
node_dashboard -->|"starts sessions"| node_runner
node_codex -->|"uses session tools"| node_runner
node_runner -->|"performs"| node_recon
node_runner -->|"requests plans"| node_oracle
node_runner -->|"delegates objectives"| node_proxy
node_runner -->|"validates commands"| node_command_guard
node_command_guard -->|"permits execution"| node_kali
node_runner -->|"calls when selected"| node_openai
node_runner -->|"calls when selected"| node_zai
node_runner -->|"calls when selected"| node_nim
node_runner -->|"updates evidence"| node_evidence
node_runner -->|"uses planning checks"| node_strategy
node_runner -->|"uses research"| node_research
node_runner -->|"queries AD findings"| node_whippet
node_runner -->|"uses managed queries"| node_batch
node_runner -->|"records artifacts"| node_artifacts
node_codex -->|"queries findings"| node_whippet
node_codex -->|"records evidence"| node_artifacts
node_dashboard -->|"offers replay"| node_replay
node_dashboard -->|"manages settings snapshots"| node_snapshots
node_dashboard -->|"uses session archives"| node_archive
node_runner -.->|"stores session history"| node_archive

click node_dashboard "https://github.com/pdmiv/harp/blob/main/harp_web.py"
click node_codex "https://github.com/pdmiv/harp/blob/main/harp_mcp.py"
click node_runner "https://github.com/pdmiv/harp/blob/main/harp.py"
click node_recon "https://github.com/pdmiv/harp/blob/main/harp.py"
click node_command_guard "https://github.com/pdmiv/harp/blob/main/harp.py"
click node_oracle "https://github.com/pdmiv/harp/blob/main/harp_nim.py"
click node_proxy "https://github.com/pdmiv/harp/blob/main/harp.py"
click node_openai "https://github.com/pdmiv/harp/blob/main/harp_openai.py"
click node_zai "https://github.com/pdmiv/harp/blob/main/harp_zai.py"
click node_nim "https://github.com/pdmiv/harp/blob/main/harp_nim.py"
click node_evidence "https://github.com/pdmiv/harp/blob/main/harp_evidence.py"
click node_strategy "https://github.com/pdmiv/harp/blob/main/harp_strategy.py"
click node_research "https://github.com/pdmiv/harp/blob/main/harp_research.py"
click node_whippet "https://github.com/pdmiv/harp/blob/main/harp_whippet.py"
click node_batch "https://github.com/pdmiv/harp/blob/main/harp_whippet_batch.py"
click node_artifacts "https://github.com/pdmiv/harp/blob/main/harp_artifacts.py"
click node_replay "https://github.com/pdmiv/harp/blob/main/harp_replay.py"
click node_snapshots "https://github.com/pdmiv/harp/blob/main/harp_snapshots.py"
click node_archive "https://github.com/pdmiv/harp/blob/main/harp_session_archive.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_dashboard,node_codex toneBlue
class node_runner,node_recon,node_command_guard,node_kali toneAmber
class node_evidence,node_strategy,node_research,node_whippet,node_batch toneMint
class node_oracle,node_proxy,node_openai,node_zai,node_nim toneRose
class node_artifacts,node_replay,node_snapshots,node_archive,node_operator toneIndigo
```

## Components

### Operator interfaces

- [HARP dashboard](https://github.com/pdmiv/harp/blob/main/harp_web.py): `harp_web.py`
- [Codex MCP](https://github.com/pdmiv/harp/blob/main/harp_mcp.py): `harp_mcp.py`

### Session orchestration

- [Lab runner](https://github.com/pdmiv/harp/blob/main/harp.py): `harp.py`
- [Deterministic recon](https://github.com/pdmiv/harp/blob/main/harp.py): `harp.py`
- [Command validation](https://github.com/pdmiv/harp/blob/main/harp.py): `harp.py`
- **Kali runtime**

### Evidence and research

- [Capability evidence](https://github.com/pdmiv/harp/blob/main/harp_evidence.py): `harp_evidence.py`
- [Planning checks](https://github.com/pdmiv/harp/blob/main/harp_strategy.py): `harp_strategy.py`
- [CVE and web research](https://github.com/pdmiv/harp/blob/main/harp_research.py): `harp_research.py`
- [Whippet AD analysis](https://github.com/pdmiv/harp/blob/main/harp_whippet.py): `harp_whippet.py`
- [Whippet batch queries](https://github.com/pdmiv/harp/blob/main/harp_whippet_batch.py): `harp_whippet_batch.py`

### Model integrations

- [Oracle planning](https://github.com/pdmiv/harp/blob/main/harp_nim.py): `harp_nim.py`
- [Proxy model](https://github.com/pdmiv/harp/blob/main/harp.py): `harp.py`
- [OpenAI transport](https://github.com/pdmiv/harp/blob/main/harp_openai.py): `harp_openai.py`
- [Z.AI transport](https://github.com/pdmiv/harp/blob/main/harp_zai.py): `harp_zai.py`
- [NVIDIA NIM transport](https://github.com/pdmiv/harp/blob/main/harp_nim.py): `harp_nim.py`

### Session records

- [Flags and artifacts](https://github.com/pdmiv/harp/blob/main/harp_artifacts.py): `harp_artifacts.py`
- [Session replay](https://github.com/pdmiv/harp/blob/main/harp_replay.py): `harp_replay.py`
- [Settings snapshots](https://github.com/pdmiv/harp/blob/main/harp_snapshots.py): `harp_snapshots.py`
- [Session archive](https://github.com/pdmiv/harp/blob/main/harp_session_archive.py): `harp_session_archive.py`

### Other components

- **Operator**

## Connections

- Operator → HARP dashboard: configures and starts (evidence: `README.md`)
- Operator → Codex MCP: connects via (evidence: `README.md`)
- HARP dashboard → Lab runner: starts sessions (evidence: `harp_web.py`)
- Codex MCP → Lab runner: uses session tools (evidence: `harp_mcp.py`)
- Lab runner → Deterministic recon: performs (evidence: `README.md`)
- Lab runner → Oracle planning: requests plans (evidence: `README.md`)
- Lab runner → Proxy model: delegates objectives (evidence: `README.md`)
- Lab runner → Command validation: validates commands (evidence: `README.md`)
- Command validation → Kali runtime: permits execution (evidence: `README.md`)
- Lab runner → OpenAI transport: calls when selected (evidence: `harp.py`)
- Lab runner → Z.AI transport: calls when selected (evidence: `harp.py`)
- Lab runner → NVIDIA NIM transport: calls when selected (evidence: `harp.py`)
- Lab runner → Capability evidence: updates evidence (evidence: `harp.py`)
- Lab runner → Planning checks: uses planning checks (evidence: `harp.py`)
- Lab runner → CVE and web research: uses research (evidence: `harp.py`)
- Lab runner → Whippet AD analysis: queries AD findings (evidence: `harp.py`)
- Lab runner → Whippet batch queries: uses managed queries (evidence: `README.md`)
- Lab runner → Flags and artifacts: records artifacts (evidence: `harp.py`)
- Codex MCP → Whippet AD analysis: queries findings (evidence: `harp_mcp.py`)
- Codex MCP → Flags and artifacts: records evidence (evidence: `harp_mcp.py`)
- HARP dashboard → Session replay: offers replay (evidence: `harp_web.py`)
- HARP dashboard → Settings snapshots: manages settings snapshots (evidence: `harp_web.py`)
- HARP dashboard → Session archive: uses session archives (evidence: `harp_web.py`)
- Lab runner → Session archive: stores session history
