pentestMCP

pentestMCP: Teste de Penetração com IA via MCP, um MCP projetado para testadores de penetração.

Documentação

pentestMCP: Testes de Penetração com IA via MCP

O pentestMCP fornece uma ponte poderosa entre Modelos de Linguagem de Grande Porte (LLMs) e ferramentas práticas de teste de penetração através do Model Context Protocol (MCP). Este projeto funciona como um Servidor MCP, expondo um conjunto selecionado de mais de 20 utilitários padrão de avaliação de segurança (Nmap, Nuclei, ZAP, SQLMap, etc.) como 'ferramentas' chamáveis. Isso permite que agentes de IA em clientes compatíveis com MCP (como Claude Desktop ou configurações específicas do VS Code) utilizem esses utilitários para análises de segurança automatizadas e interativas.

O objetivo é permitir o controle em linguagem natural sobre fluxos de trabalho de segurança complexos, tornando os recursos de teste de penetração mais acessíveis e integrados a ambientes orientados por IA. Este trabalho é inspirado no GhidraMCP de Laurie Kirk.

Sumário

Conceitos Centrais e Arquitetura
Principais Recursos
Pré-requisitos
Instalação e Configuração
- Usando Imagem Docker Pré-construída (Recomendado)
- Construindo a Imagem Docker Localmente
Integração com o Cliente Host
- Integração com Claude Desktop
- Integração com VS Code Copilot Chat
Referência de Ferramentas
Considerações de Segurança
Contribuindo
Licença
Aviso Legal
Agradecimentos

Demonstração em Vídeo

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

Conceitos Centrais e Arquitetura

O pentestMCP adere estritamente à especificação MCP, funcionando exclusivamente como um Servidor MCP. Ele não incorpora nem se comunica diretamente com nenhum LLM específico. O fluxo de interação é mediado por um aplicativo Cliente Host MCP:

Aplicativo Cliente Host (ex.: Claude Desktop, agente personalizado): Conecta-se ao pentestMCP (normalmente via stdio intermediado pelo Docker), gerencia a interação do usuário e faz a interface com um LLM escolhido.
LLM: Recebe prompts do usuário e definições de ferramentas (do pentestMCP via Cliente Host). Ele decide quais ferramentas invocar com base no contexto.
Servidor pentestMCP (Este Projeto): Executa dentro de um contêiner Docker. Escuta solicitações tools/call do Cliente Host, executa a ferramenta subjacente correspondente (ex.: nmap) e retorna os resultados.
Ferramentas Externas: Os utilitários reais de linha de comando encapsulados na imagem Docker.

O servidor é construído usando o SDK Python MCP (mcp.server.fastmcp.FastMCP) e apresenta:

Descoberta de Ferramentas: Utiliza dicas de tipo e docstrings do Python para geração automática do esquema de ferramentas MCP.
Controle de Concorrência: Um threading.Semaphore limita a execução simultânea de varreduras que consomem muitos recursos.
Padrão de Varredura Assíncrona: Implementa métodos de lançamento/obtenção para tarefas de longa duração (Nmap, Nuclei, SQLMap, Gobuster) para evitar o bloqueio da conexão MCP.

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

Principais Recursos

Conjunto Abrangente de Ferramentas: Integra mais de 20 ferramentas essenciais de teste de penetração via MCP.
Acesso Padronizado: Permite que qualquer cliente MCP que suporte o lançamento de servidor stdio utilize fluxos de trabalho complexos de teste de penetração.
Varreduras Não Bloqueantes: Gerencia com eficiência varreduras de longa duração sem travar o fluxo de interação.
Gerenciamento de Recursos: Implementa limitação básica de concorrência para varreduras.
Portátil e Reproduzível: O ambiente Dockerizado garante que todas as dependências e ferramentas estejam disponíveis de forma consistente em todas as plataformas (Windows, macOS, Linux).
Integração com Scanner Web: Fornece controle direto sobre o Active Scan do OWASP ZAP e as funcionalidades do AJAX Spider.

Pré-requisitos

Docker: Requer Docker Desktop (Windows/macOS) ou Docker Engine (Linux) instalado e em execução. Certifique-se de que o daemon do Docker esteja ativo.
Git: Necessário apenas se você for construir a imagem localmente (etapa git clone).
(Opcional, mas Recomendado) Instância OWASP ZAP: Para usar ferramentas relacionadas ao ZAP (run_zap_*, run_active_scan_*, run_ajax_*). Esta instância do ZAP precisa estar em execução e acessível pela rede de dentro do contêiner Docker do pentestMCP (consulte a seção Integração com o Cliente Host para configuração).

Instalação e Configuração

Recomendamos usar a imagem Docker pré-construída para a configuração mais rápida e confiável.

🐳 Usando Imagem Docker Pré-construída (Recomendado)

Usar a imagem pré-construída evita tempos de construção locais e garante que todas as ferramentas (como gofang, nmap e nuclei) estejam instaladas corretamente, sem problemas de dependência.

Baixe a imagem do Docker Hub:
```
docker pull ramgameer/pentest-mcp:latest
```
ℹ️ Nota: Dependendo do seu ambiente, pode ser necessário autenticar ou garantir que o daemon do Docker esteja em execução.

🛠️ Construindo a Imagem Docker Localmente

⚠️ IMPORTANTE: A construção local é atualmente mais eficiente e suportada em ambientes Linux.

Se você deseja modificar o código do servidor, usar a versão mais recente absoluta, ou se a imagem pré-construída não estiver disponível, você pode construir a imagem Docker localmente.

Clone o repositório:

git clone https://github.com/ramkansal/pentestMCP.git
cd pentestMCP

Construa a imagem Docker:

docker build -t pentest-mcp-server:custom .

Instale o SecLists (Opcional, mas altamente recomendado):

💡 Dica: Várias ferramentas (como Gobuster e utilitários de Fuzzing) dependem de listas de palavras massivas. Você deve clonar o repositório SecLists para que essas varreduras específicas funcionem de forma eficaz.
```
git clone https://github.com/danielmiessler/SecLists.git seclists
```

Integração com o Cliente Host

O pentestMCP executa dentro do Docker e se comunica com o Cliente Host via stdio. Você configura seu host (ex.: Claude Desktop, VS Code) para iniciar o servidor usando docker run -i ....

Integração com Claude Desktop

Localize/Crie o Arquivo de Configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Edite a Configuração: Adicione/atualize a seção mcpServers. Use o nome correto da imagem (ramgameer/pentest-mcp:latest ou sua tag personalizada).

{
  "mcpServers": {
    "pentestMCP": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ramgameer/pentest-mcp:latest"
      ]
    }
  }
}

Reinicie o Claude Desktop completamente.
Verifique: Procure o ícone . Clicar nele deve listar as ferramentas de teste de penetração.
Interaja: Peça ao Claude para usar as ferramentas (veja exemplos no rascunho).

Integração com VS Code Copilot Chat

A integração requer a configuração das configurações do VS Code para definir o servidor MCP para agentes do Copilot Chat que suportam MCP.

Instale o Pré-requisito: Certifique-se de que a extensão Github Copilot e as extensões relevantes do GitHub Copilot estejam instaladas.
Configure as Configurações do VS Code: Abra seu arquivo settings.json de Usuário ou Espaço de Trabalho (Paleta de Comandos: "Preferences: Open Settings (JSON)"). Adicione a configuração do servidor MCP no caminho apropriado (este caminho pode mudar dependendo da implementação específica do agente Copilot Chat, consulte sua documentação):
```
"pentest-mcp": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "ramgameer/pentest-mcp:latest"
    ]
}
```
Recarregue o VS Code / Agente: Reinicie o VS Code ou use comandos relevantes para recarregar a configuração do agente Copilot para que as alterações tenham efeito. Consulte a documentação específica do agente Copilot para obter detalhes.
Interaja: Use a interface do Copilot Chat, possivelmente invocando ferramentas via menções se o agente suportar, ou deixe o agente invocá-las com base em seus prompts.

Referência de Ferramentas

O servidor expõe uma variedade de ferramentas categorizadas por função:

Reconhecimento e Enumeração:
- run_subfinder: Descobre subdomínios usando o Subfinder do ProjectDiscovery.
- launch_nmap_scan / fetch_nmap_results: Executa varreduras de rede Nmap e recupera resultados assincronamente.
- run_gobuster_scan / check_gobuster_status: Realiza força bruta de diretórios/arquivos/DNS com Gobuster assincronamente.
- launch_gofang_scan / fetch_gofang_results: Executa gofang, um rastreador web completo com superpoderes de extração.
- run_harvester / check_harvester_status: Executa o theHarvester assincronamente para coleta de OSINT (e-mails, hosts, IPs).
- run_dig_tool: Executa consultas DNS dig.
- fetch_whois_data: Recupera informações WHOIS para um domínio.
- run_curl_tool: Executa comandos cURL para interação HTTP.
Varredura de Vulnerabilidades:
- launch_nuclei_scan / fetch_nuclei_results: Executa varreduras de vulnerabilidades baseadas em modelos com o Nuclei do ProjectDiscovery assincronamente.
Análise de Aplicações Web:
- launch_arjun_scan / fetch_arjun_results: Localiza parâmetros HTTP ocultos usando Arjun.
Suporte à Exploração:
- run_searchsploit: Pesquisa o banco de dados local Exploit-DB usando Searchsploit.
- run_sqlmap_tool / check_sqlmap_status: Executa o SQLmap para testes de injeção SQL assincronamente.
Análise de Active Directory (ferramentas ad_*):
- Enumeração: ad_user_enum, ad_shares_enum, ad_smb_signing_check, ad_certipy_enum, ad_ldap_dump, ad_bloodhound_collect
- Ataques/Coerção: ad_asreproast, ad_kerberoast, ad_password_spray, ad_coerce_petitpotam, ad_coerce_printerbug, ad_responder_poison, ad_relay_setup
- Operações de Credenciais/Domínio: ad_check_credentials, ad_secrets_dump, ad_dcsync

Considerações de Segurança

Permissões de Execução: As ferramentas são executadas como appuser dentro do Docker, mas o próprio Docker é executado com privilégios do host. Tenha cuidado com ferramentas que modificam arquivos ou exigem acesso elevado ao sistema.
Autorização do Alvo: CRÍTICO: Use estas ferramentas apenas contra sistemas para os quais você tenha autorização explícita, prévia e por escrito. Varreduras não autorizadas são ilegais e antiéticas.
Exposição de Rede: Se você mapear a porta do ZAP (-p 8888:8888), certifique-se de que o firewall do seu host restrinja o acesso se a máquina estiver em uma rede não confiável. A chave de API do ZAP configurada fornece controle sobre a instância.
Validação de Entrada: Embora o MCP forneça entrada estruturada, as ferramentas subjacentes ainda podem ser vulneráveis a argumentos manipulados se não forem tratadas de forma robusta nas funções wrapper Python.

Contribuindo

Contribuições são altamente incentivadas! Faça um fork do repositório, crie um branch de recurso e envie um pull request. Por favor, garanta a adesão às diretrizes de testes éticos em todas as contribuições. Relatórios de bugs e sugestões de recursos são bem-vindos via GitHub Issues.

Licença

Este projeto é distribuído sob os termos da Licença MIT.

Aviso Legal

Este software destina-se EXCLUSIVAMENTE a fins educacionais e testes de segurança autorizados e éticos. Qualquer uso contra sistemas sem permissão explícita é estritamente proibido e ilegal. Os autores e contribuidores NÃO assumem NENHUMA responsabilidade por uso indevido ou danos resultantes deste programa. Use por sua conta e risco e garanta a conformidade com todas as leis e acordos aplicáveis.

Agradecimentos

A inspiração profunda para este projeto vem do trabalho inovador de Laurie Kirk no GhidraMCP.