From 61dd08428aea2349b06b705dfac32bcd5e2dc756 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 07:27:39 +0000 Subject: [PATCH 1/2] Remove repo cadavers: empty .gitmodules, unused clients/ package, 4 unreferenced docs Cleanup of dead files identified by cross-referencing every candidate against code, config.py, docker-compose, Makefile, CI, and tests: - .gitmodules: empty (1 byte), no submodules defined - blhackbox/clients/: empty placeholder package; nothing imports blhackbox.clients. pyproject auto-discovers packages (include = ["blhackbox*"]), so no packaging change is needed - docs/container-integration-review.md, docs/external-repo-assessment.md, docs/pentagi-comparison.md, docs/repo-audit.md: point-in-time analysis docs linked from nothing (README/.env.example-linked docs were kept) No surviving file references any removed path. Full test suite passes (201 passed). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01GXPrrB6JQMBGHc19sXhcHw --- .gitmodules | 1 - blhackbox/clients/__init__.py | 1 - docs/container-integration-review.md | 36 ---- docs/external-repo-assessment.md | 61 ------ docs/pentagi-comparison.md | 291 --------------------------- docs/repo-audit.md | 40 ---- 6 files changed, 430 deletions(-) delete mode 100644 .gitmodules delete mode 100644 blhackbox/clients/__init__.py delete mode 100644 docs/container-integration-review.md delete mode 100644 docs/external-repo-assessment.md delete mode 100644 docs/pentagi-comparison.md delete mode 100644 docs/repo-audit.md diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 8b13789..0000000 --- a/.gitmodules +++ /dev/null @@ -1 +0,0 @@ - diff --git a/blhackbox/clients/__init__.py b/blhackbox/clients/__init__.py deleted file mode 100644 index 0ede157..0000000 --- a/blhackbox/clients/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""API clients for external services.""" diff --git a/docs/container-integration-review.md b/docs/container-integration-review.md deleted file mode 100644 index 006205e..0000000 --- a/docs/container-integration-review.md +++ /dev/null @@ -1,36 +0,0 @@ -# Container Integration Review - -## Current container topology - -| Startup | Service | Purpose | Port(s) | Network | -|---|---|---|---:|---| -| default | `kali-mcp` | Kali tool execution and Metasploit CLI workflows | `9001` | `blhackbox_net` | -| default | `wire-mcp` | tshark/Wireshark traffic tools sharing Kali network namespace | `9003` | `service:kali-mcp` | -| default | `screenshot-mcp` | Playwright/Chromium evidence capture | `9004` | `blhackbox_net` | -| default | `hexstrike-ai` | Capsulated HexStrike Gamma API | `8888` | `blhackbox_net` | -| default | `hexstrike-bridge-mcp` | Full upstream HexStrike Gamma MCP server loaded unchanged and exposed over SSE | `9006` | `blhackbox_net` | -| default | `boaz-mcp` | Upstream BOAZ-MCP Gamma server with image-bundled `BOAZ_gamma` | `9005` | `blhackbox_net` | -| default | `portainer` | Local container management UI | `9443` | `blhackbox_net` | -| `gateway` | `mcp-gateway` | Gateway for host clients that explicitly need it | `8080` | `blhackbox_net` | -| `neo4j` | `neo4j` | Graph database | `7474`, `7687` | `blhackbox_net` | -| `claude-code` | `claude-code` | In-network MCP client | n/a | `blhackbox_net` | - -## Interconnection review - -- `hexstrike-bridge-mcp` depends on `hexstrike-ai` and uses `HEXSTRIKE_URL=http://hexstrike-ai:8888`. -- `boaz-mcp` loads upstream BOAZ-MCP Gamma from `BOAZ_MCP_PATH=/opt/BOAZ-MCP_gamma`, uses `BOAZ_PATH=/opt/BOAZ_gamma`, and mounts `./output/boaz-lab` for operator workspace files. -- `claude-code` has `NO_PROXY` entries for all internal service hostnames. -- `wire-mcp` intentionally shares the Kali network namespace for packet visibility. -- `mcp-gateway` remains available only for clients that require a single host-side Streamable HTTP endpoint; normal Docker-based Claude Code operation connects directly to Kali, WireMCP, Screenshot MCP, BOAZ MCP, and HexStrike MCP. - -## Operator commands - -- `make up` starts the default stack, including HexStrike and BOAZ. -- `make mcp-status` runs static MCP validation, tool inventory, and the fallback security scan. -- `make check-mcp LIVE=1` checks live endpoints for default MCP services. -- `make logs-hexstrike` tails HexStrike API and MCP logs. -- `make logs-boaz` tails BOAZ MCP logs. - -## Review outcome - -The stack is aligned around one Docker network, default-start MCP services, predictable ports, and health checks. HexStrike and BOAZ are no longer profile-gated sidecars; they are integrated into the normal compose lifecycle and the Claude Code direct-SSE path like the other MCP services. diff --git a/docs/external-repo-assessment.md b/docs/external-repo-assessment.md deleted file mode 100644 index 7fcaa84..0000000 --- a/docs/external-repo-assessment.md +++ /dev/null @@ -1,61 +0,0 @@ -# External Repository Assessment: HexStrike AI, BOAZ-MCP, BOAZ_beta - -Reviewed references: - -- `https://github.com/0x4m4/hexstrike-ai` -- `https://github.com/Yenn503/BOAZ-MCP` -- `https://github.com/thomasxm/BOAZ_beta` - -> Network cloning from this environment was blocked by GitHub CONNECT tunnel restrictions, so this assessment used accessible public README/package index summaries and compared their architecture against the local blhackbox codebase. - -## HexStrike AI ideas worth adopting - -HexStrike AI's strongest public ideas are architectural rather than code-specific: - -- A searchable, categorized security-tool catalogue. -- Workflow-oriented agents/profiles for bug bounty, CTF, CVE intelligence, exploit generation, and technology detection. -- Tool selection and parameter optimization before execution. -- Failure recovery, graceful degradation, and performance/caching concepts. -- Visual/evidence-oriented reporting. - -### Adopted now - -- Added searchable catalogue discovery through `search_tools`. -- Added exact metadata retrieval through `get_tool_details`. -- Added workflow profiles through `recommend_workflow`. -- Enriched tool metadata with backend, tags, and example parameters. - -### Recommended later - -- Add a local decision engine that scores candidate tools by target type, phase, authorization, and previous results. -- Add cache metadata keyed by target, tool, parameters, and timestamp. -- Add retry/fallback policies for common tool failures. - -## BOAZ-MCP and BOAZ_beta ideas worth adopting carefully - -BOAZ-MCP wraps BOAZ_beta for AI-assisted payload wrapping/evasion in authorized red-team labs. Its public documentation emphasizes process injection loaders, encoders, obfuscation, anti-emulation, and related techniques. - -### Adopted now - -- Integrated the upstream BOAZ-MCP Gamma server as the default `boaz-mcp` Docker Compose service, backed by a BOAZ_gamma checkout in the image. -- Exposed BOAZ over SSE on port `9005` and wired it into the same Claude Code Docker direct-SSE `.mcp.json` path as Kali, WireMCP, Screenshot MCP, and HexStrike. -- Kept BOAZ isolated as a separate MCP server with its own workspace mount and upstream path-confinement behavior. -- Kept authorization-gated prompts/docs and avoided automatic execution in default assessment workflows. - -### Recommended follow-up hardening - -- Add tests that validate path confinement and that payload inputs must already exist in an authorized lab payload directory. -- Keep BOAZ output directories explicit and separate from general report/session output. -- Continue to avoid implicit BOAZ execution in default discovery-only workflows. - -## Build-vs-fork recommendation - -Keep blhackbox as the base and selectively adopt design patterns. A full HexStrike fork would likely increase maintenance burden and reduce the clean separation currently present in blhackbox: - -- Docker-separated MCP services. -- Core graph/reporting/prompt server. -- Explicit tests for MCP schemas and data models. -- Controlled output paths. -- Existing authorization-template workflow. - -The best upgrade path is incremental: searchable catalogue, workflow profiles, health checks, caching, and CI-backed Docker smoke tests. diff --git a/docs/pentagi-comparison.md b/docs/pentagi-comparison.md deleted file mode 100644 index f9bb98f..0000000 --- a/docs/pentagi-comparison.md +++ /dev/null @@ -1,291 +0,0 @@ -# PentAGI vs BLHACKBOX — Architecture Comparison & Optimization Roadmap - -> Analysis date: 2026-03-25 -> PentAGI repo: https://github.com/vxcontrol/pentagi -> Note: PentAGI source code was under licensing audit at time of analysis; details sourced from README, DeepWiki, forks (AlExAnDeR-O-G/pentagi), and cached Go source files at commit e97bbe5. - ---- - -## 1. Multi-Agent Architecture Comparison - -PentAGI implements a "simulated security firm" with 13 specialized AI agents, each with its own system prompt (`.tmpl` file), tool set, and optionally a different LLM model. BLHACKBOX uses Claude Code as a single orchestrating LLM that calls MCP tools directly. - -### Agent Mapping - -| PentAGI Agent | Role | Tool-Call Limit | Tools Available | BLHACKBOX Equivalent | -|---|---|---|---|---| -| **Primary Agent** | Orchestrator — decomposes tasks, delegates to specialists | 100 (general) | `adviser`, `coder`, `installer`, `pentester`, `searcher`, `memorist`, `ask_user` | Claude Code itself | -| **Pentester** | Runs security tools in Docker sandbox | 100 (general) | `terminal`, `file`, `hack_result`, guide tools | Kali MCP (70+ tools) | -| **Coder** | Writes custom exploit code in real-time | 100 (general) | `terminal`, `file`, `code_result`, `search_code`, `store_code`, guide tools | **None** | -| **Installer** | Installs packages/infra into Docker sandbox | 100 (general) | `terminal`, `file`, `browser`, `maintenance_result`, guide tools | **None** (pre-baked images) | -| **Assistant** | General-purpose helper | 100 (general) | Full tool set | Claude Code general capabilities | -| **Searcher** | Web research via 6 search engines | 20 (limited) | `google`, `duckduckgo`, `tavily`, `perplexity`, `traversaal`, `browser`, `search_answer`, `memorist` | Claude's WebSearch | -| **Memorist** | Long-term memory retrieval via vector store | 20 (limited) | `search_in_memory`, `terminal`, `file` | Neo4j (optional, manual Cypher) | -| **Enricher** | Enriches questions with context before Adviser | 20 (limited) | Vector store queries | **None** | -| **Adviser** | Strategic planning (often uses stronger model) | 20 (limited) | Receives enriched context, returns recommendations | Skill templates (static) | -| **Reflector** | Detects text-only responses, forces tool calls | 20 (limited) | Re-prompts agents to use barrier functions | **None** | -| **Generator** | Initial subtask decomposition (up to 15 subtasks) | 20 (limited) | `memorist`, `searcher`, `subtask_list` | Skill templates (static plans) | -| **Refiner** | Adjusts planned subtasks based on progress | 20 (limited) | Subtask modification | **None** | -| **Reporter** | Compiles final task reports | 20 (limited) | `report_result` only | `aggregate_results` MCP tool | -| **Summarizer** | Truncates/summarizes large tool outputs | 20 (limited) | Text processing | **None** | - -### PentAGI Orchestration Flow (from Go source) - -``` -User submits task - │ - ▼ -Generator agent (generator.tmpl) - │ Decomposes task into ≤15 subtasks - │ Queries memorist for similar past tasks - ▼ -For each subtask: - │ - ├─ Primary Agent (primary_agent.tmpl) — runs in a loop - │ │ Has tools: adviser, coder, installer, pentester, searcher, memorist - │ │ - │ ├─ Calls "pentester" → performPentester() - │ │ ├─ Renders pentester.tmpl - │ │ ├─ Gets tools: terminal, file, hack_result - │ │ ├─ Executes commands in Docker (debian or kali-linux) - │ │ └─ MUST call hack_result (barrier function) to return - │ │ - │ ├─ Calls "coder" → performCoder() - │ │ ├─ Renders coder.tmpl - │ │ ├─ Gets tools: terminal, file, code_result, search_code - │ │ ├─ Writes/tests exploit code in container - │ │ └─ MUST call code_result (barrier function) to return - │ │ - │ ├─ Calls "searcher" → performSearcher() - │ │ ├─ Renders searcher.tmpl - │ │ ├─ Gets tools: google, duckduckgo, tavily, perplexity, browser - │ │ └─ MUST call search_result (barrier function) to return - │ │ - │ ├─ Calls "adviser" → Enricher → Adviser chain - │ │ ├─ Enricher fetches context from vector store - │ │ ├─ Adviser (stronger model) provides strategic recommendation - │ │ └─ Returns advice to Primary Agent - │ │ - │ └─ If agent returns text instead of tool call: - │ └─ Reflector (reflector.tmpl) re-prompts to use barrier function - │ - ├─ Refiner agent adjusts remaining subtasks based on results - │ - └─ Loop continues until Primary Agent calls "finaly" barrier - -Reporter agent (reporter.tmpl) - └─ Compiles all subtask results into final report -``` - -### Barrier Function Pattern (Critical Design) - -Each sub-agent has a mandatory "barrier function" — a special tool it MUST call to terminate its loop and return results to the Primary Agent: - -| Agent | Barrier Function | Purpose | -|---|---|---| -| Pentester | `hack_result` | Report pentest findings | -| Coder | `code_result` | Return written code | -| Searcher | `search_result` | Return research | -| Installer | `maintenance_result` | Report infra changes | -| Memorist | `memorist_result` | Return recalled data | -| Reporter | `report_result` | Return compiled report | -| Generator | `subtask_list` | Return subtask plan | - -Without calling its barrier function, an agent's loop continues (up to `maxRetries=3`). The Reflector catches agents that produce text-only responses and forces them back to tool use. - -### Key Architectural Differences - -| Aspect | PentAGI | BLHACKBOX | -|---|---|---| -| **Orchestration** | Go backend with multi-agent delegation loops | Claude Code LLM is the orchestrator | -| **LLM calls** | Multiple LLM calls per agent, per subtask (N agents × M retries) | Single LLM conversation thread | -| **Model routing** | Per-agent model selection via `ProviderOptionsType` | Single model per session (or manual `/fast` toggle) | -| **Tool routing** | Backend assigns restricted tool sets per agent type | Claude decides which MCP tool to call | -| **Tool isolation** | Each agent sees ONLY its allowed tools (enforced in Go) | All MCP tools visible to Claude simultaneously | -| **State management** | PostgreSQL + pgvector + Neo4j + Redis | JSON session files + optional Neo4j | -| **Execution sandbox** | Ephemeral Docker containers per flow (debian or kali-linux) | Persistent Docker containers (Kali MCP, Wire MCP) | -| **Protocol** | Custom REST/GraphQL API | MCP standard | -| **LLM framework** | Custom Go-native agent framework (NOT LangChain — only uses langchaingo for `llms.Tool` type defs) | Native Claude Code / MCP protocol | -| **Retry logic** | `maxRetries=3` per agent chain, 5s delay between retries | No systematic retry mechanism | - ---- - -## 2. PentAGI Features to Adopt - -### P0 — Critical (Highest ROI) - -#### 2.1 Exploit Development Skill (Coder Agent equivalent) - -PentAGI's Coder agent (`coder.tmpl`) has `terminal`, `file`, `code_result`, `search_code`, and `store_code` tools. It writes exploit code in a Docker container, tests it, iterates, and must call `code_result` to return. Critically, successful code is stored via `store_code` for reuse in future engagements (vector-indexed). - -This is the single biggest capability gap in BLHACKBOX. - -**Proposal**: Create a `/exploit-dev` skill that: -- Instructs Claude to enter "developer mode" for exploit writing -- Generates custom PoC scripts based on discovered vulnerabilities -- Adapts public exploits to the specific target environment -- Writes targeted payloads (reverse shells, SQLi chains, XSS payloads) -- Tests exploits inside the Kali container via `run_kali_tool("python3", ...)` and iterates -- Captures successful exploit code in the AggregatedPayload `poc_payload` field - -The Kali MCP already has `msfvenom` for payload generation and `python3` for script execution, but no structured workflow for *custom* exploit development with test-iterate-store loops. - -#### 2.2 Vector Memory System (Memorist + Enricher Agent equivalent) - -PentAGI's memory system has two layers from the Go source: -- **Memorist agent** (`memory.go`): Similarity search with threshold 0.45, documents tagged with flow ID, task ID, subtask ID, and type metadata -- **Searcher store** (`search.go`): Higher threshold 0.75 for storing/retrieving search answers — avoids storing low-quality results -- Documents embedded via pgvector in PostgreSQL; each agent can call `search_in_memory` and `store_*` tools - -BLHACKBOX stores sessions as flat JSON files — not searchable by similarity. - -**Proposal**: Add a pgvector-backed memory service: -1. New MCP tool: `recall_similar_findings(description: str, threshold: float = 0.45, limit: int = 10) -> list[Finding]` -2. New MCP tool: `store_engagement_memory(session_id: str, finding_type: str, content: str)` — auto-embeds via API -3. Auto-embed tool outputs and findings after each `aggregate_results` call (tag with session_id, target, tool_source) -4. On new engagements, skill templates query similar past findings to inform strategy -5. Use per-type thresholds like PentAGI: 0.45 general memory, 0.7 code samples, 0.75 search answers, 0.8 pentest guides - -Could be added as a new Docker service (`memory-mcp`) using PostgreSQL + pgvector, or integrated into the existing blhackbox MCP server. - -### P1 — High Priority - -#### 2.3 Loop Detection & Agent Supervision (Reflector Agent equivalent) - -PentAGI's Reflector (`reflector.tmpl`) catches two specific failure modes from the Go source: -1. **Text-only responses**: Agent produces analysis text instead of calling a tool → Reflector re-prompts to use the barrier function -2. **Tool-call limit approach**: When an agent nears its limit (100 for general, 20 for limited agents), Reflector guides graceful completion - -PentAGI also has retry logic: `maxRetriesToCallAgentChain = 3` with `delayBetweenRetries = 5s`. - -**Proposal**: Implement as a Claude Code hook (session-start or pre-tool): -1. Track tool calls per session (tool name + args hash) -2. Detect patterns: same tool called >3 times with identical args -3. Inject system message: "You appear to be repeating. Reassess your approach or try an alternative tool." -4. Warn when approaching context limits: "You've used N tool calls. Begin wrapping up findings." -5. Track total token usage and inject aggregation reminder at 70% context window - -#### 2.4 Automatic Knowledge Graph Population - -PentAGI uses Graphiti to automatically extract entities and relationships from agent interactions. - -BLHACKBOX's `aggregate_results` already produces structured `AggregatedPayload` with hosts, services, vulnerabilities, and endpoints. This data should auto-populate Neo4j. - -**Proposal**: After `aggregate_results` validation succeeds, automatically: -1. Create `(:Host)` nodes from `findings.hosts` -2. Create `(:Service)` nodes from `findings.services` -3. Create `(:Vulnerability)` nodes from `findings.vulnerabilities` -4. Create `(:Endpoint)` nodes from `findings.endpoints` -5. Create relationships: `(:Host)-[:RUNS]->(:Service)`, `(:Service)-[:HAS_VULN]->(:Vulnerability)`, etc. - -This is low-effort since the structured data already exists in the payload. - -### P2 — Medium Priority - -#### 2.5 Multi-Model Routing in Skills - -PentAGI assigns different models per agent role for cost/quality optimization. - -**Proposal**: Skills could specify model preferences: -```yaml -# In SKILL.md frontmatter -phases: - planning: opus # Deep strategic reasoning - recon: haiku # Fast, cheap parsing - exploitation: opus # Complex exploit development - reporting: sonnet # Balanced quality -``` - -This is partially achievable today via the `Agent` tool's `model` parameter but isn't systematized. - -#### 2.6 Exploit Database Search Tool - -PentAGI integrates Sploitus search for exploit discovery. BLHACKBOX relies on generic web search. - -**Proposal**: Add a Kali MCP tool `search_exploits(query: str, type: str)` that queries: -- `searchsploit` (local ExploitDB) -- Sploitus API (remote exploit aggregator) -- Metasploit module search (`msfconsole -qx "search ..."`) - -### P3 — Lower Priority - -#### 2.7 Dynamic Package Installation - -PentAGI's Installer agent can `apt-get install` new tools at runtime. - -**Proposal**: Add `install_package(name: str)` to Kali MCP. Low effort, edge case utility. - -#### 2.8 Strategic Pre-Planning Agent (Adviser equivalent) - -PentAGI's Adviser uses a stronger model for strategic analysis before execution. - -**Proposal**: A `/plan-engagement` skill that uses Opus to: -1. Analyze the target scope -2. Research the target's technology stack -3. Propose a prioritized attack plan -4. Estimate which tools and phases are most likely to yield results - ---- - -## 3. Where BLHACKBOX is Already Superior - -| Area | BLHACKBOX | PentAGI | -|---|---|---| -| **Tool breadth** | 70+ Kali tools via MCP | ~20 tools | -| **Network analysis** | Dedicated WireMCP (tshark, pcap, credential extraction) | No packet analysis | -| **Evidence capture** | Screenshot MCP (Playwright, annotations, element capture) | Basic scraper only | -| **Client flexibility** | Claude Code + Claude Desktop + ChatGPT via MCP Gateway | Web UI only | -| **Infrastructure simplicity** | 3 containers core stack | 10+ containers | -| **Workflow templates** | 10 production-ready slash command skills | No equivalent | -| **PoC rigor** | Mandatory `evidence`, `poc_steps`, `poc_payload` fields | No enforced PoC structure | -| **Protocol standard** | MCP-native (works with any MCP client) | Custom API | -| **Metasploit integration** | Full msfconsole + msfvenom via CLI | Basic Metasploit | -| **Report formats** | MD + PDF + HTML with AggregatedPayload contract | Less structured | - ---- - -## 4. PentAGI Source Code Reference (Key Files) - -For implementation reference, these are the critical Go source files in PentAGI's backend: - -| File | What It Contains | -|---|---| -| `backend/pkg/providers/provider.go` | `FlowProvider` interface: `GenerateSubtasks`, `RefineSubtasks`, `PerformAgentChain`, `GetTaskResult` | -| `backend/pkg/providers/performers.go` | Agent loop: `performAgentChain()`, `performCoder()`, `performPentester()`, `performSearcher()`, `performInstaller()`, `performMemorist()` | -| `backend/pkg/providers/handlers.go` | Handler factories per agent: `adviserHandler`, `coderHandler`, `pentesterHandler`, `searcherHandler`, `summarizeResultHandler` | -| `backend/pkg/tools/tools.go` | `FlowToolsExecutor` and `ContextToolsExecutor` interfaces; per-agent tool set factory methods | -| `backend/pkg/tools/registry.go` | 31 tool definitions with type classification (Environment, SearchNetwork, SearchVectorDb, Agent, Barrier) | -| `backend/pkg/tools/terminal.go` | Docker container command execution (default 5min timeout, hard limit 20min) | -| `backend/pkg/tools/memory.go` | Vector store similarity search (threshold 0.45) | -| `backend/pkg/tools/search.go` | Search answer retrieval/storage (threshold 0.75) | -| `backend/pkg/templates/templates.go` | 21 `PromptType` constants, `Prompter` interface, embedded `.tmpl` files | -| `backend/pkg/templates/prompts/*.tmpl` | 21 prompt templates (one per agent type + utilities) | - ---- - -## 5. Key Architectural Insights - -1. **PentAGI is NOT LangChain/LangGraph** — It uses a custom Go-native agent framework. Only imports `langchaingo` for `llms.Tool` type definitions. All orchestration, retries, and delegation are hand-written Go. - -2. **Tool isolation is the security model** — The Primary Agent cannot execute commands; it can only delegate. The Pentester cannot write code; it must ask the Coder. This prevents any single agent from having unrestricted capabilities. In BLHACKBOX, Claude sees all tools simultaneously — which works because Claude is good at tool selection, but offers no enforcement. - -3. **Memory is the learning mechanism** — Every agent is instructed to "search long-term memory first" before attempting new work, and to "store results in long-term memory" after completing tasks. 12 specific tools auto-persist their outputs. This makes the system progressively more effective. - -4. **The Coder writes code that the Pentester uses** — The delegation flow is: Primary Agent → Pentester → Coder (when custom exploit code is needed). The Coder does NOT directly execute pentests. - -5. **29 tools across 8 categories** — `EnvironmentToolType` (terminal, file), `SearchNetworkToolType` (Google, DDG, Tavily, Perplexity, Traversaal, browser), `SearchVectorDbToolType` (memory/code/guide/answer search), `AgentToolType` (delegation to sub-agents), `StoreAgentResultToolType`, and `BarrierToolType` (done, ask_user). - -6. **Two-node production deployment** — PentAGI recommends isolating worker execution on a separate server with Docker-in-Docker over TLS, separate network boundaries, and dedicated port ranges for out-of-band attacks. This prevents untrusted exploit code from executing on the primary system. BLHACKBOX runs everything on a single Docker host — worth considering for production deployments. - ---- - -## 6. Summary - -PentAGI's multi-agent architecture provides deeper autonomous reasoning through specialization and cross-session learning. BLHACKBOX's MCP-native architecture provides broader tool access, simpler deployment, and better evidence rigor. - -The three highest-ROI improvements to close the gap: -1. **Exploit development skill** — matches PentAGI's Coder agent -2. **Vector memory system** — matches PentAGI's pgvector-based learning (4 threshold tiers) -3. **Loop detection guardrails** — matches PentAGI's Reflector agent + barrier function pattern - -These additions would capture PentAGI's key differentiators while preserving BLHACKBOX's architectural advantages (70+ tools, MCP standard, 3-container simplicity, mandatory PoC rigor). diff --git a/docs/repo-audit.md b/docs/repo-audit.md deleted file mode 100644 index a387383..0000000 --- a/docs/repo-audit.md +++ /dev/null @@ -1,40 +0,0 @@ -# blhackbox Repository Audit - -## Scope - -This audit covers the current repository structure, MCP servers, Docker/config files, tests, scripts, and Markdown documentation. - -## High-priority findings - -| Area | Finding | Impact | Recommendation | -|---|---|---|---| -| MCP live validation | Static tests cannot prove Docker services are running. | Broken containers or SSE endpoints may pass unit tests. | Use `make check-mcp LIVE=1` after `docker compose up -d`; HexStrike and BOAZ are checked as default services. | -| Tool/catalog drift | Catalogue, Kali allowlist, Dockerfile packages, and MCP configs can drift. | Agents may recommend tools that are unavailable or misrouted. | Use `scripts/tool_inventory.py`; later promote to CI. | -| External binary installs | Dockerfile downloads release artifacts for tools not in apt. | Supply-chain/version drift. | Pin checksums/signatures where available. | -| Integrated services | HexStrike/BOAZ now run in the default compose stack. | Default services can drift from host, gateway, or Claude Code Docker MCP configs if not checked. | Keep `make mcp-status`, `scripts/tool_inventory.py`, and `docs/container-integration-review.md` updated with every service change. | - -## Medium-priority findings - -| Area | Finding | Impact | Recommendation | -|---|---|---|---| -| Workflow profiles | Profiles are currently static lists. | Less adaptive than HexStrike-style decision engine. | Add parameter presets and fallback suggestions per tool. | -| Screenshot MCP | Good screenshot coverage but limited DOM/header analysis. | Misses browser-agent evidence ideas. | Add DOM summary/security-header capture as future safe tools. | -| WireMCP tests | Static tests exist, but pcap fixture coverage can be improved. | Parser regressions may be missed. | Add small sanitized pcap fixtures. | -| Docs | README is comprehensive but long. | New users may miss operator flows. | Split quickstart vs reference sections over time. | - -## Low-priority findings - -| Area | Finding | Impact | Recommendation | -|---|---|---|---| -| CLI catalog | Search is useful but plain. | Operators may want exact workflow display. | Add `blhackbox catalog workflow ` later. | -| Security scan | Offline scanner is intentionally basic. | Does not replace Bandit/pip-audit. | Add optional Makefile target that runs external scanners when installed. | - -## Implemented in this iteration - -- Removed unwanted risk labels/gates from tool discovery. -- Added static/live MCP validation script. -- Added tool inventory consistency script. -- Replaced the local BOAZ helper implementation with a default containerized integration of the upstream BOAZ-MCP Gamma server. -- Added HexStrike Gamma API + upstream MCP service as default containerized integrations. -- Added HexStrike architecture decision docs and workflow profile expansion. -- Added container integration review documentation. From a1d18f57813f2714967cebac27dc0efc7df38eb9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 07:36:35 +0000 Subject: [PATCH 2/2] Align report/session output on output/ (fix results/reports vs output split) config.py was the only component never migrated to the v2.1 output/ layout: results_dir/reports_dir still defaulted to the top-level results/ and reports/ dirs, while skills, templates, docker mounts + entrypoint symlinks, setup.sh, README, and DOCKER.md all use output/. Effect: on the host / Claude Code Web path the core MCP tools (aggregate_results, generate_report) wrote session JSON and reports to results/ + reports/, while the agent's hand-authored docs (per the skills) went to output/ -- splitting a single engagement across two trees and leaving the documented output/ folders looking empty. In Docker the core server isn't wired in, so results/ + reports/ were never written at all. Reconciliation: - config.py: results_dir -> output/sessions, reports_dir -> output/reports (still overridable via RESULTS_DIR / REPORTS_DIR env vars) - remove now-dead top-level results/ and reports/ (.gitkeep) - drop the stale "legacy" results/reports rules from .gitignore - .dockerignore: results/ -> output/ to keep runtime scan data out of the build context (preserves the original protective intent) - sync now-inaccurate docstrings in reporting/paths.py and the generate_report tool description to output/reports/... MCP tool schemas and the AggregatedPayload contract are unchanged. Full test suite passes (201 passed). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01GXPrrB6JQMBGHc19sXhcHw --- .dockerignore | 2 +- .gitignore | 10 ---------- blhackbox/config.py | 6 ++++-- blhackbox/mcp/server.py | 2 +- blhackbox/reporting/paths.py | 6 +++--- reports/.gitkeep | 0 results/.gitkeep | 0 7 files changed, 9 insertions(+), 17 deletions(-) delete mode 100644 reports/.gitkeep delete mode 100644 results/.gitkeep diff --git a/.dockerignore b/.dockerignore index b1782d9..c39fb42 100644 --- a/.dockerignore +++ b/.dockerignore @@ -49,7 +49,7 @@ Dockerfile /LICENSE # Results and data (may contain sensitive scan data) -results/ +output/ wordlists/ neo4j_data/ neo4j_logs/ diff --git a/.gitignore b/.gitignore index d52cc82..6a4a5b3 100644 --- a/.gitignore +++ b/.gitignore @@ -39,16 +39,6 @@ output/** !output/screenshots/ !output/screenshots/.gitkeep -# Legacy results and reports (pre-v2.1) -results/*.json -results/*.pdf -results/*.html -!results/.gitkeep - -# Organized reports (keep folder structure, ignore generated files) -reports/reports-* -!reports/.gitkeep - # Neo4j data neo4j_data/ neo4j_logs/ diff --git a/blhackbox/config.py b/blhackbox/config.py index aa183b0..d7ba691 100644 --- a/blhackbox/config.py +++ b/blhackbox/config.py @@ -44,10 +44,12 @@ class Settings(BaseSettings): ) log_level: str = Field(default="INFO", description="Logging level") results_dir: Path = Field( - default=_REPO_ROOT / "results", description="Directory for scan results" + default=_REPO_ROOT / "output" / "sessions", + description="Directory for scan results", ) reports_dir: Path = Field( - default=_REPO_ROOT / "reports", description="Directory for organized reports" + default=_REPO_ROOT / "output" / "reports", + description="Directory for organized reports", ) wordlists_dir: Path = Field( default=_REPO_ROOT / "wordlists", description="Directory for wordlists" diff --git a/blhackbox/mcp/server.py b/blhackbox/mcp/server.py index c511066..63c4a9a 100644 --- a/blhackbox/mcp/server.py +++ b/blhackbox/mcp/server.py @@ -200,7 +200,7 @@ async def _get_backend() -> ToolBackend: description=( "Generate a professional pentest report from a session. " "Reports are saved to an organized folder structure: " - "reports/reports-DDMMYYYY/report--DDMMYYYY.. " + "output/reports/reports-DDMMYYYY/report--DDMMYYYY.. " "Use format 'both' to generate .md and .pdf together." ), inputSchema={ diff --git a/blhackbox/reporting/paths.py b/blhackbox/reporting/paths.py index 4aeae0c..c4a366a 100644 --- a/blhackbox/reporting/paths.py +++ b/blhackbox/reporting/paths.py @@ -1,7 +1,7 @@ """Organized report path resolution. Creates a structured folder layout for reports: - reports/ + output/reports/ reports-DDMMYYYY/ report--DDMMYYYY.md report--DDMMYYYY.pdf @@ -25,7 +25,7 @@ def _slugify(value: str, max_len: int = 60) -> str: def get_report_dir(date: datetime | None = None) -> Path: """Return the date-specific report sub-directory, creating it if needed. - Example: ``reports/reports-02032026/`` + Example: ``output/reports/reports-02032026/`` """ dt = date or datetime.now(UTC) folder_name = f"reports-{dt.strftime('%d%m%Y')}" @@ -47,7 +47,7 @@ def get_report_path( date: Override date (defaults to UTC now). Returns: - Path like ``reports/reports-02032026/report-example-com-02032026.md`` + Path like ``output/reports/reports-02032026/report-example-com-02032026.md`` """ dt = date or datetime.now(UTC) date_str = dt.strftime("%d%m%Y") diff --git a/reports/.gitkeep b/reports/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/results/.gitkeep b/results/.gitkeep deleted file mode 100644 index e69de29..0000000