How vhater/hexstrike-ai-community-edition works
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 API façade · server_core/__init__.py Runtime core · tool_registry.py Registry · workflow.py Bug bounty
Components 22
MCP Client
Local entrypoint, argument handling, and MCP plumbing.
- MCP entry · User-facing MCP launcher for the local client side.
hexstrike_mcp.py - MCP core · Argument parsing, server setup, and MCP client wiring.
mcp_core/mcp_entry.py - Client link · Forwards MCP requests to the HTTP server.
mcp_core/hexstrike_client.py - Server setup · 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 · 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 · Platform runtime for execution, reliability, and observability.
server_core/__init__.py - Exec engine · Runs external tools and commands.
server_core/command_executor.py - Process mgmt · Manages spawned processes and lifecycle.
server_core/process_manager.py - Cache & state · Caches results and stores session state.
server_core/advanced_cache.py - Telemetry · Performance, telemetry, and resource monitoring.
server_core/performance_monitor.py - Recovery · Failure recovery and error handling.
server_core/failure_recovery_system.py
Tool Capabilities
Tool adapters and domain wrappers used by the platform.
- Web tools · Web scanning, fuzzing, crawling, probing, and scanning adapters.
mcp_tools/web_scan/nikto.py - Network tools · Recon, DNS, port scanning, SMB enumeration, and lookup tools.
mcp_tools/net_scan/nmap.py - Binary tools · Binary analysis, debugging, gadget search, and memory forensics.
mcp_tools/binary_analysis/ghidra.py - Cloud tools · Cloud audit, exploit, visualization, and container/IaC scanning.
mcp_tools/cloud_audit/prowler.py - Cracking tools · Password auditing and cracking adapters.
mcp_tools/password_cracking/hashcat.py
Intelligence
Decision-making and payload reasoning layers.
- Decision engine · Vulnerability awareness and tool selection logic.
intelligence/intelligent_decision_engine.py - Payload AI · AI-assisted payload generation and exploit reasoning.
mcp_tools/ai_payload/ai_payload_generation.py
Workflows
Multi-step orchestration for guided engagements.
- Bug bounty · Guided recon and testing workflow for target-driven engagements.
workflows/bugbounty/workflow.py - CTF flow · Challenge coordination and automation for CTF tasks.
workflows/ctf/workflowManager.py
Shared Models
Common domain objects and registry metadata.
- Registry · Maps tools and capabilities to catalog metadata.
tool_registry.py - Shared models · Targets, attack steps, chains, and target types.
shared/attack_chain.py
Connections 28
- 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.