# brukal001/brukal architecture

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

- Interactive diagram: https://gitdiagram.com/brukal001/brukal
- Repository: https://github.com/brukal001/brukal

## Overview

Brukal is a trust-governed, multi-agent penetration-testing system. Its main workflow takes an operator’s engagement through planning and agent proposals, deterministically checks proposed actions against immutable scope and risk policy, and executes only approved actions in a constrained cage. Results feed verification and engagement knowledge; decisions and outcomes are recorded in a tamper-evident audit log. The README documents major capabilities beyond the sampled implementation excerpts; those branches are included, with uncertain wiring left unclaimed.

Main entry points: [`brukal/orchestrator.py`](https://github.com/brukal001/brukal/blob/main/brukal/orchestrator.py) (Agent orchestrator), [`brukal/executor.py`](https://github.com/brukal001/brukal/blob/main/brukal/executor.py) (Command executor), [`brukal/gate.py`](https://github.com/brukal001/brukal/blob/main/brukal/gate.py) (Deterministic gate), [`brukal/web.py`](https://github.com/brukal001/brukal/blob/main/brukal/web.py) (Governed web testing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Engagement workflow"]
  node_cli["CLI<br/>[cli.py]"]
  node_engagement["Engagement runner<br/>[engagement.py]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_agents["Recon / exploit agents"]
  node_verify["Result verifier<br/>[verify.py]"]
  node_blackboard[("Shared blackboard<br/>[blackboard.py]")]
  node_tasktree["Pentest task tree<br/>[tasktree.py]"]
end

subgraph group_governance["Safety governance"]
  node_scope["Scope policy<br/>[scope.py]"]
  node_gate["Deterministic gate<br/>[gate.py]"]
  node_risk["Risk and trust<br/>[risk.py]"]
end

subgraph group_execution["Execution surfaces"]
  node_executor["Command executor<br/>[executor.py]"]
  node_kali["Kali cage<br/>[kali.py]"]
  node_web["Governed web testing<br/>[web.py]"]
  node_browser["Headless browser<br/>[chrome.py]"]
end

subgraph group_learning["Planning and learning"]
  node_strategist["Strategist<br/>[strategist.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_lessons[("Verified lessons<br/>[lessons.py]")]
  node_research["On-demand research<br/>[research.py]"]
  node_skills[("Playbooks and skills<br/>[skills.py]")]
end

subgraph group_evidence["Evidence and records"]
  node_capture["Evidence capture<br/>[capture.py]"]
  node_findings["Findings<br/>[findings.py]"]
  node_audit[("Audit ledger<br/>[audit.py]")]
end

node_operator(("Operator"))

node_operator -->|"starts engagement"| node_cli
node_cli -->|"starts run"| node_engagement
node_engagement -->|"runs agents"| node_orchestrator
node_orchestrator -->|"dispatches tasks"| node_tasktree
node_orchestrator -->|"reads and writes"| node_blackboard
node_orchestrator -->|"dispatches tasks"| node_agents
node_agents -->|"submits actions"| node_executor
node_agents -->|"requests proposals"| node_llm
node_strategist -->|"requests plans"| node_llm
node_scope -->|"defines allowed scope"| node_gate
node_gate -->|"evaluates action risk"| node_risk
node_executor -->|"checks action"| node_gate
node_executor -->|"runs approved command"| node_kali
node_executor -->|"records decision and result"| node_audit
node_web -->|"scope-checks web actions"| node_gate
node_web -->|"logs web actions"| node_audit
node_web -.->|"drives browser"| node_browser
node_verify -->|"checks gated output"| node_executor
node_verify -->|"promotes verified wins"| node_lessons
node_orchestrator -->|"loads relevant playbooks"| node_skills
node_research -->|"supplies untrusted reference"| node_strategist
node_capture -.->|"supports findings"| node_findings

click node_cli "https://github.com/brukal001/brukal/blob/main/brukal/cli.py"
click node_engagement "https://github.com/brukal001/brukal/blob/main/brukal/engagement.py"
click node_orchestrator "https://github.com/brukal001/brukal/blob/main/brukal/orchestrator.py"
click node_agents "https://github.com/brukal001/brukal/tree/main/brukal/agents"
click node_strategist "https://github.com/brukal001/brukal/blob/main/brukal/agents/strategist.py"
click node_llm "https://github.com/brukal001/brukal/blob/main/brukal/llm.py"
click node_scope "https://github.com/brukal001/brukal/blob/main/brukal/scope.py"
click node_gate "https://github.com/brukal001/brukal/blob/main/brukal/gate.py"
click node_risk "https://github.com/brukal001/brukal/blob/main/brukal/risk.py"
click node_executor "https://github.com/brukal001/brukal/blob/main/brukal/executor.py"
click node_kali "https://github.com/brukal001/brukal/blob/main/brukal/kali.py"
click node_web "https://github.com/brukal001/brukal/blob/main/brukal/web.py"
click node_browser "https://github.com/brukal001/brukal/blob/main/brukal/chrome.py"
click node_verify "https://github.com/brukal001/brukal/blob/main/brukal/verify.py"
click node_capture "https://github.com/brukal001/brukal/blob/main/brukal/capture.py"
click node_findings "https://github.com/brukal001/brukal/blob/main/brukal/findings.py"
click node_audit "https://github.com/brukal001/brukal/blob/main/brukal/audit.py"
click node_lessons "https://github.com/brukal001/brukal/blob/main/brukal/lessons.py"
click node_research "https://github.com/brukal001/brukal/blob/main/brukal/research.py"
click node_skills "https://github.com/brukal001/brukal/blob/main/brukal/skills.py"
click node_blackboard "https://github.com/brukal001/brukal/blob/main/brukal/blackboard.py"
click node_tasktree "https://github.com/brukal001/brukal/blob/main/brukal/tasktree.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_engagement,node_orchestrator,node_agents,node_verify,node_blackboard,node_tasktree toneBlue
class node_scope,node_gate,node_risk toneAmber
class node_executor,node_kali,node_web,node_browser toneMint
class node_strategist,node_llm,node_lessons,node_research,node_skills toneRose
class node_capture,node_findings,node_audit,node_operator toneIndigo
```

## Components

### Engagement workflow

- [CLI](https://github.com/brukal001/brukal/blob/main/brukal/cli.py): `brukal/cli.py`
- [Engagement runner](https://github.com/brukal001/brukal/blob/main/brukal/engagement.py): `brukal/engagement.py`
- [Agent orchestrator](https://github.com/brukal001/brukal/blob/main/brukal/orchestrator.py): `brukal/orchestrator.py`
- [Recon / exploit agents](https://github.com/brukal001/brukal/tree/main/brukal/agents): `brukal/agents`
- [Result verifier](https://github.com/brukal001/brukal/blob/main/brukal/verify.py): `brukal/verify.py`
- [Shared blackboard](https://github.com/brukal001/brukal/blob/main/brukal/blackboard.py): `brukal/blackboard.py`
- [Pentest task tree](https://github.com/brukal001/brukal/blob/main/brukal/tasktree.py): `brukal/tasktree.py`

### Safety governance

- [Scope policy](https://github.com/brukal001/brukal/blob/main/brukal/scope.py): `brukal/scope.py`
- [Deterministic gate](https://github.com/brukal001/brukal/blob/main/brukal/gate.py): `brukal/gate.py`
- [Risk and trust](https://github.com/brukal001/brukal/blob/main/brukal/risk.py): `brukal/risk.py`

### Execution surfaces

- [Command executor](https://github.com/brukal001/brukal/blob/main/brukal/executor.py): `brukal/executor.py`
- [Kali cage](https://github.com/brukal001/brukal/blob/main/brukal/kali.py): `brukal/kali.py`
- [Governed web testing](https://github.com/brukal001/brukal/blob/main/brukal/web.py): `brukal/web.py`
- [Headless browser](https://github.com/brukal001/brukal/blob/main/brukal/chrome.py): `brukal/chrome.py`

### Planning and learning

- [Strategist](https://github.com/brukal001/brukal/blob/main/brukal/agents/strategist.py): `brukal/agents/strategist.py`
- [LLM client](https://github.com/brukal001/brukal/blob/main/brukal/llm.py): `brukal/llm.py`
- [Verified lessons](https://github.com/brukal001/brukal/blob/main/brukal/lessons.py): `brukal/lessons.py`
- [On-demand research](https://github.com/brukal001/brukal/blob/main/brukal/research.py): `brukal/research.py`
- [Playbooks and skills](https://github.com/brukal001/brukal/blob/main/brukal/skills.py): `brukal/skills.py`

### Evidence and records

- [Evidence capture](https://github.com/brukal001/brukal/blob/main/brukal/capture.py): `brukal/capture.py`
- [Findings](https://github.com/brukal001/brukal/blob/main/brukal/findings.py): `brukal/findings.py`
- [Audit ledger](https://github.com/brukal001/brukal/blob/main/brukal/audit.py): `brukal/audit.py`

### Other components

- **Operator**

## Connections

- Operator → CLI: starts engagement (evidence: `README.md`)
- CLI → Engagement runner: starts run (evidence: `brukal/engagement.py`)
- Engagement runner → Agent orchestrator: runs agents (evidence: `brukal/engagement.py`)
- Agent orchestrator → Pentest task tree: dispatches tasks (evidence: `brukal/orchestrator.py`)
- Agent orchestrator → Shared blackboard: reads and writes (evidence: `brukal/orchestrator.py`)
- Agent orchestrator → Recon / exploit agents: dispatches tasks (evidence: `brukal/orchestrator.py`)
- Recon / exploit agents → Command executor: submits actions (evidence: `brukal/agents/recon.py`)
- Recon / exploit agents → LLM client: requests proposals (evidence: `brukal/agents/recon.py`)
- Strategist → LLM client: requests plans (evidence: `brukal/agents/strategist.py`)
- Scope policy → Deterministic gate: defines allowed scope (evidence: `README.md`)
- Deterministic gate → Risk and trust: evaluates action risk (evidence: `brukal/gate.py`)
- Command executor → Deterministic gate: checks action (evidence: `brukal/executor.py`)
- Command executor → Kali cage: runs approved command (evidence: `brukal/executor.py`)
- Command executor → Audit ledger: records decision and result (evidence: `brukal/executor.py`)
- Governed web testing → Deterministic gate: scope-checks web actions (evidence: `README.md`)
- Governed web testing → Audit ledger: logs web actions (evidence: `README.md`)
- Governed web testing → Headless browser: drives browser
- Result verifier → Command executor: checks gated output (evidence: `README.md`)
- Result verifier → Verified lessons: promotes verified wins (evidence: `README.md`)
- Agent orchestrator → Playbooks and skills: loads relevant playbooks (evidence: `brukal/orchestrator.py`)
- On-demand research → Strategist: supplies untrusted reference (evidence: `README.md`)
- Evidence capture → Findings: supports findings
