How brukal001/brukal works
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: orchestrator.py Agent orchestrator · executor.py Command executor · gate.py Deterministic gate · web.py Governed web testing
Components 23
Engagement workflow
- CLI
brukal/cli.py - Engagement runner
brukal/engagement.py - Agent orchestrator
brukal/orchestrator.py - Recon / exploit agents
brukal/agents - Result verifier
brukal/verify.py - Shared blackboard
brukal/blackboard.py - Pentest task tree
brukal/tasktree.py
Safety governance
- Scope policy
brukal/scope.py - Deterministic gate
brukal/gate.py - Risk and trust
brukal/risk.py
Execution surfaces
- Command executor
brukal/executor.py - Kali cage
brukal/kali.py - Governed web testing
brukal/web.py - Headless browser
brukal/chrome.py
Planning and learning
- Strategist
brukal/agents/strategist.py - LLM client
brukal/llm.py - Verified lessons
brukal/lessons.py - On-demand research
brukal/research.py - Playbooks and skills
brukal/skills.py
Evidence and records
- Evidence capture
brukal/capture.py - Findings
brukal/findings.py - Audit ledger
brukal/audit.py
Other components
- Operator
Connections 22
- Operator → CLI: starts engagement
README.md - CLI → Engagement runner: starts run
brukal/engagement.py - Engagement runner → Agent orchestrator: runs agents
brukal/engagement.py - Agent orchestrator → Pentest task tree: dispatches tasks
brukal/orchestrator.py - Agent orchestrator → Shared blackboard: reads and writes
brukal/orchestrator.py - Agent orchestrator → Recon / exploit agents: dispatches tasks
brukal/orchestrator.py - Recon / exploit agents → Command executor: submits actions
brukal/agents/recon.py - Recon / exploit agents → LLM client: requests proposals
brukal/agents/recon.py - Strategist → LLM client: requests plans
brukal/agents/strategist.py - Scope policy → Deterministic gate: defines allowed scope
README.md - Deterministic gate → Risk and trust: evaluates action risk
brukal/gate.py - Command executor → Deterministic gate: checks action
brukal/executor.py - Command executor → Kali cage: runs approved command
brukal/executor.py - Command executor → Audit ledger: records decision and result
brukal/executor.py - Governed web testing → Deterministic gate: scope-checks web actions
README.md - Governed web testing → Audit ledger: logs web actions
README.md - Governed web testing → Headless browser: drives browser
- Result verifier → Command executor: checks gated output
README.md - Result verifier → Verified lessons: promotes verified wins
README.md - Agent orchestrator → Playbooks and skills: loads relevant playbooks
brukal/orchestrator.py - On-demand research → Strategist: supplies untrusted reference
README.md - Evidence capture → Findings: supports findings