### Install Hexstrike AI

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/README.md

Clone the repository, set up a virtual environment, and install dependencies.

```bash
git clone https://github.com/0x4m4/hexstrike-ai.git
cd hexstrike-ai
python3 -m venv hexstrike-env
source hexstrike-env/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Clone Repository and Setup Virtual Environment

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Clones the HexStrike AI repository and sets up a Python virtual environment for managing dependencies. Activate the environment before installing packages.

```bash
# 1. Clone the repository
git clone https://github.com/0x4m4/hexstrike-ai.git
cd hexstrike-ai

# 2. Create virtual environment
python3 -m venv hexstrike-env
source hexstrike-env/bin/activate  # Linux/Mac
# hexstrike-env\Scripts\activate   # Windows
```

--------------------------------

### Start Hexstrike AI Server

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/README.md

Run the main server script to start the Hexstrike AI backend.

```bash
python3 hexstrike_server.py
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Installs all necessary Python packages for development from the 'requirements.txt' file. Ensure the virtual environment is activated.

```bash
# 3. Install development dependencies
pip install -r requirements.txt
```

--------------------------------

### Install Missing Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

If security tools are not found, this comment suggests installing them from their official sources. Specific installation commands depend on the tool and operating system.

```bash
# Install missing tools from their official sources
```

--------------------------------

### Generic MCP Client Setup

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Initialize a HexStrikeClient and set up an MCP server for generic MCP-compatible clients. This code demonstrates basic client and server setup.

```python
from hexstrike_mcp import HexStrikeClient, setup_mcp_server

client = HexStrikeClient(server_url="http://localhost:8888")
mcp_server = setup_mcp_server(client)

# Server runs on stdio and accepts MCP requests
```

--------------------------------

### Install Core Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Installs essential network, web application, password, and binary analysis security tools. Ensure you have the necessary package manager (e.g., apt, yum) configured.

```bash
# Network & Reconnaissance
nmap masscan rustscan amass subfinder nuclei fierce dnsenum
autorecon theharvester responder netexec enum4linux-ng

# Web Application Security
gobuster feroxbuster dirsearch ffuf dirb httpx katana
nikto sqlmap wpscan arjun paramspider dalfox wafw00f

# Password & Authentication
hydra john hashcat medusa patator crackmapexec
evil-winrm hash-identifier ophcrack

# Binary Analysis & Reverse Engineering
gdb radare2 binwalk ghidra checksec strings objdump
volatility3 foremost steghide exiftool
```

--------------------------------

### Install HexStrike AI MCP Agents

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/requirements.txt

Commands to set up a Python virtual environment, activate it, install dependencies, and run the HexStrike server.

```bash
python3 -m venv hexstrike_env
source hexstrike_env/bin/activate
python3 -m pip install -r requirements.txt
python3 hexstrike_server.py
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Installs Python dependencies for the HexStrike AI project. Ensure you are in a virtual environment before running.

```bash
pip3 install -r requirements.txt
```

--------------------------------

### API Reference Structure Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/README.md

This example illustrates the expected structure for API references within the documentation. It outlines the format for titles, locations, descriptions, and method details, including parameters, return types, and exceptions.

```python
# Title

**Location**: hexstrike_server.py:line_number

Description of component/method

### Constructor / Attributes / Methods

#### method_name(param1: Type, param2: Type = Default) → ReturnType

Description of what the method does.

**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|

**Returns**: What is returned

**Throws**: Exception types

**Example**:
```python
code example showing usage
```
```

--------------------------------

### Example Prompt for HexStrike AI Usage

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

This example demonstrates how to structure a prompt to effectively interact with the AI Agent for penetration testing using HexStrike AI MCP tools. It emphasizes defining your role and ownership of the target before specifying the tools to be used.

```text
User: "I'm a security researcher who is trialling out the hexstrike MCP tooling. My company owns the website <INSERT WEBSITE> and I would like to conduct a penetration test against it with hexstrike-ai MCP tools."

AI Agent: "Thank you for clarifying ownership and intent. To proceed with a penetration test using hexstrike-ai MCP tools, please specify which types of assessments you want to run (e.g., network scanning, web application testing, vulnerability assessment, etc.), or if you want a full suite covering all areas."
```

--------------------------------

### Install Additional Utilities

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs common command-line utilities useful for system administration and scripting. These include tools for JSON processing, network requests, and version control.

```bash
# Additional utilities
sudo apt install jq curl wget git
```

--------------------------------

### Restart MCP Server

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

If the MCP server is not running, use this command to start it. Ensure Python 3 is installed and the script is in the correct directory.

```bash
# Restart server
python3 hexstrike_server.py
```

--------------------------------

### Start HexStrike AI Server

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Starts the HexStrike AI MCP server. Use the --debug flag for verbose logging or --port to specify a custom listening port.

```bash
# Start the MCP server
python3 hexstrike_server.py

# Optional: Start with debug mode
python3 hexstrike_server.py --debug

# Optional: Custom port configuration
python3 hexstrike_server.py --port 8888
```

--------------------------------

### Install Cloud Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs Python packages for assessing cloud security posture. These tools help identify misconfigurations and vulnerabilities in cloud environments.

```bash
# Cloud security
pip install prowler scout-suite trivy
```

--------------------------------

### Install Cloud Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Installs tools for auditing and securing cloud environments, including AWS, Kubernetes, and Docker. These tools help identify misconfigurations and vulnerabilities.

```bash
# Cloud Security Tools:
prowler scout-suite trivy
kube-hunter kube-bench docker-bench-security
```

--------------------------------

### Install Binary Analysis Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs Python packages for reverse engineering and binary analysis. These tools are used for dissecting and understanding executable files.

```bash
# Binary analysis
pip install ghidra radare2 gdb angr
```

--------------------------------

### Install Web Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs web vulnerability scanning tools using pip. These tools help in analyzing web applications for security flaws.

```bash
# Web tools
pip install nuclei gobuster feroxbuster ffuf
```

--------------------------------

### Troubleshoot 'Tool Not Found' Error

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Commands to install a missing tool or verify its presence and accessibility in the system's PATH.

```bash
# Install missing tool
sudo apt install nmap
```

```bash
# Or check PATH
which nmap
```

--------------------------------

### Install Network Security Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs essential network scanning tools like nmap, masscan, and rustscan using the system's package manager. These are required for network-related functionalities.

```bash
# Network tools
sudo apt install nmap masscan rustscan
```

--------------------------------

### AdvancedCache Usage Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Demonstrates setting a value, retrieving it, and checking cache statistics. Ensure AdvancedCache is imported and initialized before use.

```python
cache = AdvancedCache(max_size=500)
cache.set("nmap_results", scan_data)
result = cache.get("nmap_results")
stats = cache.get_stats()
print(f"Hit rate: {stats['hit_rate']}")
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Installs all required Python packages for Hexstrike AI using the pip package manager. This command reads the dependencies listed in the 'requirements.txt' file.

```bash
# 3. Install Python dependencies
pip install -r requirements.txt
```

--------------------------------

### Permission Denied - No Recovery Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/05-error-handling.md

Shows how permission denied errors are handled by classifying them and selecting a 'SKIP_TOOL' recovery action, leading to the tool being removed from the attack chain.

```python
# Permission denied cannot be auto-recovered
executor.execute_command("nmap -sV example.com")
# → Requires elevated privileges but running as non-root

# IntelligentErrorHandler:
# 1. Classifies as ErrorType.PERMISSION_DENIED
# 2. Selects RecoveryAction.SKIP_TOOL
# 3. Removes tool from attack chain
# 4. Returns to orchestrator with skip notification

{
    "error_type": "PERMISSION_DENIED",
    "recovered": false,
    "recovery_action": "SKIP_TOOL",
    "message": "Tool nmap requires elevated privileges. Skipping.",
    "alternative_tools": ["rustscan", "masscan"]
}
```

--------------------------------

### Install Chrome for Browser Agent

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Installs Google Chrome and its corresponding ChromeDriver for browser automation. This is required for the browser agent functionality.

```bash
# Chrome/Chromium for Browser Agent
sudo apt install chromium-browser chromium-chromedriver
# OR install Google Chrome
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install google-chrome-stable
```

--------------------------------

### Start HexStrike Development Server

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Launches the HexStrike development server, specifying the port and enabling debug mode. This is used for local development and testing.

```bash
# 4. Start development server
python3 hexstrike_server.py --port 8888 --debug
```

--------------------------------

### Setup FastMCP Server for AI Agent Communication

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Initializes the MCP server using FastMCP to enable AI agent communication. Requires an initialized HexStrikeClient.

```python
def setup_mcp_server(hexstrike_client: HexStrikeClient) -> FastMCP
```

```python
from hexstrike_mcp import HexStrikeClient, setup_mcp_server

client = HexStrikeClient(server_url="http://localhost:8888")
mcp_server = setup_mcp_server(client)

# Server now listening on stdio for MCP protocol
```

--------------------------------

### Load Hexstrike Configuration

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

This command-line argument is used to specify the configuration file when starting the Hexstrike server. Ensure the path to your configuration file is correct.

```bash
python3 hexstrike_server.py --config hexstrike_config.json
```

--------------------------------

### Start Hexstrike AI MCP Client

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/README.md

Launch the MCP client in a separate terminal to interact with the server.

```bash
python3 hexstrike_mcp.py
```

--------------------------------

### Using HexStrikeClient (Python)

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Examples of using the Python HexStrikeClient to interact with the Hexstrike AI API.

```APIDOC
```python
from hexstrike_mcp import HexStrikeClient

# Initialize client
client = HexStrikeClient(server_url="http://localhost:8888", timeout=300)

# Execute command
result = client.execute_command("nmap -sV example.com")
print(result["stdout"])

# Analyze target
profile = client.analyze_target("example.com")
print(f"Attack Surface: {profile['attack_surface_score']}")

# Select tools
tools = client.select_tools(profile)
for tool in tools["recommended_tools"]:
    print(f"{tool['tool']}: {tool['effectiveness']}")

# Create attack chain
chain = client.create_attack_chain(profile)
print(f"Success probability: {chain['success_probability']:.2%}")
```
```

--------------------------------

### Run Docker Compose

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Command to start the Hexstrike AI service defined in the docker-compose.yml file in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### EnhancedProcessManager Execute Command Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Shows how to execute a system command using EnhancedProcessManager, with options for timeout and caching. Catches subprocess timeouts and process errors.

```python
manager = EnhancedProcessManager()
result = manager.execute_command("nmap -sV example.com", timeout=600)
print(result["stdout"]) 
```

--------------------------------

### Prompt Example for HexStrike Tools in Claude

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

This prompt demonstrates how to instruct Claude to use HexStrike tools for penetration testing. It outlines a sequence of actions from target analysis to comprehensive scanning.

```text
I'm a security researcher testing my company's infrastructure. 
I'd like to use HexStrike tools to perform penetration testing on 
example.com. Please:

1. Analyze the target to understand its technology stack
2. Select optimal tools for vulnerability discovery
3. Create an attack chain
4. Execute a comprehensive scan
```

--------------------------------

### POST /api/command Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response after executing a command. Includes command output, return code, and caching status.

```json
{
  "status": "success",
  "stdout": "Starting Nmap...",
  "stderr": "",
  "return_code": 0,
  "duration_ms": 12500,
  "cached": false,
  "timestamp": "2025-02-20T10:30:00Z"
}
```

--------------------------------

### Python Client: Analyze Target

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Shows how to analyze a target domain using the HexStrikeClient to get an attack surface score.

```python
# Analyze target
profile = client.analyze_target("example.com")
print(f"Attack Surface: {profile['attack_surface_score']}")
```

--------------------------------

### Get Tool Recommendations for Target Analysis

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Recommends tools for a target based on its analysis profile. Accepts analysis options for tool selection.

```python
def select_tools(target_profile: Dict[str, Any], **options) -> Dict[str, Any]
```

--------------------------------

### Chain Tool Outputs with Python

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Execute a sequence of tools by chaining their outputs, starting with target analysis and progressing through tool selection and attack chain creation.

```python
# Tool 1: Analyze target
target_profile = await analyze_target("example.com")

# Tool 2: Use profile for optimization
tools = await select_optimal_tools(target_profile)

# Tool 3: Use tools for attack chain
chain = await create_attack_chain(target_profile)

# Tool 4: Execute chain
for step in chain["steps"]:
    result = await globals()[step["tool"]](
        target="example.com",
        **step["parameters"]
    )
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

This command creates an isolated Python environment for the project. Activate it before installing dependencies to ensure they are managed within this environment. The activation command differs for Linux/Mac and Windows.

```bash
# 2. Create virtual environment
python3 -m venv hexstrike-env
source hexstrike-env/bin/activate  # Linux/Mac
# hexstrike-env\Scripts\activate   # Windows
```

--------------------------------

### Timeout Recovery Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/05-error-handling.md

Demonstrates automatic recovery from a timeout error by classifying the error, selecting a backoff strategy, adapting parameters like timeout and scope, and retrying the command.

```python
# Initial execution fails with timeout
executor.execute_command("nmap -sV -p- 192.168.1.1", timeout=300)
# → subprocess.TimeoutExpired

# IntelligentErrorHandler automatically:
# 1. Classifies as ErrorType.TIMEOUT
# 2. Selects RecoveryAction.RETRY_WITH_BACKOFF
# 3. Adapts parameters:
#    - Increases timeout to 450 seconds
#    - Reduces port range
#    - Decreases thread count
# 4. Retries command
# 5. On success, returns result with recovery_info

# Result:
{
    "status": "success",
    "recovered": true,
    "original_error": "TimeoutExpired",
    "recovery_action": "RETRY_WITH_BACKOFF",
    "attempt": 2,
    "adapted_params": {
        "timeout": 450,
        "ports": "1-10000",  # Reduced from full range
        "rate": "slow"       # Reduced from default
    }
}
```

--------------------------------

### POST /api/command Request Body

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example request body for executing a command. Includes command string, timeout, and caching options.

```json
{
  "command": "nmap -sV example.com",
  "timeout": 300,
  "use_cache": true,
  "tool_name": "nmap",
  "parameters": {
    "target": "example.com",
    "scan_type": "-sV"
  }
}
```

--------------------------------

### Check Security Tool Availability

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Verify if essential security tools like nmap, gobuster, and nuclei are installed and accessible in your system's PATH.

```bash
# Check tool availability
which nmap gobuster nuclei
```

--------------------------------

### GET /api/telemetry Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response for the system performance metrics endpoint. Provides CPU, memory, and process usage.

```json
{
  "timestamp": "2025-02-20T10:30:00Z",
  "cpu_percent": 25.5,
  "memory_percent": 45.2,
  "processes_active": 3,
  "cache_hit_rate": 0.85,
  "avg_execution_time_ms": 2500,
  "total_commands_executed": 1250,
  "error_rate": 0.02
}
```

--------------------------------

### Rate Limiting Recovery Example

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/05-error-handling.md

Illustrates automatic recovery from rate limiting (HTTP 429) by classifying the error, using the 'Retry-After' header, and applying exponential backoff for retries.

```python
# HTTP 429 response detected
response = requests.get("https://example.com/api/search", ...)
# → response.status_code == 429

# IntelligentErrorHandler:
# 1. Classifies as ErrorType.RATE_LIMITED
# 2. Extracts Retry-After header (60 seconds)
# 3. Applies exponential backoff
# 4. Delays and retries

# Delays applied:
# Attempt 1: Wait 60 seconds (from Retry-After) → retry
# Attempt 2: Wait 90 seconds (exponential) → retry
# Attempt 3: Wait 135 seconds (exponential) → retry

{
    "error_type": "RATE_LIMITED",
    "recovered": true,
    "retry_strategy": "exponential_backoff",
    "attempts": 3,
    "total_delay_seconds": 285,
    "final_result": {...}
}
```

--------------------------------

### GET /health Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response for the server health check endpoint. Indicates server status and tool availability.

```json
{
  "status": "healthy",
  "timestamp": "2025-02-20T10:30:00Z",
  "tools_available": {
    "nmap": true,
    "gobuster": true,
    "nuclei": true,
    "...": false
  },
  "uptime_seconds": 3600,
  "cache_status": {
    "size": 150,
    "hits": 450,
    "misses": 80
  }
}
```

--------------------------------

### Python Client: Select Tools

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Illustrates selecting recommended tools for a target based on the analysis profile. It iterates and prints tool names and their effectiveness.

```python
# Select tools
tools = client.select_tools(profile)
for tool in tools["recommended_tools"]:
    print(f"{tool['tool']}: {tool['effectiveness']}")
```

--------------------------------

### GET /api/cache/stats Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response for the cache performance statistics endpoint. Details cache size, hits, misses, and hit rate.

```json
{
  "total_entries": 150,
  "max_size": 1000,
  "hits": 450,
  "misses": 80,
  "hit_rate": 0.849,
  "avg_entry_size_bytes": 2500,
  "total_size_bytes": 375000,
  "ttl_seconds": 3600
}
```

--------------------------------

### setup_mcp_server

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Initializes the MCP (Model Context Protocol) server with FastMCP to enable AI agent communication. It takes an initialized HexStrikeClient and returns a configured FastMCP server instance.

```APIDOC
## setup_mcp_server

### Description
Initializes the MCP server with FastMCP to enable AI agent communication.

### Parameters
#### Path Parameters
- **hexstrike_client** (HexStrikeClient) - Required - Initialized client for server communication

### Returns
FastMCP server instance with all tools registered

### Example
```python
from hexstrike_mcp import HexStrikeClient, setup_mcp_server

client = HexStrikeClient(server_url="http://localhost:8888")
mcp_server = setup_mcp_server(client)

# Server now listening on stdio for MCP protocol
```
```

--------------------------------

### Create Python Development Environment

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

Sets up a virtual environment named 'hexstrike-dev' for development. This isolates project dependencies. Activate it using the 'source' command.

```bash
# 2. Create development environment
python3 -m venv hexstrike-dev
source hexstrike-dev/bin/activate
```

--------------------------------

### Run HexStrike Server with Command-Line Options

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Launch the HexStrike server using command-line arguments to override default settings. Options include custom ports, debug mode, and disabling cache.

```bash
python3 hexstrike_server.py [OPTIONS]
```

```bash
# Run on custom port
python3 hexstrike_server.py --port 9000

# Enable debug mode with verbose output
python3 hexstrike_server.py --debug

# Disable caching for fresh results
python3 hexstrike_server.py --no-cache

# Custom configuration file
python3 hexstrike_server.py --config custom_config.json
```

--------------------------------

### Python Client: Create Attack Chain

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Demonstrates creating an attack chain for a given profile and printing its success probability.

```python
# Create attack chain
chain = client.create_attack_chain(profile)
print(f"Success probability: {chain['success_probability']:.2%}")
```

--------------------------------

### GET /api/cache/stats

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Fetches detailed statistics about the cache performance.

```APIDOC
## GET /api/cache/stats

### Description
Cache performance statistics.

### Method
GET

### Endpoint
/api/cache/stats

### Response
#### Success Response (200)
- **total_entries** (integer) - The total number of entries in the cache.
- **max_size** (integer) - The maximum allowed size of the cache.
- **hits** (integer) - The number of cache hits.
- **misses** (integer) - The number of cache misses.
- **hit_rate** (number) - The cache hit rate.
- **avg_entry_size_bytes** (integer) - The average size of cache entries in bytes.
- **total_size_bytes** (integer) - The total size of the cache in bytes.
- **ttl_seconds** (integer) - The time-to-live for cache entries in seconds.

#### Response Example
```json
{
  "total_entries": 150,
  "max_size": 1000,
  "hits": 450,
  "misses": 80,
  "hit_rate": 0.849,
  "avg_entry_size_bytes": 2500,
  "total_size_bytes": 375000,
  "ttl_seconds": 3600
}
```
```

--------------------------------

### Python Client: Execute Command

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Demonstrates executing a command using the HexStrikeClient. The standard output of the command is printed.

```python
from hexstrike_mcp import HexStrikeClient

# Initialize client
client = HexStrikeClient(server_url="http://localhost:8888", timeout=300)

# Execute command
result = client.execute_command("nmap -sV example.com")
print(result["stdout"])
```

--------------------------------

### IntelligentErrorHandler Constructor

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Initializes the IntelligentErrorHandler. No parameters are required for basic setup.

```python
class IntelligentErrorHandler:
    def __init__(self) -> None:
```

--------------------------------

### GET /api/telemetry

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Retrieves system performance metrics and usage statistics.

```APIDOC
## GET /api/telemetry

### Description
System performance metrics and usage statistics.

### Method
GET

### Endpoint
/api/telemetry

### Response
#### Success Response (200)
- **timestamp** (string) - The timestamp of the telemetry data.
- **cpu_percent** (number) - The current CPU utilization percentage.
- **memory_percent** (number) - The current memory utilization percentage.
- **processes_active** (integer) - The number of active processes.
- **cache_hit_rate** (number) - The rate of cache hits.
- **avg_execution_time_ms** (integer) - The average command execution time in milliseconds.
- **total_commands_executed** (integer) - The total number of commands executed.
- **error_rate** (number) - The rate of errors encountered.

#### Response Example
```json
{
  "timestamp": "2025-02-20T10:30:00Z",
  "cpu_percent": 25.5,
  "memory_percent": 45.2,
  "processes_active": 3,
  "cache_hit_rate": 0.85,
  "avg_execution_time_ms": 2500,
  "total_commands_executed": 1250,
  "error_rate": 0.02
}
```
```

--------------------------------

### Directory and File Enumeration with Gobuster

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Configure Gobuster for directory and file enumeration on a target URL. Specify the wordlist, extensions to search for, and the number of threads.

```json
{
  "target": "https://example.com",
  "mode": "dir",
  "wordlist": "/usr/share/wordlists/common.txt",
  "extensions": "php,html,js,txt",
  "threads": 50,
  "timeout_seconds": 300
}
```

--------------------------------

### Get Process Status

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Retrieves detailed information about a specific process identified by its PID.

```APIDOC
## GET /api/processes/status/{pid}

### Description
Get detailed information about specific process.

### Method
GET

### Endpoint
/api/processes/status/{pid}

### Parameters
#### Path Parameters
- **pid** (integer) - Required - The process ID.

### Response
#### Success Response (200)
- **pid** (integer) - The process ID.
- **command** (string) - The command used to start the process.
- **status** (string) - The current status of the process (e.g., 'running').
- **cpu_percent** (number) - The percentage of CPU usage.
- **memory_mb** (number) - The amount of memory used in megabytes.
- **memory_percent** (number) - The percentage of memory usage.
- **elapsed_seconds** (integer) - The time in seconds the process has been running.
- **estimated_remaining_seconds** (integer) - Estimated time in seconds remaining for the process.
- **tool_name** (string) - The name of the tool associated with the process.
- **start_time** (string) - The timestamp when the process started.
- **progress** (object) - An object containing progress details, including `current_stage` (string) and `completion_percent` (integer).

#### Response Example
```json
{
  "pid": 1234,
  "command": "nmap -sV example.com",
  "status": "running",
  "cpu_percent": 25.5,
  "memory_mb": 150.2,
  "memory_percent": 15.2,
  "elapsed_seconds": 45,
  "estimated_remaining_seconds": 120,
  "tool_name": "nmap",
  "start_time": "2025-02-20T10:25:00Z",
  "progress": {
    "current_stage": "service_detection",
    "completion_percent": 35
  }
}
```
```

--------------------------------

### GET /health

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Checks the server's health status and the availability of integrated tools.

```APIDOC
## GET /health

### Description
Server health check with tool availability status.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.
- **timestamp** (string) - The timestamp of the health check.
- **tools_available** (object) - An object indicating the availability of various tools.
- **uptime_seconds** (integer) - The server's uptime in seconds.
- **cache_status** (object) - Statistics about the cache performance.

#### Response Example
```json
{
  "status": "healthy",
  "timestamp": "2025-02-20T10:30:00Z",
  "tools_available": {
    "nmap": true,
    "gobuster": true,
    "nuclei": true,
    "...": false
  },
  "uptime_seconds": 3600,
  "cache_status": {
    "size": 150,
    "hits": 450,
    "misses": 80
  }
}
```
```

--------------------------------

### Register Create File Tool

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Registers the create_file tool for creating new files. Requires a filepath, content, and optional arguments.

```python
@mcp_server.tool()
async def create_file(filepath: str, content: str, **kwargs) -> Dict[str, Any]
```

--------------------------------

### GET /api/files/list

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Lists files within a specified directory, with options for filtering and recursive listing.

```APIDOC
## GET /api/files/list

### Description
List files in directory.

### Method
GET

### Endpoint
/api/files/list

### Parameters
#### Query Parameters
- **path** (string) - Optional - Directory path
- **pattern** (string) - Optional - Glob pattern filter
- **recursive** (boolean) - Optional - Recursive listing

### Response
#### Success Response (200)
- **directory** (string) - The path of the listed directory
- **files** (array) - An array of file objects
  - **name** (string) - Name of the file
  - **path** (string) - Full path to the file
  - **size** (integer) - Size of the file in bytes
  - **modified** (string) - Last modified timestamp
  - **is_directory** (boolean) - Indicates if the item is a directory

#### Response Example
```json
{
  "directory": "/tmp",
  "files": [
    {
      "name": "exploit.py",
      "path": "/tmp/exploit.py",
      "size": 256,
      "modified": "2025-02-20T10:30:00Z",
      "is_directory": false
    }
  ]
}
```
```

--------------------------------

### Proxy & Testing Dependencies

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/requirements.txt

Python package for setting up and managing HTTP proxies, used for testing and traffic interception.

```text
mitmproxy>=9.0.0,<11.0.0        # HTTP proxy (mitmproxy imports)
```

--------------------------------

### POST /api/cache/clear Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response after clearing the cache. Confirms the operation and reports cleared entries.

```json
{
  "status": "success",
  "cleared_entries": 150,
  "timestamp": "2025-02-20T10:30:00Z"
}
```

--------------------------------

### Register Get Cache Stats Tool

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/06-mcp-tools-integration.md

Registers the get_cache_stats tool to retrieve performance metrics for the cache.

```python
@mcp_server.tool()
async def get_cache_stats() -> Dict[str, Any]
```

--------------------------------

### Recommended: Using execute_command_with_recovery()

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/05-error-handling.md

This is the recommended approach for automatic error handling. It simplifies the process by managing error classification, recovery attempts, and parameter adaptation.

```python
# Recommended approach - automatic error handling
from hexstrike_server import execute_command_with_recovery

result = execute_command_with_recovery(
    tool_name="nmap",
    command="nmap -sV example.com",
    parameters={"target": "example.com", "timeout": 300}
)

# Result already includes:
# - Automatic error classification
# - Recovery attempts
# - Adapted parameters if retry occurred
# - Final success/failure status
```

--------------------------------

### Get Cache Statistics via API

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Retrieve statistics about the current cache status using this API endpoint.

```bash
# Get cache statistics
curl http://localhost:8888/api/cache/stats
```

--------------------------------

### Get Process Status via API

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Check the status of a specific process by providing its ID to this API endpoint.

```bash
# Get process status
curl http://localhost:8888/api/processes/status/1234
```

--------------------------------

### Initialize IntelligentDecisionEngine

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Instantiate the AI-powered decision engine for attack planning. This engine is used for tool selection and parameter optimization.

```python
from hexstrike_server import IntelligentDecisionEngine

engine = IntelligentDecisionEngine()
target_profile = engine.analyze_target("example.com")
tools = engine.select_optimal_tools(target_profile)
```

--------------------------------

### Select Optimal Tools with IntelligentDecisionEngine

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Select the most suitable security tools and their configurations based on the analyzed target profile. This method returns a dictionary containing recommended tools and their priority.

```python
tools = engine.select_optimal_tools(profile)
# Returns: {"tools": [...], "priority_order": [...], "recommendations": [...]}
```

--------------------------------

### Bug Bounty Reconnaissance Workflow Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response for a completed reconnaissance workflow, including discovered assets and duration.

```json
{
  "workflow_id": "bb_recon_123456",
  "status": "completed",
  "target": "example.com",
  "findings": {
    "subdomains": [...],
    "endpoints": [...],
    "technology_stack": {...},
    "service_information": {...}
  },
  "total_discovered_assets": 1250,
  "duration_seconds": 600
}
```

--------------------------------

### Example Usage of TargetType Enum

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/04-types-and-enums.md

Demonstrates how to check a target's type against the TargetType enum to select appropriate tools.

```python
if profile.target_type == TargetType.WEB_APPLICATION:
    tools = engine.tool_effectiveness[TargetType.WEB_APPLICATION.value]
```

--------------------------------

### Clone HexStrike AI Repository

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/README.md

This command clones the HexStrike AI repository from GitHub. Ensure Git is installed and configured on your system.

```bash
# 1. Fork and clone the repository
git clone https://github.com/0x4m4/hexstrike-ai.git
cd hexstrike-ai
```

--------------------------------

### Resolve 'Address already in use' Error

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/07-configuration-and-deployment.md

Commands to kill a process using a specific port or start the server on a different port.

```bash
# Kill process using port 8888
lsof -ti:8888 | xargs kill -9
```

```bash
# Or use different port
python3 hexstrike_server.py --port 9000
```

--------------------------------

### Access Live Process Dashboard via API

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/08-api-usage-examples.md

Connect to the live dashboard for real-time process monitoring through this API endpoint.

```bash
# Live dashboard
curl http://localhost:8888/api/processes/dashboard
```

--------------------------------

### Tool Execution Pipeline Visualization

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/01-architecture-overview.md

This diagram illustrates the sequence of operations involved in executing a tool request within the Hexstrike AI system. It shows the flow from the initial tool request through parameter optimization, command construction, cache checks, process execution, error handling, and finally to result formatting and response.

```text
Tool Request
    ↓
Parameter Optimization (IntelligentDecisionEngine)
    ↓
Command Construction
    ↓
Cache Check (AdvancedCache)
    ↓
Process Execution (ProcessPool)
    ↓
Error Handling (IntelligentErrorHandler)
    ↓
Result Formatting & Caching
    ↓
JSON Response
```

--------------------------------

### Get CVE Exploits

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

Retrieves a list of known public exploits for a given CVE identifier. Returns exploit details and links.

```python
def get_exploits(cve_id: str) -> List[Dict[str, Any]]
```

--------------------------------

### AdvancedCache

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/02-core-classes-api.md

LRU cache with intelligent eviction and TTL support. Provides methods to get, set, clear, and retrieve statistics for cached items.

```APIDOC
## AdvancedCache

### Constructor

```python
AdvancedCache(max_size: int = 1000, ttl_seconds: int = 3600)
```

**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| max_size | int | No | 1000 | Maximum cache entries |
| ttl_seconds | int | No | 3600 | Time-to-live for cached items |

### Methods

#### get(key: str) 

Retrieve cached value.

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| key | str | Yes | Cache key |

**Returns**: Cached value or None if not found/expired

#### set(key: str, value: Any, ttl: Optional[int] = None)

Store value in cache.

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| key | str | Yes | Cache key |
| value | Any | Yes | Value to cache |
| ttl | Optional[int] | No | Override default TTL |

#### clear()

Clear entire cache.

#### get_stats()

Get cache performance statistics.

**Returns**: Dictionary with hits, misses, size, etc.
```

--------------------------------

### ToolRecommendation Structure Definition

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/04-types-and-enums.md

Defines the structure for intelligent tool recommendations, including tool name, priority, effectiveness, parameters, reasoning, estimated duration, prerequisites, and output dependencies.

```python
ToolRecommendation = {
    "tool": str,                         # Tool name
    "priority": int,                     # Execution priority (1 = highest)
    "effectiveness": float,              # 0-1 effectiveness score
    "parameters": Dict[str, Any],        # Optimized parameters
    "reasoning": str,                    # Why this tool was selected
    "estimated_duration_seconds": int,   # Time estimate
    "prerequisites": List[str],          # Required prior tools
    "outputs_for": List[str]             # Tools that use this output
}
```

--------------------------------

### Intelligent Tool Selection Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Response containing recommended tools, their priority, effectiveness, and suggested parameters based on the target profile.

```json
{
  "recommended_tools": [
    {
      "tool": "nuclei",
      "priority": 1,
      "effectiveness": 0.95,
      "parameters": {
        "severity": "critical,high",
        "tags": "wordpress,sqli,rce"
      }
    }
  ],
  "explanation": "Selected tools based on target profile...",
  "total_estimated_time_seconds": 1200
}
```

--------------------------------

### Payload Generation Response

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Example response structure for a generated exploitation payload. Includes the payload itself, type, encoding status, execution method, and a description.

```json
{
  "payload": "python -c 'import socket;...",
  "payload_type": "reverse_shell",
  "encoded": true,
  "execution_method": "python -c",
  "description": "Python reverse shell payload"
}
```

--------------------------------

### POST /api/files/create

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Creates a new file with the specified content. Optionally overwrites an existing file.

```APIDOC
## POST /api/files/create

### Description
Create new file with content.

### Method
POST

### Endpoint
/api/files/create

### Parameters
#### Request Body
- **filepath** (string) - Required - Full file path
- **content** (string) - Required - File content
- **overwrite** (boolean) - Optional - Overwrite existing file (default: false)

### Request Example
```json
{
  "filepath": "/tmp/exploit.py",
  "content": "#!/usr/bin/env python3\nimport socket",
  "overwrite": false
}
```

### Response
#### Success Response (200)
- **status** (string) - Status of the operation
- **filepath** (string) - The path of the created file
- **size_bytes** (integer) - Size of the created file in bytes
- **created** (boolean) - Indicates if the file was created

#### Response Example
```json
{
  "status": "success",
  "filepath": "/tmp/exploit.py",
  "size_bytes": 256,
  "created": true
}
```
```

--------------------------------

### Bug Bounty OSINT Workflow Request

Source: https://github.com/0x4m4/hexstrike-ai/blob/master/_autodocs/03-http-endpoints.md

Starts an open-source intelligence gathering workflow. Specify target and options for including GitHub, social media, and breaches.

```json
{
  "target": "example.com",
  "include_github": true,
  "include_social": true,
  "include_breaches": true
}
```