# vhater/hexstrike-ai-community-edition architecture

> Architecture diagram of the GitHub repository vhater/hexstrike-ai-community-edition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vhater/hexstrike-ai-community-edition
- Repository: https://github.com/vhater/hexstrike-ai-community-edition

## Overview

1. HexStrike AI is a two-tier Python platform: a local MCP client launches tools through a separate HTTP API server. The user-facing side is the MCP entrypoint (`hexstrike_mcp.py`), and the execution side is the server (`hexstrike_server.py`), which exposes security-tool actions and AI-assisted orchestration.

2. The main architecture boundary is client vs. server. `mcp_core/` contains argument parsing, server setup, colored logging, and the MCP client plumbing. The client decides which tool sets to expose using compact/profile flags, then forwards requests to the server over HTTP.

3. `server_api/` is the HTTP surface area. It is organized by security domain—web, network, cloud, binary, password cracking, recon, etc.—and acts as the server-side façade for tool operations. This is the layer that would map API calls into actual execution and domain-specific handlers.

4. `server_core/` is the platform runtime. It provides command execution, process management, caching, session storage, environment management, resource/telemetry monitoring, error recovery, rate-limit detection, and logging. In diagram terms, this is the control plane that makes tool execution reliable and observable.

5. `mcp_tools/` is the main tool catalog. It is split into many focused subpackages by attack surface: web scanning, network scanning, cloud audit, container scan, binary analysis, credential harvest, SMB enum, DNS enum, database query, payload generation, and more. Most modules are thin adapters around external security tools and CLIs.

6. Many tools are organized in mirrored categories across `mcp_tools/` and `server_api/`, which suggests a clear separation between “tool capability definitions/wrappers” and “server-exposed endpoints.” That duplication is important for the diagram: the repo is not just a tool library, it is a service layer that publishes those tools to MCP clients.

7. The intelligence layer is split into `intelligence/` and `mcp_tools/ai_*`. `CVEIntelligenceManager` and `IntelligentDecisionEngine` handle vulnerability awareness and tool selection logic, while `ai_payload_generation` and related assistants support AI-driven payload and exploit reasoning. These modules likely sit above raw tool execution and influence what gets run next.

8. `workflows/` provides higher-level orchestration for whole tasks rather than single tools. There are explicit bug bounty and CTF flows, with target modeling, testing steps, challenge coordination, and workflow managers. In architecture terms, this is where multiple tool calls are chained into a guided process.

9. `shared/` and `tool_registry.py` define common domain objects and catalog metadata. Shared models like target profiles, attack steps, attack chains, and target types give the platform a structured way to pass context between intelligence, workflows, and tools.

10. The platform has a strong operational layer: `visual/` and `mcp_core/colored_formatter.py` handle human-readable output, while `server_core/performance_monitor.py`, `telemetry_collector.py`, `advanced_cache.py`, and recovery modules track and stabilize execution. `assets/`, requirements files, and the README’s token/host flags indicate a locally deployed service that can optionally be authenticated and bound to localhost or a wider interface.

11. External dependencies are a core part of the architecture, not an implementation detail. The repo is an orchestrator for many third-party security binaries and cloud tools, so the primary runtime flow is “MCP request → server orchestration → subprocess/tool invocation → structured results back to the client.”

12. If you draw the diagram, the clearest layers are: MCP client/UI, server API façade, server runtime/execution core, tool adapters, intelligence/workflows, and shared models. The most important flows are request routing, tool selection, subprocess execution, result aggregation, and feedback into the decision engine for the next action.

Main entry points: [`server_api/__init__.py`](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_api/__init__.py) (API façade), [`server_core/__init__.py`](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/__init__.py) (Runtime core), [`tool_registry.py`](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/tool_registry.py) (Registry), [`workflows/bugbounty/workflow.py`](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/workflows/bugbounty/workflow.py) (Bug bounty)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP Client"]
  node_hexstrike_mcp["MCP entry<br/>entrypoint<br/>[hexstrike_mcp.py]"]
  node_mcp_entry["MCP core<br/>client plumbing<br/>[mcp_entry.py]"]
  node_hexstrike_client["Client link<br/>http client"]
  node_server_setup["Server setup<br/>bootstrap<br/>[server_setup.py]"]
end

subgraph group_server["Server API"]
  node_server_api_root["API façade<br/>http surface<br/>[__init__.py]"]
end

subgraph group_core["Server Core"]
  node_server_core_root["Runtime core<br/>execution runtime<br/>[__init__.py]"]
  node_command_executor["Exec engine<br/>subprocess control"]
  node_process_manager["Process mgmt<br/>process control<br/>[process_manager.py]"]
  node_cache_store["Cache & state<br/>state store<br/>[advanced_cache.py]"]
  node_monitoring["Telemetry<br/>observability"]
  node_recovery["Recovery<br/>resilience"]
end

subgraph group_capabilities["Tool Capabilities"]
  node_web_tools["Web tools<br/>web security adapters<br/>[nikto.py]"]
  node_network_tools["Network tools<br/>network adapters<br/>[nmap.py]"]
  node_binary_tools["Binary tools<br/>binary analysis<br/>[ghidra.py]"]
  node_cloud_tools["Cloud tools<br/>cloud security<br/>[prowler.py]"]
  node_password_tools["Cracking tools<br/>credential attack<br/>[hashcat.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_intelligence_layer["Decision engine<br/>ai orchestration"]
  node_payload_ai["Payload AI<br/>ai assist"]
end

subgraph group_workflows["Workflows"]
  node_bugbounty_flow["Bug bounty<br/>workflow<br/>[workflow.py]"]
  node_ctf_flow["CTF flow<br/>workflow<br/>[workflowManager.py]"]
end

subgraph group_shared["Shared Models"]
  node_tool_registry["Registry<br/>catalog metadata<br/>[tool_registry.py]"]
  node_shared_models["Shared models<br/>domain models<br/>[attack_chain.py]"]
end

node_hexstrike_mcp -->|"launches"| node_mcp_entry
node_mcp_entry -->|"routes requests"| node_hexstrike_client
node_mcp_entry -->|"configures"| node_server_setup
node_hexstrike_client -->|"HTTP calls"| node_server_api_root
node_server_api_root -->|"delegates"| node_server_core_root
node_server_api_root -->|"exposes"| node_web_tools
node_server_api_root -->|"exposes"| node_network_tools
node_server_api_root -->|"exposes"| node_binary_tools
node_server_api_root -->|"exposes"| node_cloud_tools
node_server_api_root -->|"exposes"| node_password_tools
node_server_core_root -->|"runs"| node_command_executor
node_server_core_root -->|"controls"| node_process_manager
node_server_core_root -->|"stores state"| node_cache_store
node_server_core_root -->|"observes"| node_monitoring
node_server_core_root -->|"recovers"| node_recovery
node_tool_registry -->|"catalogs"| node_web_tools
node_tool_registry -->|"catalogs"| node_network_tools
node_tool_registry -->|"catalogs"| node_binary_tools
node_tool_registry -->|"catalogs"| node_cloud_tools
node_shared_models -->|"feeds context"| node_bugbounty_flow
node_shared_models -->|"feeds context"| node_ctf_flow
node_intelligence_layer -->|"selects tools"| node_tool_registry
node_intelligence_layer -->|"guides"| node_payload_ai
node_bugbounty_flow -->|"chains"| node_network_tools
node_bugbounty_flow -->|"chains"| node_web_tools
node_bugbounty_flow -->|"adapts"| node_intelligence_layer
node_ctf_flow -->|"chains"| node_binary_tools
node_ctf_flow -->|"chains"| node_password_tools

click node_hexstrike_mcp "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/hexstrike_mcp.py"
click node_mcp_entry "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/mcp_entry.py"
click node_hexstrike_client "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/hexstrike_client.py"
click node_server_setup "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/server_setup.py"
click node_server_api_root "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_api/__init__.py"
click node_server_core_root "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/__init__.py"
click node_command_executor "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/command_executor.py"
click node_process_manager "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/process_manager.py"
click node_cache_store "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/advanced_cache.py"
click node_monitoring "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/performance_monitor.py"
click node_recovery "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/failure_recovery_system.py"
click node_tool_registry "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/tool_registry.py"
click node_shared_models "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/shared/attack_chain.py"
click node_intelligence_layer "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/intelligence/intelligent_decision_engine.py"
click node_payload_ai "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/ai_payload/ai_payload_generation.py"
click node_web_tools "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/web_scan/nikto.py"
click node_network_tools "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/net_scan/nmap.py"
click node_binary_tools "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/binary_analysis/ghidra.py"
click node_cloud_tools "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/cloud_audit/prowler.py"
click node_password_tools "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/password_cracking/hashcat.py"
click node_bugbounty_flow "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/workflows/bugbounty/workflow.py"
click node_ctf_flow "https://github.com/vhater/hexstrike-ai-community-edition/blob/master/workflows/ctf/workflowManager.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_hexstrike_mcp,node_mcp_entry,node_hexstrike_client,node_server_setup,node_tool_registry,node_shared_models toneBlue
class node_server_api_root toneAmber
class node_server_core_root,node_command_executor,node_process_manager,node_cache_store,node_monitoring,node_recovery toneMint
class node_web_tools,node_network_tools,node_binary_tools,node_cloud_tools,node_password_tools toneRose
class node_intelligence_layer,node_payload_ai toneIndigo
class node_bugbounty_flow,node_ctf_flow toneTeal
```

## Components

### MCP Client

Local entrypoint, argument handling, and MCP plumbing.

- [MCP entry](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/hexstrike_mcp.py): entrypoint · User-facing MCP launcher for the local client side. · `hexstrike_mcp.py`
- [MCP core](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/mcp_entry.py): client plumbing · Argument parsing, server setup, and MCP client wiring. · `mcp_core/mcp_entry.py`
- [Client link](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/hexstrike_client.py): http client · Forwards MCP requests to the HTTP server. · `mcp_core/hexstrike_client.py`
- [Server setup](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_core/server_setup.py): bootstrap · Initializes server-side MCP exposure and startup wiring. · `mcp_core/server_setup.py`

### Server API

HTTP façade exposing security capabilities by domain.

- [API façade](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_api/__init__.py): http surface · Server-side domain façade that exposes security actions. · `server_api/__init__.py`

### Server Core

Execution runtime for processes, caching, sessions, telemetry, and recovery.

- [Runtime core](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/__init__.py): execution runtime · Platform runtime for execution, reliability, and observability. · `server_core/__init__.py`
- [Exec engine](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/command_executor.py): subprocess control · Runs external tools and commands. · `server_core/command_executor.py`
- [Process mgmt](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/process_manager.py): process control · Manages spawned processes and lifecycle. · `server_core/process_manager.py`
- [Cache & state](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/advanced_cache.py): state store · Caches results and stores session state. · `server_core/advanced_cache.py`
- [Telemetry](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/performance_monitor.py): observability · Performance, telemetry, and resource monitoring. · `server_core/performance_monitor.py`
- [Recovery](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/server_core/failure_recovery_system.py): resilience · Failure recovery and error handling. · `server_core/failure_recovery_system.py`

### Tool Capabilities

Tool adapters and domain wrappers used by the platform.

- [Web tools](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/web_scan/nikto.py): web security adapters · Web scanning, fuzzing, crawling, probing, and scanning adapters. · `mcp_tools/web_scan/nikto.py`
- [Network tools](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/net_scan/nmap.py): network adapters · Recon, DNS, port scanning, SMB enumeration, and lookup tools. · `mcp_tools/net_scan/nmap.py`
- [Binary tools](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/binary_analysis/ghidra.py): binary analysis · Binary analysis, debugging, gadget search, and memory forensics. · `mcp_tools/binary_analysis/ghidra.py`
- [Cloud tools](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/cloud_audit/prowler.py): cloud security · Cloud audit, exploit, visualization, and container/IaC scanning. · `mcp_tools/cloud_audit/prowler.py`
- [Cracking tools](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/password_cracking/hashcat.py): credential attack · Password auditing and cracking adapters. · `mcp_tools/password_cracking/hashcat.py`

### Intelligence

Decision-making and payload reasoning layers.

- [Decision engine](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/intelligence/intelligent_decision_engine.py): ai orchestration · Vulnerability awareness and tool selection logic. · `intelligence/intelligent_decision_engine.py`
- [Payload AI](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/mcp_tools/ai_payload/ai_payload_generation.py): ai assist · AI-assisted payload generation and exploit reasoning. · `mcp_tools/ai_payload/ai_payload_generation.py`

### Workflows

Multi-step orchestration for guided engagements.

- [Bug bounty](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/workflows/bugbounty/workflow.py): workflow · Guided recon and testing workflow for target-driven engagements. · `workflows/bugbounty/workflow.py`
- [CTF flow](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/workflows/ctf/workflowManager.py): workflow · Challenge coordination and automation for CTF tasks. · `workflows/ctf/workflowManager.py`

### Shared Models

Common domain objects and registry metadata.

- [Registry](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/tool_registry.py): catalog metadata · Maps tools and capabilities to catalog metadata. · `tool_registry.py`
- [Shared models](https://github.com/vhater/hexstrike-ai-community-edition/blob/master/shared/attack_chain.py): domain models · Targets, attack steps, chains, and target types. · `shared/attack_chain.py`

## Connections

- MCP entry → MCP core: launches · Starts the MCP client entrypoint.
- MCP core → Client link: routes requests · Client plumbing forwards tool calls to the server.
- MCP core → Server setup: configures · Initializes available tool profiles and server bindings.
- Client link → API façade: HTTP calls · Sends requests to the server API façade.
- API façade → Runtime core: delegates · Hands execution work to the runtime layer.
- API façade → Web tools: exposes · Publishes web-domain security operations.
- API façade → Network tools: exposes · Publishes network and recon operations.
- API façade → Binary tools: exposes · Publishes binary analysis and debugging operations.
- API façade → Cloud tools: exposes · Publishes cloud and container security operations.
- API façade → Cracking tools: exposes · Publishes password-cracking operations.
- Runtime core → Exec engine: runs · Executes external tools and subprocesses.
- Runtime core → Process mgmt: controls · Manages process lifecycle and pooling.
- Runtime core → Cache & state: stores state · Persists session and cached results.
- Runtime core → Telemetry: observes · Collects telemetry and performance data.
- Runtime core → Recovery: recovers · Handles failures and retries.
- Registry → Web tools: catalogs · Registers web capabilities in the tool catalog.
- Registry → Network tools: catalogs · Registers network capabilities in the tool catalog.
- Registry → Binary tools: catalogs · Registers binary capabilities in the tool catalog.
- Registry → Cloud tools: catalogs · Registers cloud capabilities in the tool catalog.
- Shared models → Bug bounty: feeds context · Provides target and attack-chain structures to workflows.
- Shared models → CTF flow: feeds context · Provides shared challenge and step models.
- Decision engine → Registry: selects tools · Uses catalog metadata to choose capabilities.
- Decision engine → Payload AI: guides · Influences payload and exploit reasoning.
- Bug bounty → Network tools: chains · Orchestrates recon and scanning steps.
- Bug bounty → Web tools: chains · Orchestrates web discovery and testing steps.
- Bug bounty → Decision engine: adapts · Feeds results back into decision making.
- CTF flow → Binary tools: chains · Uses binary tooling for challenge solving.
- CTF flow → Cracking tools: chains · Uses cracking tools when needed.
