CHAI pentest tool

Cyber Host Artificial Intelligence (C.H.A.I) é um servidor MCP (Model Context Protocol) de teste de penetração autônomo, com um mecanismo de decisão de IA integrado, suporte a LLM de múltiplos provedores e uma arquitetura de plugins extensível.

GitHub

Experimente este MCPPatrocinado

Documentação

CHAI

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

Um servidor MCP (Model Context Protocol) de teste de penetração autônomo, pronto para produção, com um mecanismo de decisão de IA integrado, suporte a múltiplos provedores de LLM e uma arquitetura de plugins extensível. Projetado para Raspberry Pi 4/5 rodando Kali Linux ARM64.

## Visão Geral da Arquitetura

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   │
└─────────────────────────────────────────┘

Filosofia de Design: CÉREBRO FINO, LOOP ESPESSO

O LLM interno dispara apenas em pontos de decisão, não a cada etapa
Um execution_loop local lida com o encadeamento de ferramentas deterministicamente entre chamadas de LLM
Mantém o uso de tokens baixo (~6-10 chamadas por pentest completo) e latência aceitável em um Pi 4

Recursos

Suporte a Múltiplos Provedores de LLM

Azure OpenAI (GPT-4.1, GPT-4o, GPT-5+, Kimi, DeepSeek via Azure AI Foundry)
OpenAI Direto (GPT-4.1, GPT-4o, etc.)
Anthropic Claude (Sonnet, Opus)
Amazon Bedrock (Claude, Titan, Llama via AWS)
OpenRouter (100+ modelos com uma chave)
HuggingFace (DeepSeek, Qwen, Llama via Inference API)

Mecanismo de Decisão de IA

plan(): Decide o que testar em seguida com base nos achados
evaluate(): Decide se deve continuar ou parar
summarize_for_report(): Gera resumo executivo e prioridades de remediação

Segurança e Sandboxing

Perfis firejail com restrições de rlimit
cgroups do Linux para limitação de recursos
Execução de usuário restrito (pentester)
Política de segurança em camadas (Tier 1/2/3)
Registro de auditoria imutável de todos os comandos e decisões de IA

Sistema de Plugins

Descobre automaticamente plugins de plugins/bundled/ e plugins/external/
Arquitetura de plugin drop-in — sem necessidade de alterações no núcleo
Plugins incluídos: Feroxbuster, Metasploit, Burp Suite API

Banco de Dados

Somente SQLite — sem necessidade de Neo4j, Redis ou Postgres
Modo WAL para melhor concorrência
Grafo de conhecimento com 50+ técnicas de ataque e consultas recursivas de cadeia CTE

Estrutura do Projeto

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

Instalação

Pré-requisitos

Qualquer máquina Linux / Raspberry Pi 4/5 com Kali Linux ARM64 (bare metal, SEM Docker)
Python 3.11+
firejail instalado
Ferramentas de pentest do Kali Linux (nmap, sqlmap, nuclei, ffuf, etc.)

Configuração

# 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

Configuração

config.yaml (Config Principal)

Edite config.yaml para configurar:

Transporte do servidor (stdio ou SSE)
Limites de sandbox (RAM, CPU, timeout)
Seleção do provedor de LLM
Ativar/desativar plugins

Seções principais:

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 (Segredos)

# 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

Integração CHAI

Adicione ao seu config.json do 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 acesso remoto ao Pi):

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

Uso

Inicializar uma Sessão

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

Executar Varredura Autônoma (Uma Chamada, Teste Completo)

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"
# }

Chamadas Manuais de Ferramentas

# 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")

Adicionando um Novo Provedor de LLM

Passo 1 — Crie 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): ...

Passo 2 — Adicione um case a llm/provider_factory.py:

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

Passo 3 — Adicione o bloco de configuração a config.yaml:

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

Passo 4 — Adicione a chave a .security.yml:

gemini:
  api_key: ""

Passo 5 — Altere active_provider: "gemini" em config.yaml.

É isso. Nenhum outro arquivo muda.

Adicionando um Novo Plugin de Pentest

Passo 1 — Crie 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
        ...

Passo 2 — Reinicie o servidor. O plugin carrega automaticamente.

É isso. Nenhuma alteração no aplicativo principal.

Orçamento de Chamadas LLM

Para uma varredura autônoma de 4 fases:

Fase 1: plan() + evaluate() = 2 chamadas
Fase 2: plan() + evaluate() = 2 chamadas
Fase 3: plan() + evaluate() = 2 chamadas
Fase 4: plan() + evaluate() = 2 chamadas
Relatório: summarize_for_report() = 1 chamada
Total: ~9 chamadas LLM por pentest completo

Isso mantém o uso de tokens baixo e a latência aceitável em um Raspberry Pi 4.

Segurança e Conformidade

Lista de negação de comandos: Comandos perigosos (rm -rf /, fork bombs, etc.) são bloqueados
Sistema de camadas: Ferramentas classificadas por risco (Tier 1/2/3)
Verificação de escopo: Comandos validados contra o escopo definido
Limitação de taxa: Limites de execução concorrente por camada
Sandboxing: Todos os comandos são executados via firejail com limites de recursos
Trilha de auditoria: Cada comando e decisão de IA é registrado de forma imutável

Licença

Licença MIT — Consulte o arquivo LICENSE para detalhes.

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes (pytest)
Envie um pull request

Suporte

Para problemas e perguntas:

Issues do GitHub: https://github.com/NIHAR-SARKAR/CHAI/issues
Documentação: https://github.com/NIHAR-SARKAR/CHAI/blob/main/README.md
URL do site: https://aithread.in