# hack-umbrella/pipadeep architecture

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

- Interactive diagram: https://gitdiagram.com/hack-umbrella/pipadeep
- Repository: https://github.com/hack-umbrella/pipadeep

## Overview

This DSH plugin supports an authorized penetration-test workflow: a commander records goals and intents, delegates scoped investigation to execution agents, and records confirmed facts, assets, and findings. Results persist in a session graph, which the Web UI presents as exploration, vulnerability, asset, and report views. Execution also includes browser-based evidence capture, flag submission, and on-demand skills and bypass knowledge. The README documents some wiring not shown in sampled source; those links are represented only where documented.

Main entry points: [`preset/pentest/agent.cordis.yml`](https://github.com/hack-umbrella/pipadeep/blob/llm/preset/pentest/agent.cordis.yml) (Execution agent), [`lib/shot.js`](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot.js) (Evidence capture), [`lib/pentest.js`](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest.js) (Graph tools), [`lib/shot-runner.js`](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot-runner.js) (Playwright runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Test workflow"]
  node_commander["Commander agent<br/>[agent.cordis.yml]"]
  node_executor["Execution agent<br/>[agent.cordis.yml]"]
end

subgraph group_execution["Execution tools"]
  node_arsenal["Arsenal tool<br/>[pentest-tools.js]"]
  node_scope["Scope gate<br/>[pentest-tools.js]"]
  node_bypass["Bypass tool<br/>[pentest-tools.js]"]
  node_flag["Flag submission<br/>[pentest-tools.js]"]
  node_shot["Evidence capture<br/>[shot.js]"]
  node_runner["Playwright runner<br/>[shot-runner.js]"]
  node_arsenal_container["Arsenal container"]
end

subgraph group_records["Records and storage"]
  node_recording["Graph tools<br/>[pentest.js]"]
  node_projection["Session projection<br/>[pentest.js]"]
  node_sqlite[("Pentest SQLite<br/>[storage-sqlite.js]")]
end

subgraph group_web["Web and evidence"]
  node_proxy["Mitmproxy addon<br/>[mitm-addon.py]"]
  node_evidence["Evidence files"]
  node_webui["Pentest Web UI"]
  node_routes["Web data routes"]
end

subgraph group_knowledge["Knowledge"]
  node_bypass_routes["Knowledge routes<br/>[bypass-routes.js]"]
  node_skills["Pentest skills"]
  node_bypass_file["Bypass knowledge"]
end

node_user(("User"))
node_target(("Test target"))
node_tsec["Tsec platform"]

node_user -->|"provides target"| node_commander
node_commander -->|"records goal and intent"| node_recording
node_commander -->|"delegates investigation"| node_executor
node_executor -->|"runs tools"| node_arsenal
node_arsenal -->|"dispatches command"| node_arsenal_container
node_arsenal_container -->|"scans or exploits"| node_target
node_executor -->|"checks authorization"| node_scope
node_executor -->|"loads knowledge"| node_bypass
node_executor -->|"submits flag"| node_flag
node_flag -->|"posts flag"| node_tsec
node_executor -->|"captures evidence"| node_shot
node_shot -->|"checks target scope"| node_scope
node_shot -->|"starts subprocess"| node_runner
node_runner -->|"visits target"| node_target
node_runner -->|"sends proxied traffic"| node_proxy
node_proxy -->|"indexes requests"| node_evidence
node_shot -->|"writes evidence files"| node_evidence
node_shot -->|"returns evidence"| node_recording
node_executor -->|"submits confirmed results"| node_recording
node_recording -->|"reads and writes domain"| node_sqlite
node_recording -->|"replays session graph"| node_projection
node_projection -->|"supplies session view"| node_webui
node_webui -->|"requests engagements and evidence"| node_routes
node_routes -->|"reads engagements"| node_sqlite
node_routes -->|"serves evidence files"| node_evidence
node_executor -.->|"loads skills on demand"| node_skills
node_bypass -->|"reads bypass data"| node_bypass_file
node_bypass_routes -->|"reads and writes"| node_bypass_file
node_bypass_routes -->|"reads and writes"| node_skills
node_webui -.->|"manages knowledge"| node_bypass_routes

click node_commander "https://github.com/hack-umbrella/pipadeep/blob/llm/preset/pentest/agent.cordis.yml"
click node_executor "https://github.com/hack-umbrella/pipadeep/blob/llm/preset/pentest/agent.cordis.yml"
click node_recording "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest.js"
click node_projection "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest.js"
click node_sqlite "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/storage-sqlite.js"
click node_arsenal "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js"
click node_scope "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js"
click node_bypass "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js"
click node_flag "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js"
click node_shot "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot.js"
click node_runner "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot-runner.js"
click node_proxy "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/mitm-addon.py"
click node_webui "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/ui-pentest.client.js"
click node_routes "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/engagements-routes.js"
click node_bypass_routes "https://github.com/hack-umbrella/pipadeep/blob/llm/lib/bypass-routes.js"
click node_skills "https://github.com/hack-umbrella/pipadeep/tree/llm/skills"
click node_bypass_file "https://github.com/hack-umbrella/pipadeep/blob/llm/pentest-bypass.example.json"

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_commander,node_executor,node_user toneBlue
class node_arsenal,node_scope,node_bypass,node_flag,node_shot,node_runner,node_arsenal_container toneAmber
class node_recording,node_projection,node_sqlite toneMint
class node_proxy,node_evidence,node_webui,node_routes toneRose
class node_bypass_routes,node_skills,node_bypass_file,node_target,node_tsec toneIndigo
```

## Components

### Test workflow

- [Commander agent](https://github.com/hack-umbrella/pipadeep/blob/llm/preset/pentest/agent.cordis.yml): `preset/pentest/agent.cordis.yml`
- [Execution agent](https://github.com/hack-umbrella/pipadeep/blob/llm/preset/pentest/agent.cordis.yml): `preset/pentest/agent.cordis.yml`

### Execution tools

- [Arsenal tool](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js): `lib/pentest-tools.js`
- [Scope gate](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js): `lib/pentest-tools.js`
- [Bypass tool](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js): `lib/pentest-tools.js`
- [Flag submission](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest-tools.js): `lib/pentest-tools.js`
- [Evidence capture](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot.js): `lib/shot.js`
- [Playwright runner](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/shot-runner.js): `lib/shot-runner.js`
- **Arsenal container**

### Records and storage

- [Graph tools](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest.js): `lib/pentest.js`
- [Session projection](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/pentest.js): `lib/pentest.js`
- [Pentest SQLite](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/storage-sqlite.js): `lib/storage-sqlite.js`

### Web and evidence

- [Mitmproxy addon](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/mitm-addon.py): `lib/mitm-addon.py`
- **Evidence files**
- [Pentest Web UI](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/ui-pentest.client.js): `lib/ui-pentest.client.js`
- [Web data routes](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/engagements-routes.js): `lib/engagements-routes.js`

### Knowledge

- [Knowledge routes](https://github.com/hack-umbrella/pipadeep/blob/llm/lib/bypass-routes.js): `lib/bypass-routes.js`
- [Pentest skills](https://github.com/hack-umbrella/pipadeep/tree/llm/skills): `skills`
- [Bypass knowledge](https://github.com/hack-umbrella/pipadeep/blob/llm/pentest-bypass.example.json): `pentest-bypass.example.json`

### Other components

- **User**
- **Test target**
- **Tsec platform**

## Connections

- User → Commander agent: provides target
- Commander agent → Graph tools: records goal and intent
- Commander agent → Execution agent: delegates investigation
- Execution agent → Arsenal tool: runs tools
- Arsenal tool → Arsenal container: dispatches command
- Arsenal container → Test target: scans or exploits
- Execution agent → Scope gate: checks authorization
- Execution agent → Bypass tool: loads knowledge
- Execution agent → Flag submission: submits flag
- Flag submission → Tsec platform: posts flag
- Execution agent → Evidence capture: captures evidence
- Evidence capture → Scope gate: checks target scope
- Evidence capture → Playwright runner: starts subprocess
- Playwright runner → Test target: visits target
- Playwright runner → Mitmproxy addon: sends proxied traffic
- Mitmproxy addon → Evidence files: indexes requests
- Evidence capture → Evidence files: writes evidence files
- Evidence capture → Graph tools: returns evidence
- Execution agent → Graph tools: submits confirmed results
- Graph tools → Pentest SQLite: reads and writes domain
- Graph tools → Session projection: replays session graph
- Session projection → Pentest Web UI: supplies session view
- Pentest Web UI → Web data routes: requests engagements and evidence
- Web data routes → Pentest SQLite: reads engagements
- Web data routes → Evidence files: serves evidence files
- Execution agent → Pentest skills: loads skills on demand
- Bypass tool → Bypass knowledge: reads bypass data
- Knowledge routes → Bypass knowledge: reads and writes
- Knowledge routes → Pentest skills: reads and writes
- Pentest Web UI → Knowledge routes: manages knowledge