# knowbe4/frieren-dast-ai architecture

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

- Interactive diagram: https://gitdiagram.com/knowbe4/frieren-dast-ai
- Repository: https://github.com/knowbe4/frieren-dast-ai

## Overview

#### Purpose and Entry Points
Frieren DAST-AI is a Python dynamic application security testing system: an HTTPS MITM proxy captures traffic, runs passive analysis, queues in-scope targets for active AI-guided testing, and presents findings through a local dashboard. Primary CLI entry is `dast/cli.py`; runtime composition is centered on `dast/proxy/runner.py` and `dast/orchestrator.py`. An optional Electron launcher starts the same backend from `desktop/main.js`.

#### Proxy, Capture, and Dashboard Boundary
The proxy terminates/intercepts HTTPS using a local CA, applies scope/bypass policy, and captures request/response history. The dashboard server exposes the UI and API/WebSocket-facing control plane; the browser UI is static JavaScript rather than a separate application backend.
- `dast/proxy/proxy_server.py`
- `dast/proxy/cert_authority.py`
- `dast/proxy/dashboard_server.py`

Captured traffic and scan state are held by proxy/session-layer stores, creating the boundary between live interception, manual tools (Repeater/Intruder), saved sessions, and scan execution.
- `dast/proxy/intercept_store.py`
- `dast/proxy/session_store.py`
- `dast/proxy/scan_queue_state.py`

#### Scan Pipeline and Orchestration
The main control flow is: intercepted in-scope traffic → passive scan and queue → orchestration/coordinator → selected active agents → validated findings → dashboard/report consumers. The attack engine executes requests/probes with concurrency and host safety controls, while the orchestrator coordinates lifecycle and result handling.
- `dast/orchestrator.py`
- `dast/attack/engine.py`
- `dast/ai/coordinator.py`

Passive checks are data-driven YAML rules, allowing security coverage additions without scanner-code changes. Active payload seeds and vulnerability knowledge are similarly separated from agent logic.
- `dast/plugins/passive_scanner.py`
- `dast/passive_rules/`
- `dast/payloads/loader.py`

#### AI Decision and Safety Layer
The coordinator uses a provider abstraction to plan agent selection, generate/adapt payloads, classify probes, analyze responses, and filter false positives. Provider support includes AWS Bedrock, Anthropic, and OpenAI-compatible APIs. Prompt safety and red-team validation are explicit gates around model-driven actions/findings.
- `dast/ai/providers.py`
- `dast/ai/bedrock_client.py`
- `dast/ai/red_team.py`

#### Vulnerability Agents
Specialized agents implement vulnerability-class probing, generally operating in parallel for an endpoint under coordinator selection. Coverage spans injection, authorization/session flaws, SSRF/file access, secrets, LLM endpoints, GraphQL, and framework-specific testing. Shared payload filtering and response-difference logic support consistent evidence decisions.
- `dast/agents/xss_agent.py`
- `dast/agents/sqli_agent.py`
- `dast/agents/ssrf_agent.py`

#### Discovery, Browser, and Application Context
Discovery expands the target model through crawling, JavaScript analysis, fingerprinting, OpenAPI probing, and traffic graph construction. Playwright-backed browser contexts support authenticated/manual browsing and browser-required confirmations. The resulting application/threat/service context feeds planning and cross-host testing.
- `dast/discovery/engine.py`
- `dast/discovery/traffic_graph.py`
- `dast/browser/context_pool.py`

#### External Interaction, Persistence, and Outputs
OOB testing integrates Interactsh; HackerOne material can be parsed, safety-checked, validated, and turned into evidence. Sessions persist locally under the user home directory, while findings can be exported, including SARIF. Runtime dependencies include Python, Playwright/Chromium, optional Electron/Node.js, and configured LLM/cloud credentials.
- `dast/utils/interactsh.py`
- `dast/hackerone/validator.py`
- `dast/report/sarif.py`

Main entry points: [`dast/orchestrator.py`](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/orchestrator.py) (Scan orchestrator), [`dast/ai/coordinator.py`](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/coordinator.py) (AI coordinator), [`dast/proxy/runner.py`](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/runner.py) (Proxy runner), [`dast/proxy/session_store.py`](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/session_store.py) (Capture & session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Control"]
  node_cli["CLI<br/>Python entry point<br/>[cli.py]"]
  node_desktop["Electron launcher<br/>optional desktop runtime<br/>[main.js]"]
  node_runner["Proxy runner<br/>runtime composition<br/>[runner.py]"]
end

subgraph group_proxy["Proxy &amp; Dashboard"]
  node_proxy_server{{"HTTPS MITM proxy<br/>traffic interception<br/>[proxy_server.py]"}}
  node_ca["Local certificate authority<br/>TLS trust service<br/>[cert_authority.py]"]
  node_dashboard["Dashboard server<br/>UI/API/WebSocket control plane"]
  node_session_state[("Capture &amp; session state<br/>proxy-layer stores<br/>[session_store.py]")]
end

subgraph group_scanning["Scan Pipeline"]
  node_passive_scanner["Passive scanner<br/>rule-driven analyzer<br/>[passive_scanner.py]"]
  node_passive_rules["Passive rules<br/>YAML rule set"]
  node_orchestrator["Scan orchestrator<br/>lifecycle coordinator<br/>[orchestrator.py]"]
  node_attack_engine["Attack engine<br/>probe executor<br/>[engine.py]"]
  node_payload_loader["Payload knowledge<br/>active payload loader<br/>[loader.py]"]
  node_agents["Vulnerability agents<br/>specialized active probes<br/>[xss_agent.py]"]
end

subgraph group_ai["AI Decision Layer"]
  node_coordinator["AI coordinator<br/>agent planner<br/>[coordinator.py]"]
  node_providers{{"LLM providers<br/>model provider abstraction<br/>[providers.py]"}}
  node_red_team["Prompt safety gate<br/>AI safety validation<br/>[red_team.py]"]
end

subgraph group_discovery["Discovery &amp; Context"]
  node_discovery_engine["Discovery engine<br/>target modeling<br/>[engine.py]"]
  node_traffic_graph[("Application traffic graph<br/>cross-host context<br/>[traffic_graph.py]")]
  node_browser_pool["Browser contexts<br/>Playwright context pool<br/>[context_pool.py]"]
end

subgraph group_outputs["External &amp; Outputs"]
  node_interactsh{{"Interactsh<br/>OOB testing integration<br/>[interactsh.py]"}}
  node_sarif["SARIF export<br/>finding export<br/>[sarif.py]"]
  node_hackerone_validator["HackerOne validator<br/>evidence validation<br/>[validator.py]"]
end

node_cli -->|"starts"| node_runner
node_desktop -->|"starts backend"| node_runner
node_runner -->|"runs"| node_proxy_server
node_runner -->|"serves"| node_dashboard
node_proxy_server -->|"uses for HTTPS interception"| node_ca
node_proxy_server -->|"captures traffic"| node_session_state
node_dashboard -->|"controls and reads"| node_session_state
node_session_state -->|"in-scope traffic"| node_passive_scanner
node_passive_rules -->|"defines checks"| node_passive_scanner
node_passive_scanner -->|"queues targets"| node_orchestrator
node_session_state -->|"scan state"| node_orchestrator
node_orchestrator -->|"requests plan"| node_coordinator
node_discovery_engine -->|"builds"| node_traffic_graph
node_browser_pool -->|"authenticated browsing"| node_discovery_engine
node_traffic_graph -->|"application context"| node_coordinator
node_coordinator -->|"model decisions"| node_providers
node_coordinator -->|"validates AI actions"| node_red_team
node_red_team -->|"approved probe plan"| node_agents
node_coordinator -->|"selects agents"| node_agents
node_payload_loader -->|"payload seeds"| node_agents
node_agents -->|"executes probes"| node_attack_engine
node_attack_engine -->|"OOB callbacks"| node_interactsh
node_attack_engine -->|"validated results"| node_orchestrator
node_orchestrator -->|"findings and progress"| node_dashboard
node_orchestrator -->|"exports findings"| node_sarif
node_hackerone_validator -->|"validated evidence"| node_orchestrator

click node_cli "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/cli.py"
click node_desktop "https://github.com/knowbe4/frieren-dast-ai/blob/main/desktop/main.js"
click node_runner "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/runner.py"
click node_proxy_server "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/proxy_server.py"
click node_ca "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/cert_authority.py"
click node_dashboard "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/dashboard_server.py"
click node_session_state "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/session_store.py"
click node_passive_scanner "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/plugins/passive_scanner.py"
click node_orchestrator "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/orchestrator.py"
click node_attack_engine "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/attack/engine.py"
click node_payload_loader "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/payloads/loader.py"
click node_coordinator "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/coordinator.py"
click node_providers "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/providers.py"
click node_red_team "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/red_team.py"
click node_agents "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/agents/xss_agent.py"
click node_discovery_engine "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/discovery/engine.py"
click node_traffic_graph "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/discovery/traffic_graph.py"
click node_browser_pool "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/browser/context_pool.py"
click node_interactsh "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/utils/interactsh.py"
click node_sarif "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/report/sarif.py"
click node_hackerone_validator "https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/hackerone/validator.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_cli,node_desktop,node_runner toneBlue
class node_proxy_server,node_ca,node_dashboard,node_session_state toneAmber
class node_passive_scanner,node_passive_rules,node_orchestrator,node_attack_engine,node_payload_loader,node_agents toneMint
class node_coordinator,node_providers,node_red_team toneRose
class node_discovery_engine,node_traffic_graph,node_browser_pool toneIndigo
class node_interactsh,node_sarif,node_hackerone_validator toneTeal
```

## Components

### Runtime & Control

- [CLI](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/cli.py): Python entry point · `dast/cli.py`
- [Electron launcher](https://github.com/knowbe4/frieren-dast-ai/blob/main/desktop/main.js): optional desktop runtime · Starts the same Python backend. · `desktop/main.js`
- [Proxy runner](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/runner.py): runtime composition · `dast/proxy/runner.py`

### Proxy & Dashboard

- [HTTPS MITM proxy](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/proxy_server.py): traffic interception · Applies scope and bypass policy while capturing traffic. · `dast/proxy/proxy_server.py`
- [Local certificate authority](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/cert_authority.py): TLS trust service · `dast/proxy/cert_authority.py`
- [Dashboard server](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/dashboard_server.py): UI/API/WebSocket control plane · `dast/proxy/dashboard_server.py`
- [Capture & session state](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/proxy/session_store.py): proxy-layer stores · Shared history, saved sessions, and scan queue state. · `dast/proxy/session_store.py`

### Scan Pipeline

- [Passive scanner](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/plugins/passive_scanner.py): rule-driven analyzer · `dast/plugins/passive_scanner.py`
- **Passive rules**: YAML rule set · Data-driven passive security coverage.
- [Scan orchestrator](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/orchestrator.py): lifecycle coordinator · Coordinates queued scans and result handling. · `dast/orchestrator.py`
- [Attack engine](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/attack/engine.py): probe executor · Enforces concurrency and host safety controls. · `dast/attack/engine.py`
- [Payload knowledge](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/payloads/loader.py): active payload loader · `dast/payloads/loader.py`
- [Vulnerability agents](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/agents/xss_agent.py): specialized active probes · Parallel XSS, SQLi, SSRF, and other vulnerability-class testing. · `dast/agents/xss_agent.py`

### AI Decision Layer

- [AI coordinator](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/coordinator.py): agent planner · Plans agents and analyzes probe results. · `dast/ai/coordinator.py`
- [LLM providers](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/providers.py): model provider abstraction · Supports Bedrock, Anthropic, and OpenAI-compatible APIs. · `dast/ai/providers.py`
- [Prompt safety gate](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/ai/red_team.py): AI safety validation · Gates model-driven actions and findings. · `dast/ai/red_team.py`

### Discovery & Context

- [Discovery engine](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/discovery/engine.py): target modeling · Crawls, analyzes JavaScript, fingerprints, and probes APIs. · `dast/discovery/engine.py`
- [Application traffic graph](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/discovery/traffic_graph.py): cross-host context · `dast/discovery/traffic_graph.py`
- [Browser contexts](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/browser/context_pool.py): Playwright context pool · Supports authenticated and browser-required flows. · `dast/browser/context_pool.py`

### External & Outputs

- [Interactsh](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/utils/interactsh.py): OOB testing integration · `dast/utils/interactsh.py`
- [SARIF export](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/report/sarif.py): finding export · `dast/report/sarif.py`
- [HackerOne validator](https://github.com/knowbe4/frieren-dast-ai/blob/main/dast/hackerone/validator.py): evidence validation · Safety-checks imported HackerOne material. · `dast/hackerone/validator.py`

## Connections

- CLI → Proxy runner: starts
- Electron launcher → Proxy runner: starts backend
- Proxy runner → HTTPS MITM proxy: runs
- Proxy runner → Dashboard server: serves
- HTTPS MITM proxy → Local certificate authority: uses for HTTPS interception
- HTTPS MITM proxy → Capture & session state: captures traffic
- Dashboard server → Capture & session state: controls and reads
- Capture & session state → Passive scanner: in-scope traffic
- Passive rules → Passive scanner: defines checks
- Passive scanner → Scan orchestrator: queues targets
- Capture & session state → Scan orchestrator: scan state
- Scan orchestrator → AI coordinator: requests plan
- Discovery engine → Application traffic graph: builds
- Browser contexts → Discovery engine: authenticated browsing
- Application traffic graph → AI coordinator: application context
- AI coordinator → LLM providers: model decisions
- AI coordinator → Prompt safety gate: validates AI actions
- Prompt safety gate → Vulnerability agents: approved probe plan
- AI coordinator → Vulnerability agents: selects agents
- Payload knowledge → Vulnerability agents: payload seeds
- Vulnerability agents → Attack engine: executes probes
- Attack engine → Interactsh: OOB callbacks
- Attack engine → Scan orchestrator: validated results
- Scan orchestrator → Dashboard server: findings and progress
- Scan orchestrator → SARIF export: exports findings
- HackerOne validator → Scan orchestrator: validated evidence