HiveBreach

Version 1.0.0 — Autonomous Multi-Agent AI Penetration Testing Framework

Overview • Architecture • Agents • Skills • Installation • Usage • Components • Harness • Governance • Testing • Extensibility • Roadmap • Legal

## Overview HiveBreach is an autonomous multi-agent penetration testing framework powered by 20 specialised AI agents operating under a coordinated ECC (Evolvable Command & Control) architecture. Rather than treating penetration testing as a fixed script or a single monolithic scanner, HiveBreach deploys a swarm of expert agents each owning a distinct attack surface — network recon, DNS enumeration, web exploitation, cloud posture analysis, credential testing, pivot tunnelling, and more — all coordinated through a deterministic orchestration loop with an immutable audit trail and a non-negotiable scope authorisation gate at every step. The framework implements a five-stage autonomic core loop that governs every engagement, adapting ECC's Plan, Execute, Verify, Learn, and Persist cycle to the specific demands of autonomous security testing. During the Plan phase, the scheduler-agent decomposes the target scope into a directed acyclic graph of tasks, assigning each to the appropriate agent based on capability and risk profile and resolving inter-agent dependencies so that a credential harvesting task is never scheduled before the target service running on that host has been confirmed reachable by the recon-agent. In the Execute phase, agents operate autonomously within their sandboxed and scope-gated boundaries, using kill-chain-mapped tools from the toolbelt registry and consulting MITRE and OWASP mapped skill playbooks from the knowledge layer as reference material rather than rigid scripts, preserving each agent's ability to improvise chained and creative exploits that a fixed procedure would miss. The Verify phase runs every finding through a dual-track validation pipeline managed by the validator-agent. Exploit-verified findings are reproduced in an isolated Docker sandbox for high-confidence confirmation, while state-verified findings undergo direct config or posture confirmation using an independent method such as an idempotent API call or a secondary tool with a different detection mechanism; each track carries an explicit confidence label in the final report so that readers know which findings were proven by exploitation and which were confirmed to exist but not exploited. During the Learn phase, the instinct system extracts repeatable patterns from validated findings and feeds them back into the skill library as reusable playbooks, creating a closed feedback loop where every successful engagement improves the framework's knowledge for the next one. Finally, the Persist phase saves session memory, audit logs with HMAC-SHA256 chain-of-custody integrity, and encrypted finding data to the sessions directory to enable cross-session context resumption, allowing an operator to stop an engagement mid-flight, power down the host, and resume exactly where they left off by loading the most recent serialised session state. HiveBreach is provider-agnostic at the LLM layer, supporting three backend tiers with automatic fallback between them. Ollama provides fully offline and air-gapped operation using locally hosted open-weight models, suitable for privacy-sensitive engagements where target data must never leave the operator's network. NVIDIA NIM provides free hosted inference at production model quality without requiring local GPU hardware, routing requests through a shared rate-limited API that is suitable for the majority of agent reasoning tasks. Paid API keys from OpenAI or Anthropic are reserved for the highest-stakes reasoning steps such as orchestrator replanning after a delegation failure and exploit PoC validation logic where the cost of a reasoning mistake is highest. The model router selects the optimal backend per agent and per task, routing simple recon parsing to a small local model while reserving paid API calls for critical reasoning paths, and falling back through the configured backend chain if the primary provider returns a rate-limit error or a timeout. ## Architecture HiveBreach's architecture is organised into six vertically integrated layers that span the entire engagement lifecycle from target specification to final report generation. Each layer encapsulates a distinct responsibility and communicates with adjacent layers through well-defined interfaces. The Execution Layer is the runtime environment where all agent actions take place. It includes the Docker sandbox for isolated exploit reproduction, the encrypted secrets vault for credential handling with AES-256-GCM short-retention storage, and the dual-track PoC validator that classifies each finding as exploit-verified or state-verified with an explicit confidence label. The Knowledge Layer contains the structured skill playbooks mapped to MITRE ATT&CK technique IDs and OWASP categories. Each playbook is a markdown file with YAML frontmatter metadata specifying the technique ID, difficulty level, verification method, and references. Skills are ingested from curated authoring and from an automated CVE/KEV feed pipeline that lands new entries into a staging state until they pass a validated use before promotion to active status. The Agent Layer is the roster of 20 expert agents, each defined by an ECC-style agent card with YAML frontmatter specifying harness compatibility, stage, tools, verification method, and communication peers. Agents operate autonomously, posting findings and requests to the communication bus rather than following rigid step-by-step scripts. The Toolbelt Layer is a kill-chain-mapped registry of 38 security tools, each entry specifying version, category, kill-chain stage, risk level, sandbox and authorisation requirements, agent ownership, and MITRE technique mappings. The Orchestration Layer is the control plane comprising the model router for LLM backend selection, the deterministic scope gate that enforces Rules of Engagement as a hard non-LLM boundary, the sanity check layer for pre-delegation invariant verification, the scheduler for DAG-based pipeline orchestration, and the communication bus for agent pub-sub messaging. The Governance Layer wraps the entire framework with Rules of Engagement templates, an immutable HMAC-chained audit trail, compliance mapping to SOC2, PCI-DSS, ISO 27001, and NIST frameworks, and a credential-voucher system for scope-token verification on every agent action. The engagement flow follows a linear progression through six phases that mirrors a professional penetration testing methodology, with the scope gate and sanity check layer interleaved at every transition to ensure no action executes without authorisation. The Planning phase is owned by the orchestrator and scheduler-agent, performing target prioritisation based on the active ROE and agent assignment into a directed task graph with explicit dependency edges. The orchestrator reads the target profile from the recon-agent's initial deep fingerprinting output, which includes operating system versions, service banners, technology stack identification, and WAF detection, and uses this information to select the relevant skill playbooks and assign the appropriate specialist agents. The Reconnaissance phase deploys the recon-agent for port scanning and host discovery, the dns-agent for DNS enumeration, zone transfer attempts, and subdomain discovery through both passive OSINT sources and active brute-force techniques, and the web-discover-agent for directory brute-forcing, virtual host enumeration, parameter fuzzing, and technology fingerprinting using httpx and whatweb. Every recon action is logged with its target, technique, and raw output in the audit trail, and the aggregate results form the target profile that all downstream agents reference. The Exploitation phase activates the exploit-agent for Metasploit module selection and payload generation, the web-exploit-agent for SQL injection, XSS, SSRF, and command injection testing using sqlmap, xsser, commix, and burpsuite, the creed-creds-agent for credential harvesting and password spraying using hydra and responder with explicit ROE authorisation gating, and the pivot-agent for lateral movement tunnelling using chisel and sshuttle. Each exploitation action is filtered through the scope gate with sandbox-only defaults for high-risk operations, and tools classified as requiring sandbox execution are automatically routed to isolated Docker containers. The Analysis phase runs the analyzer-agent for log correlation and pattern detection using jq and custom parsers, the state-agent for configuration drift detection and system state verification using ansible and osquery, the risk-agent for CVSS v4.0 scoring and impact assessment, and the validator-agent for dual-track PoC reproduction in the Docker sandbox, generating a confidence score for each finding based on whether it was reproduced, confirmed via independent method, or unconfirmed. The Reporting phase engages the report-agent for generating structured reports with OWASP Top 10, MITRE ATT&CK technique IDs, CWE root-cause classification, CVSS severity scoring, and SOC2, PCI-DSS, ISO 27001, and NIST compliance framework tagging, and each fix suggestion carries a non-removable disclaimer that it is a suggested remediation for developer review and has not been validated as a patch. The Cleanup phase runs the sandbox-agent unconditionally to restore container state to the baseline snapshot, clear credential caches from the vault, remove uploaded test artifacts, and reset network proxy configurations, with every cleanup action recorded in the HMAC-chained audit trail and a cleanup completion summary sent to the orchestrator before the engagement is marked as finished. ## Agent Roster The full agent roster comprises 20 specialised agents organised across five operational stages. Each agent is defined by an ECC-standard agent card specifying its harness compatibility, tools, verification method, and communication peers. | Agent Name | Role | Stage | Risk Level | Default Mode | Communications | |---|---|---|---|---|---| | recon-agent | Network reconnaissance, host discovery, port scanning | recon | low | autonomous | vuln-scan-agent, scheduler-agent, audit-agent | | dns-agent | DNS enumeration, subdomain discovery, zone transfer | recon | low | autonomous | web-discover-agent, risk-agent, audit-agent | | web-discover-agent | Web app discovery, directory brute-force, endpoint mapping | recon | low | autonomous | web-exploit-agent, dns-agent, audit-agent | | vuln-scan-agent | Vulnerability scanning, CVE matching, misconfiguration detection | recon | medium | autonomous | exploit-agent, risk-agent, audit-agent | | exploit-agent | Exploit selection, payload generation, delivery orchestration | exploitation | critical | sandbox-only | vuln-scan-agent, pivot-agent, validator-agent, audit-agent, sandbox-agent | | web-exploit-agent | Web exploitation, SQLi, XSS, SSRF, RCE, LFI/RFI | exploitation | high | scope-gated | web-discover-agent, creed-creds-agent, validator-agent, audit-agent | | creed-creds-agent | Credential harvesting, password spraying, hash capture | exploitation | critical | sandbox-only unless RoE authorises | exploit-agent, pivot-agent, report-agent, audit-agent, vault-agent | | pivot-agent | Lateral movement, tunnel establishment, proxy chains | exploitation | critical | sandbox-only | exploit-agent, creed-creds-agent, sandbox-agent, audit-agent | | analyzer-agent | Log analysis, pattern detection, indicator extraction | analysis | low | autonomous | state-agent, risk-agent, report-agent, audit-agent | | state-agent | System state verification, config drift detection | analysis | low | autonomous | analyzer-agent, validator-agent, audit-agent, config-agent | | risk-agent | Risk scoring, impact assessment, priority ranking | analysis | low | autonomous | vuln-scan-agent, report-agent, scope-agent, audit-agent | | report-agent | Report generation, evidence packaging, executive summary | analysis | low | autonomous | risk-agent, validator-agent, audit-agent | | scope-agent | ROE enforcement, target validation, boundary compliance | support | low | autonomous | recon-agent, exploit-agent, scheduler-agent, audit-agent | | audit-agent | Full telemetry capture, chain-of-custody logging, immutable audit trail | support | low | autonomous | all agents, report-agent | | scheduler-agent | Pipeline orchestration, dependency resolution, parallel execution | support | low | autonomous | all agents, audit-agent | | validator-agent | PoC validation, exploit verification, confidence scoring | support | low | autonomous | exploit-agent, web-exploit-agent, report-agent, sandbox-agent, audit-agent | | sandbox-agent | Docker sandbox lifecycle, snapshot and restore, health checks | infrastructure | low | autonomous | exploit-agent, pivot-agent, validator-agent, audit-agent | | vault-agent | Secrets management, AES-256-GCM encryption, key rotation | infrastructure | medium | autonomous | creed-creds-agent, config-agent, audit-agent | | config-agent | Configuration distribution, env injection, dynamic parameter resolution | infrastructure | low | autonomous | state-agent, vault-agent, scheduler-agent, audit-agent | | comm-agent | Inter-agent messaging, result routing, LLM abstraction | infrastructure | low | autonomous | scheduler-agent, all agents, audit-agent | Agents communicate through the communication bus using structured JSON messages routed by the scheduler-agent. Each message carries a from-agent and to-agent routing field, a correlation ID for full traceability through the audit trail, a payload with the action-specific data, and a scope token that the scope gate verifies against the active Rules of Engagement before the action executes. All messages are captured by the audit-agent with HMAC-SHA256 chain-of-custody metadata, ensuring that every agent decision and tool invocation can be reconstructed and verified after the fact. ## Skill Library The knowledge layer contains structured skill playbooks that provide agents with technique-specific procedures, tool guidance, and verification criteria. Each playbook is a markdown document with YAML frontmatter specifying the MITRE ATT&CK technique ID, OWASP mapping where applicable, difficulty rating, and reference links. Skills are organised by domain and are consulted by agents as reference knowledge rather than obeyed as fixed scripts, preserving the autonomous reasoning capability of each agent. | Skill Playbook | MITRE Mapping | Difficulty | Domain | |---|---|---|---| | Port Scanning | T1046 | beginner | network-security | | Service Enumeration | T1040 | beginner | network-security | | SQL Injection | T1190 | intermediate | penetration-testing | | IAM Misconfiguration (AWS) | T1525 | intermediate | cloud-security | | Identity Recon (Azure AD) | T1525, T1087 | intermediate | cloud-security | | GraphQL Testing | T1190 | advanced | api-security | | Android Insecure Storage | T1212 | intermediate | mobile-security | | Incident Triage (DFIR) | T1003, T1046 | advanced | dfir | | Static Malware Analysis | T1204, T1059 | advanced | malware-analysis | | Threat Intelligence Collection | TA0011 | intermediate | threat-intel | | API Security Testing | T1190, T1498 | intermediate | api-security | Skill playbooks are authored manually by security engineers and are also auto-ingested from CVE and Known Exploited Vulnerabilities feeds. Auto-ingested entries land in the staging directory and are only promoted to active use after a maintainer review or one successful validated use in a real scan. This ensures that low-quality or malformed feed entries never become live agent behaviour without a quality gate. ## Installation HiveBreach requires Python 3.10 or later and Docker for sandbox-based execution. LLM inference can use Ollama for fully offline operation, NVIDIA NIM for free hosted inference, or paid API keys from OpenAI or Anthropic for advanced reasoning tasks. # Clone the repository git clone https://github.com/m524security/HIVEBREACH.git cd HIVEBREACH # Install the Python package in development mode pip install -e . On Windows, the install.ps1 script bootstraps a Python virtual environment, activates it, installs the package with development dependencies, and validates the installation by importing the hivebreach package. On Linux and macOS, the equivalent install.sh script performs the same steps using a POSIX-compatible toolchain. # Windows PowerShell bootstrap .\install.ps1 # Linux and macOS bootstrap chmod +x install.sh ./install.sh The following environment variables must be configured in a .env file copied from .env.example. The LLM backend selection supports Ollama, NVIDIA NIM, OpenAI, or Anthropic as the provider with automatic fallback between configured backends if the primary provider is unreachable or rate-limited. LLM_BACKEND=ollama OLLAMA_HOST=http://localhost:11434 NVIDIA_NIM_API_KEY=nvapi-... OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... SCOPE_FILE=governance/rules-of-engagement-template/roe-template.md SANDBOX_ENABLED=true MAX_CONCURRENT_AGENTS=5 AUDIT_LOG_DIR=sessions/ SECRETS_RETENTION_HOURS=24 ECC_HOOK_PROFILE=standard The ECC_HOOK_PROFILE variable selects the hook gating profile. The minimal profile runs only pre-scan and post-scan lifecycle hooks without persistence. The standard profile adds session save and load hooks for cross-session memory. The strict profile adds on-finding hooks that pause the pipeline for human review on critical-severity findings before proceeding. ## Tool Belt Registry The toolbelt directory at toolbelt/registry.json contains the ECC-style tool registry that maps 38 security tools across the full cyber kill chain. Each tool entry in the registry is a structured JSON object with the name and version of the tool, the category from a controlled vocabulary of recon, exploitation, analysis, infrastructure, governance, and utilities, the kill-chain stage identifying which phase of an attack lifecycle the tool supports, a prose description of the tool's capabilities and typical use cases, a usage guide showing the primary invocation pattern, a risk level from low through critical that determines the sandbox and authorisation requirements, a boolean flag for sandbox requirement that the execution engine uses to decide whether to route the tool invocation through Docker, a boolean flag for authentication requirement indicating the tool needs valid credentials to operate, a list of agent mappings that identifies which agents in the roster are authorised to invoke this tool, and a list of MITRE ATT&CK technique IDs that the tool's primary purpose maps to. The recon category includes nmap for comprehensive port scanning with NSE scripting, masscan for high-speed internet-scale scanning, naabu for fast SYN scan with built-in nmap pipelining, rustscan for ultra-fast port discovery with automatic nmap handoff, dnsrecon for full DNS enumeration including zone transfer attempts, subfinder and amass for passive and active subdomain discovery, ffuf and gobuster for web content brute-forcing, httpx for live host probing and technology fingerprinting, nuclei for YAML-template-driven vulnerability scanning, and nikto for web server misconfiguration detection. The exploitation category includes metasploit for full-featured exploit delivery and post-exploitation, sqlmap for automated SQL injection detection and data extraction, hydra for parallelised network protocol brute-force testing, responder for NTLM hash capture and relay, impacket for Windows protocol toolkit including secretsdump and psexec, hashcat and john for GPU-accelerated and CPU-based password hash cracking, burpsuite for web proxy and manual exploitation workflows, xsser for automated cross-site scripting detection, jwt_tool for JSON Web Token security auditing, and commix for command injection detection. The analysis category includes jq for structured JSON data processing across all tool outputs, volatility for memory forensics and kernel object analysis, binwalk for firmware extraction and embedded file identification, wireshark for network packet capture analysis and protocol dissection, prowler for multi-cloud security auditing against CIS benchmarks, cloudsplaining for AWS IAM least-privilege policy analysis, and azurehound for Azure AD identity relationship mapping. The infrastructure category includes docker for sandbox container lifecycle management, ansible for configuration management and automated state verification, and terraform for ephemeral cloud infrastructure provisioning and teardown. The utilities category includes python for custom exploit scripting and data processing, curl for raw HTTP request crafting and response analysis, git for repository reconnaissance and exposed directory detection, and openssl for TLS certificate inspection and cipher suite validation. ## Usage from orchestration.orchestrator import HiveOrchestrator import asyncio async def main(): orchestrator = HiveOrchestrator( roe_path="governance/rules-of-engagement-template/roe-template.md", llm_config="orchestration/llm-router/config.yaml", ) session = await orchestrator.run_engagement( targets=["api.acme.com", "app.acme.com", "admin.acme.com"], sandbox_mode=True, ) orchestrator.save_session("sessions/latest.pkl") findings = orchestrator.export_findings() print(f"Total findings: {findings['summary']['total_findings']}") print(f"By severity: {findings['summary']['by_severity']}") asyncio.run(main()) The CLI interface provides commands for running engagements, resuming previous sessions, and validating specific PoCs independently. # Full engagement scan across multiple targets python -m hivebreach scan --targets api.acme.com,app.acme.com --roe scope_rules.yaml # Quick reconnaissance-only scan suitable for CI pipelines python -m hivebreach scan --targets api.acme.com --mode recon --ci # Deep scan activating all agents across the full kill chain python -m hivebreach scan --targets acme.com --mode deep # Resume a persisted session for continued analysis or re-testing python -m hivebreach resume --session sessions/latest.pkl # Independently validate a specific PoC by its correlation ID python -m hivebreach validate --poc-id abc-123-def ## System Components ### Harness The ECC agent harness operating system provides the foundational abstraction layer that makes HiveBreach portable across all major AI agent runtimes. The harness abstracts harness-specific capabilities such as tool execution, file system access, permission management, and context window handling behind a uniform interface, enabling agent definitions and skill playbooks to be authored once and executed on Claude Code, Cursor, OpenCode, Codex, Gemini, Zed, or GitHub Copilot without modification. HiveBreach is currently configured for the OpenCode harness but the agent card YAML format includes a harnesses field that can be extended to any supported runtime. ### Hook System Hooks are lifecycle callbacks that fire at predetermined points during an engagement, enabling cross-cutting concerns such as scope verification, session persistence, and audit logging without embedding that logic in agent code. The pre-scan hook runs before any agent action executes, performing a deterministic scope gate check against the active Rules of Engagement and rejecting any action targeting an unauthorised host or using a prohibited technique. The post-scan hook runs after each agent action completes, capturing raw tool output, LLM reasoning, and scope gate decisions into the HMAC-chained audit trail. The on-finding hook fires when a validated finding is produced, enabling notification, human approval gates, or automatic report section generation. The hook profile is selected via the ECC_HOOK_PROFILE environment variable and controls which hooks are active and whether they are blocking or non-blocking. The standard profile enables all hooks in non-blocking audit mode, recording every action without pausing the pipeline. The strict profile promotes the on-finding hook to blocking mode for critical-severity findings, pausing the engagement until a human reviewer explicitly approves or rejects the finding before the pipeline continues. The minimal profile disables persistence hooks and runs only the scope gate pre-scan hook, suitable for ephemeral CI environments where session state does not need to survive beyond the current run. ### Command System The command system provides slash-prefixed directives that can be issued to the orchestrator at runtime to control engagement behaviour without modifying configuration files. The plan command decomposes the current target scope into a task DAG and assigns each task to the appropriate agent. The multi-plan command parallelises planning across multiple target groups, useful for large-scale engagements spanning diverse infrastructure. The harness-audit command performs a compatibility check of all agent definitions against the currently active harness, flagging unsupported tool or permission configurations before the engagement starts. The quality-gate command runs the verification pipeline against the current finding set and produces a confidence report without proceeding to reporting. The model-route command dynamically reassigns LLM backends for specific agents during an active engagement, useful for escalating a difficult reasoning task from a local model to a paid API endpoint without restarting the scan. The security-scan command runs a self-audit of the HiveBreach installation, checking for known-vulnerable dependency versions, exposed secrets in configuration files, and sandbox integrity. ### Rules Framework The rules framework provides a set of invariant checks that are enforced by the sanity-check layer before any agent delegation is executed. Rules are stored in the rules directory and are organised by scope, with common rules that apply globally and agent-specific rules that apply only when a particular agent is delegated a task. Each rule is a deterministic predicate that evaluates to pass or fail given the current task context, target metadata, and active Rules of Engagement. Example rules include rejecting mobile application decompilation tasks when assigned to the network expert agent, rejecting credential spraying tasks when no explicit authorisation flag is present in the ROE, and rejecting any action against a target outside the authorised IP range or domain list. ### Memory Persistence Session memory is saved and loaded across engagement runs through the hooks system, enabling HiveBreach to resume interrupted scans, incorporate findings from previous sessions into new target analysis, and maintain agent state across multi-day engagements. Memory snapshots are serialised to the sessions directory as pickle files and include the full agent state, finding set, audit log chain head, and scope gate decision cache. The persistence hook fires automatically on engagement completion and can be triggered manually through the CLI resume command. ### Instinct System The instinct system is a continuous learning mechanism that extracts repeatable patterns from validated findings and feeds them back into the skill library as new or updated playbooks. When the validator-agent confirms a high-confidence finding through the exploit-verified track, the instinct system analyses the technique used, the tool invocation that produced the result, and the environment characteristics that enabled the exploit. It then generates a structured skill playbook entry with the appropriate MITRE technique mapping, tool usage guide, and verification procedure, which lands in the skill library staging area for review. Over time, this creates a closed learning loop: the skill library teaches agents what to try, agents produce findings, validated findings generate new skills, and the library grows organically with the operator's specific target environment. ### Token Optimization The model router implements token-aware backend selection to minimise API costs and latency while maintaining output quality. Trivial and easy tasks such as port scan result parsing, JSON data extraction, and status code classification are routed to small local models with minimal context windows. Intermediate tasks such as vulnerability analysis, cross-referencing tool outputs, and report section drafting use mid-size hosted models. Hard and critical tasks such as orchestrator replanning, exploit PoC generation, and multi-step reasoning chains are routed to the most capable available backend, which may be a paid API endpoint if configured. The router also implements system prompt slimming, stripping unnecessary context from agent prompts when the target task does not require full session history, reducing token consumption on every call. ### Parallelization The scheduler-agent implements DAG-based task parallelism, resolving dependencies between agent actions and executing independent tasks concurrently. Network reconnaissance of multiple targets proceeds in parallel because each recon-agent instance operates independently. Exploitation tasks that depend on recon results are gated behind the recon completion signal and execute as soon as their input dependencies are satisfied. The parallelization model extends to sandbox instances, with each sandbox running as an independent Docker container that can be snapshotted, restored, and destroyed independently of other sandboxes. The MAX_CONCURRENT_AGENTS environment variable caps the total parallel agent count to prevent resource exhaustion on the host machine. ### AgentShield AgentShield is the security self-defence layer that protects the HiveBreach installation itself from the tools it invokes. Every tool executed from the toolbelt registry is checked against a known-safe invocation policy that restricts argument patterns, file system access paths, and network destinations. Tools classified as requiring sandbox execution are automatically routed to a Docker container with a read-only root filesystem, restricted network access, and no persistent storage to prevent the tool from modifying the host system or exfiltrating data. The audit-agent captures every tool invocation with its full command line, working directory, exit code, and standard output, enabling forensic reconstruction of any security incident involving the toolbelt. ## Architecture Gallery The following YAML block is the complete ECC-style harness descriptor for HiveBreach, specifying the framework name, version, registered agents, skill paths, hook profile, available commands, and rules directories. This descriptor can be consumed by ECC-compatible harnesses for automated agent discovery, skill indexing, and hook registration. name: HiveBreach version: 1.0.0 harness: opencode agents: - recon-agent - dns-agent - web-discover-agent - vuln-scan-agent - exploit-agent - web-exploit-agent - creed-creds-agent - pivot-agent - analyzer-agent - state-agent - risk-agent - report-agent - scope-agent - audit-agent - scheduler-agent - validator-agent - sandbox-agent - vault-agent - config-agent - comm-agent skills: - network-security/port-scanning - network-security/service-enumeration - penetration-testing/sql-injection - cloud-security/aws/iam-misconfiguration - cloud-security/azure/identity-recon - api-security/graphql-testing - mobile-security/android-insecure-storage - dfir/incident-triage - malware-analysis/static-analysis - threat-intel/threat-intel - api-security/api-security-testing hooks_profile: standard commands: - /plan - /multi-plan - /harness-audit - /quality-gate - /model-route - /security-scan rules: - rules/common/ - rules/python/ - rules/shell/ ## Governance HiveBreach implements a multi-layer governance model that ensures every engagement operates within defined legal, safety, and compliance boundaries. The outermost layer is the Rules of Engagement, a human-authored document that specifies the target scope as a whitelist of domains, IP ranges, and CIDR blocks, the testing window with explicit start and end timestamps, rate limits expressed as maximum requests per second per target, credential testing authorisation with sandbox-only default, wireless testing authorisation as a separate clause requiring explicit jurisdiction-specific legal review, data handling and retention policies, and an emergency contact and kill-switch procedure. The scope gate is the single non-negotiable hard boundary in the system. Unlike every other component in HiveBreach, the scope gate is implemented as deterministic Python code with no LLM involvement. It parses the active Rules of Engagement document, builds an in-memory authorisation trie mapping every target and action type to an allow or deny verdict, and intercepts every agent action before execution. If an action targets a host outside the authorised scope, uses a technique prohibited by the ROE, exceeds the rate limit, or lacks a valid scope token, the gate returns a hard deny and logs the rejection to the audit trail with the full context of what was attempted and why it was rejected. The gate is non-removable in the framework design: any engagement must have a valid ROE loaded before the orchestrator will initialise, and the gate is wired into the delegation path at the infrastructure level rather than the application level. The immutable audit trail captures every agent action, tool invocation, scope gate decision, verification result, and system event with HMAC-SHA256 integrity chaining. Each log entry includes the agent ID, action type, target identifier, ISO 8601 timestamp with microsecond precision, the raw tool output and LLM reasoning, the scope gate verdict with the matching ROE clause citation, the verification track and confidence score, and the HMAC of the previous log entry, forming an unbroken chain that makes any tampering detectable by recomputing the chain from the first entry. The audit trail is stored in the sessions directory and can be exported as JSON or CSV for external analysis. The compliance mapping layer attaches regulatory framework references to every finding, enabling security teams to map technical vulnerabilities directly to audit controls. The current mapping covers 18 SOC2 controls across the CC1 through CC7 and A1 through A3 categories for SaaS security audits, 15 PCI-DSS requirements across all 12 requirement families for payment card industry assessments, 27 ISO 27001 controls spanning clauses A.5 through A.18 for information security management systems, and 40 NIST 800-53 controls across the AC, AU, IA, SC, and SI control families for US federal and defence engagements. ## Testing The test suite validates the core orchestration, scope gate, and sandbox components through 45 tests across three test files. Tests use pytest and the standard library, with no external test dependencies beyond the framework's own packages. # Run the full test suite with verbose output pytest tests/ -v # Run individual test suites pytest tests/test_orchestrator.py -v pytest tests/test_scope_gate.py -v pytest tests/test_sandbox.py -v # Run with coverage reporting pytest tests/ --cov=. -v The test_orchestrator.py suite contains 9 tests covering agent registration, scope enforcement integration, pipeline DAG construction and execution, audit logging, and session serialization and deserialization round-trips. The test_scope_gate.py suite contains 11 tests covering target allow and deny list matching, action type filtering by ROE, depth and rate limit enforcement, compound rule evaluation, and empty or invalid ROE rejection. The test_sandbox.py suite contains 25 tests covering container creation, destruction, and reset, health check polling and timeout, snapshot creation and restore, command execution within the container, network lifecycle management, and resource cleanup on failure. ## Extensibility New agents can be added to the roster by creating a directory under the agents directory with three files following the established template. The agent.md file contains the ECC-style agent card with YAML frontmatter specifying the agent name, harness compatibility, operational stage, tool list, verification method, and communication peers. The skill-playbook.md file contains the technique-specific procedures the agent will consult during operations. The master-prompt.md file contains the full system prompt defining the agent's mission, scope boundaries, communication protocol, verification requirements, and output format. The agent template directory at agents/agent-template provides a complete skeleton for new agent creation. The template includes a fully commented agent card, a sample skill playbook with a single technique, and a master prompt with placeholder sections for mission definition, tool configuration, and handoff conditions. To add a new agent, copy the template directory to a new name, update the agent card metadata, write the domain-specific skill playbooks referencing tools from the toolbelt registry, and register the agent name in the harness descriptor and the scheduler-agent's agent registry. New hooks can be added by creating a Python module in the hooks directory and registering it in the hooks registry at hooks/registry.py. Each hook module implements a handler function that receives the current engagement context, inspects the action or state, and returns a verdict or modification. Hooks are classified as pre-scan, post-scan, or on-finding and are invoked by the orchestrator at the corresponding lifecycle point. ## Roadmap ### Tier 1 Tier 1 capabilities are implemented in the current release and form the foundation of the framework. Secrets scanning using gitleaks and trufflehog runs as a dedicated reconnaissance step before any active testing begins, catching leaked API keys and credentials as the highest-signal and lowest-cost check in the pipeline. Software composition analysis and SBOM generation using Syft and Grype identifies known-vulnerable dependencies in the target stack, mapping each CVE to the relevant MITRE technique and skill playbook. The threat modeling agent runs before active testing, analysing the target architecture to prioritise the highest-risk attack paths and reduce exhaustive scans to fast risk-ranked sweeps. The CVE and KEV feed auto-ingestion pipeline pulls new entries from NVD and CISA on a configurable schedule, generating skill playbook stubs that land in the staging directory for review and promotion. ### Tier 2 Tier 2 capabilities are planned for the next development cycle and focus on production-readiness and human oversight. A human-in-the-loop approval gate for critical and high-severity findings will pause the pipeline and send a notification through a configurable channel such as Slack, email, or webhook, requiring explicit approval or rejection before the finding proceeds to the report. A CI-mode versus deep-mode split will enable quick diff-focused scans for pull request CI pipelines that must complete within minutes alongside full-sweep scheduled scans that run the complete multi-agent roster against the entire attack surface. A cost and rate-limit governor dashboard will track API token consumption, NIM request throughput, and local hardware utilisation, providing budget visibility and preventing runaway scans from silently failing or overspending. A compliance report overlay will map every finding in the final report to its corresponding SOC2, PCI-DSS, ISO 27001, and NIST controls, making the output directly usable by audit and compliance teams. ### Tier 3 Tier 3 capabilities extend the framework into an ecosystem with advanced visualisation, community extensibility, and web-based management. An attack path and chain visualiser will render the relationship graph between individual findings as a directed attack chain, showing how a low-severity information disclosure chains through a medium-severity privilege escalation into a critical-severity domain compromise, similar to BloodHound but generalised beyond Active Directory to web, cloud, and network findings. A plugin and extensibility architecture will allow community-contributed agents to register with the orchestrator without forking the core repository, using a stable plugin API for agent card registration, toolbelt entries, and skill playbook association. A web-based dashboard built with a reactive frontend framework will provide session monitoring, finding browsing, report preview, and manual action approval workflows without requiring terminal access. ## Legal HiveBreach is designed exclusively for authorised security testing against systems you own or have explicit written permission to test under a signed Rules of Engagement. The scope and authorisation gate is deterministic and non-removable in the framework design specifically because autonomous agents operating without it would constitute unauthorised access, which is illegal in most jurisdictions regardless of intent. Building or operating a HiveBreach deployment without the authorisation layer, removing the scope gate from the pipeline, or using the framework against systems without written authorisation is outside the intended and supported use of this software. Every finding report generated by the report-agent includes the following fixed and non-removable disclaimer as the final line of every fix suggestion: "This is a suggested remediation for developer review — it has not been applied or validated as a patch." This disclaimer moves the remediation caveat from a design principle into the actual output that the report reader sees every time, ensuring that developer teams understand the suggested fix has not been tested in production and requires independent validation before deployment. The same disclaimer principle extends to all credential-related findings: the report-agent references that a credential or secret was discovered and specifies the affected service or endpoint, but never embeds the live credential value in the human-readable report, routing it instead to the encrypted vault with automatic expiry. Users of HiveBreach are responsible for ensuring compliance with all applicable laws and regulations in their jurisdiction, including but not limited to the Computer Fraud and Abuse Act in the United States, the Computer Misuse Act in the United Kingdom, the Network and Information Security Directive in the European Union, the Criminal Code computer crime provisions in Canada and Australia, and any applicable data protection regulations such as GDPR, CCPA, or LGPD. The framework is provided as a tool for professional security researchers, authorised penetration testers, and defensive security teams operating under a properly scoped Rules of Engagement. It is not a general-purpose utility for unauthorised access, data exfiltration, or any other activity that would violate applicable law. Operators should consult legal counsel before deploying HiveBreach against any target to ensure compliance with all relevant statutes and regulations, particularly when testing across jurisdictional boundaries where the legal framework governing security research and penetration testing may differ between the operator's location and the target's location. Responsible disclosure principles apply to all findings discovered through HiveBreach engagements. Critical and high-severity vulnerabilities affecting third-party software or infrastructure should be reported through established disclosure channels such as the vendor's security contact, a bug bounty programme, or a CERT coordination centre before any public disclosure. The framework's report generation pipeline includes a disclosure-ready template that redacts sensitive operational details while providing sufficient technical information for the vendor to reproduce and remediate the finding.

标签：AI风险缓解, CISA项目, DLL 劫持, Docker, IP 地址批量处理, Petitpotam, PyRIT, 人工智能, 多智能体系统, 大语言模型, 安全防御评估, 密码管理, 用户模式Hook绕过, 请求拦截, 运行时操纵, 逆向工具