MCPwner

MCPwner

Cuidado com o Texugo

Servidor do Model Context Protocol para pesquisa autônoma de segurança

Compatível com:

Sumário

• Visão Geral
• Fluxo de Trabalho
• Ferramentas Integradas
• Plugins
• Instalação
• Documentação
• Arquitetura
• Persistência de Dados
• Licença

Visão Geral

MCPwner é um servidor MCP que dá ao seu agente LLM um kit completo de ferramentas ofensivas de segurança. Ele expõe mais de 55 ferramentas conteinerizadas por meio de uma única interface MCP — SAST, SCA, segredos, IaC, reconhecimento, DAST, fuzzing guiado por cobertura, CodeQL (consultas integradas e personalizadas), um navegador headless, um servidor de callback OOB, um sandbox de scripts PoC com oráculos determinísticos e um registro persistente de descobertas.

A arquitetura é projetada para pesquisa de vulnerabilidades orientada por agente: uma única sessão de agente — independente de modelo (Claude, Cursor, Kiro, Gemini ou qualquer agente de codificação compatível com MCP) — percorre as fases de pesquisa (reconhecimento, auditoria de código, validação de PoC, revisão adversarial), registrando cada etapa no registro compartilhado de descobertas. Cada descoberta progride da hipótese à prova empírica e, em seguida, ao relatório verificado — "sem exploit, sem relatório."

Nota: Este projeto está em desenvolvimento ativo. Saiba mais sobre MCPs aqui.

Fluxo de Trabalho

MCPwner é o servidor de ferramentas; seu agente LLM é o cérebro. Um engajamento típico de pesquisa aprofundada:

O registro usa upserts de mesclagem profunda, então o veredito de review de uma fase posterior nunca sobrescreve os dados de poc anteriores (e vice-versa) — e permanece consistente se o contexto do agente for redefinido no meio do engajamento.

Ferramentas Integradas

Reconhecimento

Subfinder	Amass	Nmap	Masscan	ffuf

bbot	httpx	Katana	gau	Arjun

wafw00f	Kiterunner

Teste Estático de Segurança de Aplicações (SAST)

CodeQL	Psalm	Gosec	Bandit	Semgrep

Brakeman	PMD	NodeJsScan	Joern	YASA	OpenGrep

Fuzzing de Código-Fonte

Atheris	Jazzer	Jazzer.js	PHP-Fuzzer

Varredura de Segredos

Gitleaks	TruffleHog	detect-secrets	Whispers	Hawk-Eye

Análise de Composição de Software (SCA)

Grype	Syft	OSV-Scanner	Retire.js

Segurança de Infraestrutura e IaC

Checkov	KICS	Terrascan	TFSec	Hadolint

Teste Dinâmico de Segurança de Aplicações (DAST)

sqlmap	NoSQLMap	Commix	Dalfox	SSTImap

SSRFmap	jwt_tool	interactsh

Utilitários

Linguist	WireMock	Mitmproxy	aiohttp	Chromium w. Playwright

Validação de PoC

Sandbox de Scripts PoC
Executor de oráculo determinístico

O sandbox de PoC executa scripts de exploit em Python/bash escritos pelo agente dentro da rede alvo e retorna um veredito de oráculo determinístico (aprovado/reprovado com base no código de saída ou marcadores explícitos). É assim que o MCPwner prova bugs de lógica, IDOR/BOLA, condições de corrida e bypasses de controle de acesso que DAST prontos para uso não conseguem expressar.

Plugins

O MCPwner suporta um sistema opcional de plugins para ferramentas específicas de domínio. Os plugins adicionam serviços Docker, regras de varredura personalizadas e modelos de relatório sem modificar o núcleo. O MCPwner funciona com ou sem plugins instalados.

Plugins Disponíveis

Habilitando um Plugin

1. Adicione o nome do plugin a .env:

   PLUGINS=wp-scan
   COMPOSE_PROFILES=sast,dast,...,wp-scan
   

2. Use o wrapper de compose para iniciar os serviços (inclui automaticamente os arquivos compose do plugin):

   ./scripts/compose.sh up -d --build
   

   Ou use o empilhamento manual de -f:

   docker compose -f docker-compose.yaml -f plugins/wp-scan/docker-compose.yaml --profile wp-scan up -d
   

Ferramentas de plugins (ex.: wpscan, phpggc) são registradas automaticamente via manifest.yaml e aparecem como ferramentas MCP quando seus contêineres estão saudáveis.

Escrevendo um Plugin

Um plugin é um diretório sob plugins/ com:

• docker-compose.yaml — serviços (contextos de build relativos à raiz do projeto para empilhamento -f)
• manifest.yaml — registro de ferramentas (nome, categoria, caminho de configuração, URL padrão)
• docker/ — Dockerfiles e código do serviço
• rules/ — regras SAST personalizadas (opcional)
• templates/ — modelos de relatório (opcional)
• install.sh / uninstall.sh — scripts de configuração para instalações externas

Plugins também podem viver em um repositório separado e ser vinculados a plugins/ via symlink ou install.sh.

Instalação

Pré-requisitos

Requisitos do Sistema:

• Docker Engine 20.10+ e Docker Compose 2.0+
• Mínimo de 8GB de RAM (16GB recomendados para executar múltiplas ferramentas)
• 20GB de espaço livre em disco (as imagens das ferramentas de segurança são grandes)
• Plataformas suportadas: Linux, macOS, Windows (com WSL2)

Cliente MCP:

• Claude Desktop, Cursor, Kiro ou qualquer cliente compatível com MCP

Configuração

1. Clone o repositório:

   git clone https://github.com/nedlir/mcpwner.git
   cd mcpwner
   

2. Configure o servidor:

   cp .env.example .env
   cp config/config.yaml.example config/config.yaml
   

3. Inicie os serviços:

   docker compose up -d --build
   

4. Verifique se os serviços estão em execução:

   docker compose ps
   

Conecte Sua IDE

Assim que os contêineres Docker estiverem em execução, adicione MCPwner ao seu cliente MCP.

Registro Dinâmico de Ferramentas: MCPwner usa Docker Compose profiles para categorias de ferramentas opt-in. A variável COMPOSE_PROFILES do arquivo .env controla quais contêineres iniciam. O servidor MCP verifica os contêineres em execução na inicialização e registra apenas ferramentas saudáveis — se um contêiner estiver inativo, suas ferramentas simplesmente não aparecem. O Linguist (detecção de idioma / índice de fatos de código) é executado incondicionalmente; os utilitários de teste dinâmico (Chromium, WireMock, mitmproxy, fuzzer) são opt-in e sobem com os perfis dast e poc.

Instalação com Um Clique (requer Docker em execução):

Configuração Manual:

Adicione ao seu arquivo de configuração MCP (claude_desktop_config.json, mcp.json, etc.):

{
  "mcpServers": {
    "mcpwner": {
      "command": "docker",
      "args": ["exec", "-i", "mcpwner-server", "python", "src/server.py"],
      "env": {}
    }
  }
}

Reinicie seu cliente MCP para carregar a nova configuração do servidor.

Escaneando Projetos Locais

Monte seus projetos no contêiner adicionando um volume em docker-compose.yaml:

services:
  mcpwner:
    volumes:
      - /path/to/your/projects:/mnt/projects:ro

Em seguida, use create_workspace com source_type="local" e source="/mnt/projects/my-project".

Documentação

Guias adicionais estão no wiki do projeto:

• Quickstart — inicie a frota de ferramentas com COMPOSE_PROFILES e conecte o servidor MCP ao seu cliente.
• Configuração — .env / COMPOSE_PROFILES, config.yaml e o mapa de portas das ferramentas.
• Solução de Problemas — ferramentas ausentes, contêineres não saudáveis e falhas de build de imagem.
• Adicionando uma ferramenta — conecte um novo contêiner de scanner à frota e ao registro de ferramentas.

Contribuindo? Veja CONTRIBUTING.md para estilo de código, hooks de pré-commit e testes.

Arquitetura

graph LR
    subgraph IDE[" "]
        LLM[🤖<br/>LLM]
        Client[MCP Client]
        LLM -.-> Client
    end

    Server[MCPwner Server]

    SAST[SAST Tools]
    Secrets[Secrets Scanning]
    SCA[SCA Tools]
    Recon[Reconnaissance]
    CodeQL[CodeQL Service]
    Linguist[Language Detection]
    Utilities[Utilities]
    IaC[IaC Security]
    Fuzzing[Source Fuzzing]
    DAST[DAST Tools]
    PoC[PoC Sandbox]

    Client -->|JSON-RPC 2.0| Server
    Server -->|HTTP| SAST
    Server -->|HTTP| Secrets
    Server -->|HTTP| SCA
    Server -->|HTTP| Recon
    Server -->|HTTP| CodeQL
    Server -->|HTTP| Linguist
    Server -->|HTTP| Utilities
    Server -->|HTTP| IaC
    Server -->|HTTP| Fuzzing
    Server -->|HTTP| DAST
    Server -->|HTTP| PoC

    style LLM fill:#7C3AED,stroke:#5B21B6,stroke-width:3px,color:#fff
    style Client fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    style Server fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#fff
    style SAST fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
    style Secrets fill:#9B59B6,stroke:#7D3C98,stroke-width:2px,color:#fff
    style SCA fill:#1ABC9C,stroke:#16A085,stroke-width:2px,color:#fff
    style Recon fill:#00BCD4,stroke:#0097A7,stroke-width:2px,color:#fff
    style CodeQL fill:#E67E22,stroke:#CA6F1E,stroke-width:2px,color:#fff
    style Linguist fill:#3498DB,stroke:#2874A6,stroke-width:2px,color:#fff
    style Utilities fill:#6D28D9,stroke:#4C1D95,stroke-width:2px,color:#fff
    style IaC fill:#059669,stroke:#047857,stroke-width:2px,color:#fff
    style Fuzzing fill:#B91C1C,stroke:#7F1D1D,stroke-width:2px,color:#fff
    style DAST fill:#D35400,stroke:#A04000,stroke-width:2px,color:#fff
    style PoC fill:#DC2626,stroke:#991B1B,stroke-width:2px,color:#fff
    style IDE fill:none,stroke:#ddd,stroke-width:2px,stroke-dasharray: 5 5

Princípios de Design:

• Isolamento de contêineres para execução de ferramentas de segurança
• Saída padronizada (SARIF/JSON) para consumo por LLM
• Registro dinâmico de ferramentas — apenas contêineres saudáveis aparecem como ferramentas
• Registro persistente de descobertas com semântica de mesclagem profunda entre fases de pesquisa
• Oráculos determinísticos para validação de PoC (código de saída, marcadores, callbacks OOB, execução de XSS)

Fluxo de Trabalho do Agente

MCPwner é infraestrutura de ferramentas. Uma única sessão de agente — independente de modelo (Claude, Cursor, Kiro, Gemini ou qualquer agente de codificação compatível com MCP) — conduz todo o engajamento, executando cada fase por conta própria (recon → mapeamento de API → ambiente → auditoria de código → pesquisa de vulnerabilidades → PoC → revisão) e registrando o progresso no registro de descobertas. Não há serviço de orquestração separado nem arquivo de configuração: MCPwner expõe ferramentas, o agente fornece o fluxo de trabalho.

Para uma subtarefa longa e isolada — canonicamente, montar e conduzir um ambiente de destino ativo em um contêiner — o agente pode opcionalmente delegar a uma sessão auxiliar se seu host suportar uma, mas o fluxo nunca depende disso.

Persistência de Dados

MCPwner persiste metadados do workspace, bancos de dados CodeQL e descobertas entre reinicializações de contêineres usando armazenamento baseado em arquivos no volume Docker compartilhado (/workspaces/.metadata/). O registro de descobertas está sempre disponível (sem verificação de saúde do contêiner) — é assim que o agente acompanha descobertas entre fases e recupera o estado após uma redefinição de contexto.

Limpeza do Workspace:

• delete_files=True, delete_metadata=False — Libere espaço em disco, preserve o histórico
• delete_files=True, delete_metadata=True — Remoção completa
• delete_files=False, delete_metadata=True — Remover da lista, manter arquivos

Licença

Apache 2.0