CHAI pentest tool

Cyber Host Artificial Intelligence (C.H.A.I) es un servidor MCP (Protocolo de Contexto de Modelo) de pruebas de penetración autónomas con un motor de decisión de IA integrado, soporte para múltiples proveedores de LLM y una arquitectura de plugins extensible.

GitHub

Prueba este MCPPatrocinado

Documentación

CHAI

Cyber Host Artificial Intelligence (C.H.A.I)

Un servidor MCP (Model Context Protocol) de pruebas de penetración autónomo, listo para producción, con un motor de decisión de IA integrado, soporte multi-proveedor de LLM y una arquitectura de plugins extensible. Diseñado para Raspberry Pi 4/5 con Kali Linux ARM64.

## Descripción General de la Arquitectura

External Client (CHAI / any MCP tool)
         │  MCP stdio/SSE
         ▼
┌─────────────────────────────────────────┐
│         MCP Security Server             │
│                                         │
│  run_autonomous_scan()                  │
│         │                               │
│    ┌────▼────────────────────┐          │
│    │   execution_loop.py     │          │
│    │  (local, no LLM here)   │          │
│    │  tool1 → tool2 → tool3  │          │
│    └────┬────────────────────┘          │
│         │ at phase boundaries only      │
│    ┌────▼────────────────────┐          │
│    │   ai_planner.py         │          │
│    │  plan / evaluate /      │◄─────────┼── llm/provider_factory.py
│    │  summarize              │          │   (Azure / OpenAI / Claude /
│    └─────────────────────────┘          │    Bedrock / OpenRouter / HF)
│                                         │
│  All tools, safety, sandbox unchanged   │
└─────────────────────────────────────────┘

Filosofía de diseño: CEREBRO DELGADO, BUCLE GRUESO

El LLM interno se activa solo en los puntos de decisión, no en cada paso
Un execution_loop local maneja el encadenamiento de herramientas de forma determinista entre llamadas al LLM
Mantiene el uso de tokens bajo (~6-10 llamadas por prueba de penetración completa) y la latencia aceptable en una Pi 4

Características

Soporte Multi-Proveedor de LLM

Azure OpenAI (GPT-4.1, GPT-4o, GPT-5+, Kimi, DeepSeek vía Azure AI Foundry)
OpenAI directo (GPT-4.1, GPT-4o, etc.)
Anthropic Claude (Sonnet, Opus)
Amazon Bedrock (Claude, Titan, Llama vía AWS)
OpenRouter (más de 100 modelos con una sola clave)
HuggingFace (DeepSeek, Qwen, Llama vía Inference API)

Motor de Decisión de IA

plan(): Decide qué probar a continuación según los hallazgos
evaluate(): Decide si continuar o detenerse
summarize_for_report(): Genera un resumen ejecutivo y prioridades de remediación

Seguridad y Aislamiento (Sandboxing)

Perfiles de firejail con restricciones rlimit
cgroups de Linux para limitación de recursos
Ejecución de usuario restringido (pentester)
Política de seguridad por niveles (Nivel 1/2/3)
Registro de auditoría inmutable de todos los comandos y decisiones de IA

Sistema de Plugins

Descubre automáticamente plugins desde plugins/bundled/ y plugins/external/
Arquitectura de plugins de inserción directa: no se necesitan cambios en el núcleo
Plugins incluidos: Feroxbuster, Metasploit, Burp Suite API

Base de Datos

SOLO SQLite: no se requieren Neo4j, Redis ni Postgres
Modo WAL para mejor concurrencia
Grafo de conocimiento con más de 50 técnicas de ataque y consultas recursivas de cadenas CTE

Estructura del Proyecto

CHAI/
├── main.py                          # FastMCP server entry point
├── config.py                        # Configuration loader
├── config.yaml                      # Main configuration (no secrets)
├── .security.yml                    # API keys (git-ignored)
├── requirements.txt                 # Python dependencies
├── app_context.py                   # Application context singleton
│
├── llm/                             # Multi-provider LLM adapter layer
│   ├── base_provider.py             # Abstract base class
│   ├── provider_factory.py          # Provider selection with fallback
│   ├── prompt_templates.py          # All LLM prompts (versioned)
│   └── providers/
│       ├── azure_openai.py          # Azure OpenAI
│       ├── openai_direct.py         # Direct OpenAI
│       ├── anthropic_claude.py      # Claude
│       ├── amazon_bedrock.py        # AWS Bedrock
│       ├── openrouter.py            # OpenRouter
│       └── huggingface.py           # HuggingFace
│
├── core/                            # Core engine
│   ├── session_manager.py           # SQLite session CRUD + state machine
│   ├── safety_policy.py             # Command validation, tier system
│   ├── process_controller.py        # firejail/cgroups/chroot wrapper
│   ├── audit_logger.py              # Immutable audit logging
│   ├── ai_planner.py                # LLM decision engine (3 call types)
│   └── execution_loop.py            # Local chain runner
│
├── kb/                              # Knowledge Base
│   ├── graph_db.py                  # Attack graph with recursive CTE
│   ├── playbook_loader.py           # Playbook section extraction
│   └── vector_search.py             # Vector/BM25 search
│
├── tools/                           # Security testing tools
│   ├── base.py                      # Base tool class
│   ├── recon.py                     # Reconnaissance
│   ├── scan.py                      # Vulnerability scanning
│   ├── injection.py                 # Injection testing
│   ├── auth.py                      # Authentication testing
│   ├── network.py                   # Network testing
│   ├── poc.py                       # PoC generation
│   ├── exec.py                      # Custom command execution
│   ├── analyze.py                   # Findings analysis
│   ├── report.py                    # Report generation
│   └── autonomous.py                # Autonomous scan orchestrator
│
├── plugins/                         # Plugin system
│   ├── plugin_base.py               # Base class
│   ├── plugin_loader.py             # Auto-discovery loader
│   └── bundled/
│       ├── feroxbuster_plugin.py    # Directory bruteforcer
│       ├── metasploit_plugin.py     # Metasploit Framework
│       └── burp_api_plugin.py      # Burp Suite Pro API
│
├── models/                          # Data models
│   ├── session.py                   # Session and Finding models
│   └── schemas.py                   # Pydantic schemas
│
├── utils/                           # Utilities
│   ├── command_parser.py            # Command parsing
│   ├── output_parser.py             # Tool output parsing
│   └── cvss_calculator.py           # CVSS v3.1 calculator
│
└── data/                            # Database schemas & profiles
    ├── init_sessions.sql            # Session DB schema + AI decisions table
    ├── init_graph.sql               # Knowledge graph (50+ nodes)
    └── firejail/
        └── pentest.profile          # Firejail sandbox profile

Instalación

Requisitos Previos

Cualquier máquina Linux / Raspberry Pi 4/5 con Kali Linux ARM64 (hardware real, SIN Docker)
Python 3.11+
firejail instalado
Herramientas de pruebas de penetración de Kali Linux (nmap, sqlmap, nuclei, ffuf, etc.)

Configuración Inicial

# Clone the repository
git clone https://github.com/NIHAR-SARKAR/CHAI.git
cd CHAI

# Create virtual environment
python -m venv .venv
source .venv/bin/activate -- linux
.venv\Scripts\activate    -- windows

# Install dependencies
pip install -r requirements.txt

# Configure secrets
cp .security.yml.example .security.yml
chmod 600 .security.yml
# Edit .security.yml with your API keys

# Create required directories
### linux
sudo mkdir -p /opt/sessions /opt/logs /opt/kb /opt/mcp-security-server/plugins/external
sudo chown -R $(whoami) /opt/sessions /opt/logs /opt/kb

### windows PowerSheel
New-Item -ItemType Directory -Force -Path "C:\opt\sessions"
New-Item -ItemType Directory -Force -Path "C:\opt\logs"
New-Item -ItemType Directory -Force -Path "C:\opt\kb"
New-Item -ItemType Directory -Force -Path "C:\opt\mcp-security-server\plugins\external"

icacls "C:\opt" /grant "$env:USERNAME:(OI)(CI)F" /Ts -- Grant current user full permissions

# Install firejail profile
sudo cp data/firejail/pentest.profile /etc/firejail/



# run server
python main.py --transport streamable-http

Configuración

config.yaml (Configuración Principal)

Edita config.yaml para configurar:

Transporte del servidor (stdio o SSE)
Límites del sandbox (RAM, CPU, tiempo de espera)
Selección del proveedor de LLM
Habilitar/deshabilitar plugins

Secciones clave:

llm:
  active_provider: "azure_openai" # Change to your preferred provider
  fallback_provider: "openrouter" # Optional fallback

ai_planner:
  max_phases: 4 # Max autonomous phases
  stop_on_critical: true # Stop on critical findings

plugins:
  bundled:
    feroxbuster: true
    metasploit: false # Disabled by default (Tier 3)
    burp_api: false # Needs Burp Pro API key

.security.yml (Secretos)

# NEVER commit this file
azure_openai:
  api_key: "your-azure-key"

openai:
  api_key: "your-openai-key"

anthropic:
  api_key: "your-anthropic-key"

# ... etc for each provider

Integración con CHAI

Añade a tu config.json de CHAI:

Transporte stdio:

{
  "tools": {
    "mcp": {
      "servers": {
        "chai-security": {
          "transport": "stdio",
          "command": "python",
          "args": ["-m", "main.py"],
          "cwd": "/opt/mcp-security-server",
          "env": {
            "PYTHONPATH": "/opt/mcp-security-server"
          },
          "discovery": "deferred"
        }
      }
    }
  }
}

Transporte SSE (para acceso remoto a la Pi):

{
  "tools": {
    "mcp": {
      "servers": {
        "chai-security": {
          "transport": "sse",
          "url": "http://raspberrypi.local:9010/sse"
        }
      }
    }
  }
}

Uso

Inicializar una Sesión

initialize_session(
    target="https://target.example.com",
    test_type="web_app",
    scope=["target.example.com"]
)
# Returns: {"session_id": "sess-abc-123", ...}

Ejecutar Escaneo Autónomo (Una Llamada, Prueba Completa)

run_autonomous_scan(
    session_id="sess-abc-123",
    max_phases=4,
    stop_on_critical=True,
    generate_report=True,
    provider_override=None  # Uses config.yaml active_provider
)
# Internally: plan → [recon → scan → inject] → evaluate → plan → [...] → report
# Returns after ~15-30 min:
# {
#   "phases_completed": 3,
#   "total_findings": 12,
#   "critical_count": 1,
#   "high_count": 4,
#   "report_path": "/opt/sessions/reports/sess-abc-123.md",
#   "status": "complete"
# }

Llamadas Manuales a Herramientas

# Reconnaissance
run_recon(session_id="sess-abc-123", target="target.example.com", recon_type="passive")

# Vulnerability scanning
scan_vulnerabilities(session_id="sess-abc-123", target="target.example.com", scanner="nuclei")

# Injection testing
test_injection(session_id="sess-abc-123", target="target.example.com", injection_type="sqli")

# Authentication testing
test_authentication(session_id="sess-abc-123", target="target.example.com", test_type="bypass")

# Network testing
test_network(session_id="sess-abc-123", target="target.example.com", test_type="ssl")

# Custom command
execute_command(session_id="sess-abc-123", command="nmap -sV target.example.com")

# Run plugin
run_plugin(session_id="sess-abc-123", plugin_name="feroxbuster", target="https://target.example.com")

# Generate report
generate_report(session_id="sess-abc-123", format="markdown")

# Check status
get_session_status(session_id="sess-abc-123")

# Emergency stop
emergency_stop(session_id="sess-abc-123")

Añadir un Nuevo Proveedor de LLM

Paso 1 — Crea llm/providers/gemini.py:

from llm.base_provider import BaseLLMProvider, LLMResponse

class GeminiProvider(BaseLLMProvider):
    def __init__(self, config): ...
    @property
    def provider_name(self): return "gemini"
    async def complete(self, ...): ...
    async def health_check(self): ...

Paso 2 — Añade un case a llm/provider_factory.py:

case "gemini":
    from llm.providers.gemini import GeminiProvider
    return GeminiProvider(config)

Paso 3 — Añade el bloque de configuración a config.yaml:

llm:
  gemini:
    enabled: true
    model: "gemini-2.5-pro"
    api_base: "https://generativelanguage.googleapis.com/v1beta/openai"

Paso 4 — Añade la clave a .security.yml:

gemini:
  api_key: ""

Paso 5 — Cambia active_provider: "gemini" en config.yaml.

Eso es todo. No cambia ningún otro archivo.

Añadir un Nuevo Plugin de Pentest

Paso 1 — Crea plugins/external/gospider_plugin.py:

from plugins.plugin_base import PentestPlugin, PluginMetadata, PluginResult

class GospiderPlugin(PentestPlugin):
    @property
    def metadata(self):
        return PluginMetadata(
            name="gospider", display_name="GoSpider Web Crawler",
            version="1.1.6", description="Fast web spider",
            tier="tier1", requires_binary="gospider",
            tags=["web", "recon", "crawler"],
        )
    async def run(self, session_id, target, args, process_controller, safety_policy, session_manager):
        # Build command, validate through safety_policy, execute via process_controller
        ...

Paso 2 — Reinicia el servidor. El plugin se carga automáticamente.

Eso es todo. No hay cambios en la aplicación principal.

Presupuesto de Llamadas al LLM

Para un escaneo autónomo de 4 fases:

Fase 1: plan() + evaluate() = 2 llamadas
Fase 2: plan() + evaluate() = 2 llamadas
Fase 3: plan() + evaluate() = 2 llamadas
Fase 4: plan() + evaluate() = 2 llamadas
Informe: summarize_for_report() = 1 llamada
Total: ~9 llamadas al LLM por prueba de penetración completa

Esto mantiene el uso de tokens bajo y la latencia aceptable en una Raspberry Pi 4.

Seguridad y Cumplimiento

Lista de comandos bloqueados: los comandos peligrosos (rm -rf /, fork bombs, etc.) están bloqueados
Sistema de niveles: herramientas clasificadas por riesgo (Nivel 1/2/3)
Verificación de alcance: comandos validados contra el alcance definido
Límite de velocidad: límites de ejecución concurrente por nivel
Aislamiento: todos los comandos se ejecutan a través de firejail con límites de recursos
Rastro de auditoría: cada comando y decisión de IA se registra de forma inmutable

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Añade pruebas (pytest)
Envía una solicitud de extracción (pull request)

Soporte

Para problemas y preguntas:

GitHub Issues: https://github.com/NIHAR-SARKAR/CHAI/issues
Documentación: https://github.com/NIHAR-SARKAR/CHAI/blob/main/README.md
URL del sitio: https://aithread.in