- Linux, macOS ou Windows com WSL2
- Docker 20.10+ e Docker Compose
- Python 3.12+
- Node.js 18+ (para Web UI)
- 4GB+ de RAM (8GB recomendado)
# macOS & Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Verificar instalação
uv --version
# Ubuntu/Debian
sudo apt update && sudo apt install -y docker.io docker-compose
# macOS
brew install --cask docker
# Verificar
docker --version && docker compose version
# Ubuntu/Debian - Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
# macOS - Node.js
brew install node@18
# Instalar pnpm
npm install -g pnpm
# ou
corepack enable && corepack prepare pnpm@latest --activate
# Clonar repositório
git clone https://github.com/yohannesgk/blacksmith.git
cd blacksmith
# Instalar dependências Python
cd blacksmithAI/blacksmithAI
uv sync
# Construir imagem Docker mini-kali
docker compose up -d
# Opcional: Instalar dependências do frontend
cd ../frontend && pnpm install
# Copiar modelo de ambiente
cp blacksmithAI/.env.example blacksmithAI/.env
# Editar arquivo .env
nano blacksmithAI/.env
# Adicionar a .env
OPENROUTER_API_KEY=your-openrouter-api-key-here
# Instalar VLLM
cd blacksmithAI/blacksmithAI
uv add vllm huggingface_hub
# Iniciar servidor VLLM
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 8192 \
--gpu-memory-utilization 0.75
Editar blacksmithAI/config.json:
{
"defaults": {
"provider": "openrouter"
},
"providers": {
"openrouter": {
"base_url": "https://openrouter.ai/api/v1/chat/completions",
"default_model": "mistralai/devstral-2512:free",
"default_embedding_model": "openai/text-embedding-3-small",
"default_model_config": {
"context_size": 200000,
"max_retries": 3,
"max_tokens": null
}
},
"vllm": {
"base_url": "http://localhost:8000/v1/chat/completions",
"default_model": "mistralai/devstral-2512",
"default_embedding_model": "text-embedding-3-small",
"default_model_config": {
"context_size": 200000,
"max_retries": 3
}
}
}
}
# Adicionar à seção providers de config.json
"openai": {
"base_url": "https://api.openai.com/v1/chat/completions",
"default_model": "gpt-4-turbo",
"default_embedding_model": "text-embedding-3-small"
}
# Adicionar a .env
OPENAI_API_KEY=your-openai-key
# Atualizar defaults
"defaults": { "provider": "openai" }
# Terminal 1: Iniciar contêiner mini-kali
cd blacksmithAI/blacksmithAI
docker compose up -d
# Terminal 2: Executar BlacksmithAI CLI
cd blacksmithAI/blacksmithAI
uv run main.py
# Ou usar atalho do Makefile
make start-cli
# Terminal 1: Iniciar contêiner Docker mini-kali
cd blacksmithAI/blacksmithAI
docker compose up -d
# Terminal 2: Iniciar frontend (do diretório blacksmithAI/frontend)
pnpm build && pnpm start
# Terminal 3: Iniciar servidor de desenvolvimento LangGraph (do blacksmithAI/blacksmithAI)
uv run langgraph dev
# Acessar em http://localhost:3000
# Iniciar contêiner
docker compose up -d
# Ver logs
docker logs mini-kali-slim
# Parar contêiner
docker compose down
# Reiniciar contêiner
docker compose restart
# Remover todos os contêineres
docker compose down -v
- Papel: Controle de comando central
- Função: Planejamento de missão, delegação de tarefas, geração de relatórios
- Ferramentas Disponíveis: Ferramentas de planejamento, ferramentas de sistema de arquivos
- Propósito: Coleta de informações passiva e ativa
- Ferramentas: assetfinder, subfinder, whois, dig, nslookup, hping3, dnsrecon
- Saída: Registros DNS, subdomínios, topologia de rede
- Propósito: Enumeração de usuários, sondagem de API, descoberta de versão
- Ferramentas: nmap, masscan, enum4linux-ng, nikto, whatweb, fingerprintx, gobuster, wpscan
- Saída: Portas abertas, serviços, tecnologias, endpoints
- Propósito: Mapear serviços para CVEs, priorizar riscos
- Ferramentas: nuclei, sslscan
- Saída: Lista de vulnerabilidades com pontuações de gravidade e exploração
- Propósito: Validar vulnerabilidades com exploits controlados
- Ferramentas: sqlmap, hydra, medusa, ncrack, scripts personalizados (Python/Go/Perl/Ruby)
- Saída: Prova de comprometimento com evidência
- Propósito: Avaliar raio de blast e oportunidades de pivô
- Ferramentas: netcat, socat, tunneling SSH, impacket
- Saída: Caminhos de movimento lateral, inventário de credenciais, impacto nos negócios
# Sequência de fluxo de trabalho típica
1. Especificação de alvo (domínio/IP)
2. Orquestrador inicia fase de reconhecimento
3. Agente Recon descobre: subdomínios, registros DNS, servidores de correio
4. Resultados alimentados ao agente Scan/Enum
# Fluxo de trabalho de avaliação completo
Orquestrador (planejamento)
↓
Agente Recon (superfície de ataque) → saída: serviços & tecnologias
↓
Agente Scan/Enum (inspeção profunda) → saída: portas & versões
↓
Agente de Análise de Vuln (mapeamento de risco) → saída: lista de CVE com pontuação
↓
Agente de Exploit (validação de PoC) → saída: exploits funcionando
↓
Agente de Pós-Exploit (impacto) → saída: caminhos de movimento lateral
↓
Orquestrador (relatório final com remediação)
# Alvo direto serviços identificados para análise de vuln
1. Fornecer informação de serviço (versão, porta)
2. Agente de Análise de Vuln mapeia para CVEs
3. Agente de Exploit testa vulnerabilidades de alta prioridade
| Ferramenta | Comando | Propósito |
|---|
| assetfinder | assetfinder target.com | Descoberta de subdomínio |
| subfinder | subfinder -d target.com | Enumeração de subdomínio |
| whois | whois target.com | Pesquisa de informação de domínio |
| dig | dig target.com | Consultas de registro DNS |
| dnsrecon | dnsrecon -d target.com | Enumeração de DNS |
| hping3 | hping3 -p 80 target.com | Varredura de rede |
| Ferramenta | Comando | Propósito |
|---|
| nmap | nmap -sV target.com | Varredura de porta & detecção de versão |
| masscan | masscan 0.0.0.0/0 -p80,443 | Varredura de porta de alta velocidade |
| nikto | nikto -h target.com | Varredura de vulnerabilidade de servidor web |
| gobuster | gobuster dir -u http://target.com -w wordlist.txt | Brute-forcing de diretório/DNS |
| wpscan | wpscan --url target.com | Varredura de vulnerabilidade de WordPress |
| whatweb | whatweb target.com | Identificação de tecnologia web |
| Ferramenta | Comando | Propósito |
|---|
| nuclei | nuclei -target target.com | Varredura de vulnerabilidade rápida |
| sslscan | sslscan target.com:443 | Análise de configuração SSL/TLS |
| Ferramenta | Propósito |
|---|
| sqlmap | Teste automatizado de injeção SQL |
| hydra | Brute-forcing de senha |
| medusa | Auditoria de login de rede paralela |
| ncrack | Quebra de autenticação de rede |
| Scripts Personalizados | Desenvolvimento de exploit Python/Go/Perl/Ruby |
| Ferramenta | Propósito |
|---|
| netcat | Depuração de rede & transferência de dados |
| socat | Relé multi-propósito |
| ssh -D | Tunelamento de proxy SOCKS para pivô |
| impacket | Ferramentas de protocolo Windows (psexec, secretsdump) |
# Orquestrador gera relatórios estruturados contendo:
- Resumo Executivo
- Descobertas com classificações de gravidade
- Detalhes de evidência e prova de conceito
- Sistemas e serviços afetados
- Orientação de remediação
- Avaliação de impacto nos negócios
{
"mission_name": "Teste de Penetração - Example Corp",
"target": "example.com",
"findings": [
{
"vulnerability": "Injeção SQL no formulário de login",
"severity": "CRITICAL",
"affected_service": "Aplicativo web v2.1",
"evidence": "SELECT version() retornou versão do banco de dados",
"remediation": "Usar instruções preparadas, validação de entrada"
}
],
"timeline": "2025-03-10T14:30:00Z",
"tested_systems": ["web-server", "api-gateway", "database"]
}
{
"providers": {
"custom-provider": {
"base_url": "https://your-api-endpoint.com/v1/chat/completions",
"default_model": "your-model-name",
"default_embedding_model": "embedding-model",
"default_model_config": {
"context_size": 200000,
"max_retries": 3,
"max_tokens": null
}
}
}
}
# Modelo pequeno (7B) - mais rápido, menos memória
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
--host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.75
# Modelo grande (123B) - mais capaz
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
--host 0.0.0.0 --port 8000 --max-model-len 8192
# Modelo personalizado do HuggingFace
uv run hf auth login # Fazer login no HF primeiro
vllm serve meta-llama/Llama-2-7b-chat-hf \
--host 0.0.0.0 --port 8000
# Configuração & Instalação
make help # Mostrar todos os comandos
make setup # Configuração inicial completa
make install # Apenas dependências Python
make frontend-install # Dependências de frontend
# Gerenciamento de Docker
make docker-build # Construir imagem mini-kali
make docker-up # Iniciar contêiner
make docker-down # Parar contêiner
make docker-logs # Ver logs
# VLLM LLM Local
make vllm-install # Instalar VLLM
make vllm-serve # Iniciar VLLM (123B)
make vllm-serve-small # Iniciar VLLM (7B)
# Executando BlacksmithAI
make start-cli # Modo CLI
make start-ui # Web UI (mostra configuração)
make start-all # Início rápido CLI
# Utilitários
make status # Status do contêiner Docker
make check-deps # Verificar dependências
make check-config # Verificar configuração
make clean # Limpar contêineres
make stop # Parar todos os serviços
# Coletar dados com ferramentas externas
assetfinder -subs-only target.com > subdomains.txt
# Alimentar em BlacksmithAI
# Agentes executarão scans direcionados em subdomínios descobertos
- Saída de Nmap → Alimentada a Análise de Vuln para mapeamento de serviço
- Listas de subdomínio → Varredura direcionada por agente Scan/Enum
- Endpoints de API → Teste direto de vulnerabilidade
- Sistemas de autenticação → Tentativas de brute-force & exploração
# Escrever scripts de exploração personalizado em diretórios de agente
# Agentes podem executar scripts Python/Go/Perl/Ruby
# Exemplo: Payload de injeção SQL personalizado
cat > custom_exploit.py << 'EOF'
import sys
target = sys.argv[1]
# Lógica de exploração personalizado
EOF
# Agentes invocam: python custom_exploit.py target.com
# Definir escopo por escrito
- Lista de alvo (domínios/IPs)
- Período de teste
- Sistemas autorizados & vetores de ataque
- Requisitos de relatório
- Manipulação de dados sensíveis
# Validar autorização legal
- Permissão por escrito de cliente/proprietário
- Regras de engajamento (RoE)
- Acordos de NDA e confidencialidade
# Recomendações
1. Usar ambientes de teste isolados quando possível
2. Começar apenas com reconhecimento
3. Testar vulnerabilidades sequencialmente, não em paralelo
4. Evitar payloads destrutivos sem aprovação explícita
5. Monitorar comportamento do sistema durante exploração
6. Manter logs detalhados de todas as atividades
# Conclusões abrangentes devem incluir:
- Descrição clara de vulnerabilidade
- Pontuação CVSS/gravidade
- Evidência de prova de conceito
- Serviços e versões afetados
- Avaliação de impacto nos negócios
- Etapas de remediação prioritizadas
- Cronograma de exploração
# A escolha do modelo afeta os resultados:
- Modelos mais rápidos: Reconhecimento rápido, varredura básica
- Modelos maiores: Análise complexa, melhor tomada de decisão
- VLLM local: Focado em privacidade, sem dependências de API
- OpenRouter: Custo-efetivo, múltiplas opções de modelo
# Recomendação: Usar Sonnet/GPT-4 para avaliação complexa
- Sempre obter permissão por escrito antes de testar
- Definir escopo claramente em regras de engajamento
- Testar apenas sistemas que você possui ou tem autorização escrita explícita para testar
- Violação de leis (CFAA, GDPR, etc.) pode resultar em responsabilidade civil/criminal
# Após testes:
1. Documentar todas as descobertas com gravidade
2. Notificar proprietário do sistema sobre vulnerabilidades
3. Permitir tempo razoável para correção (tipicamente 90 dias)
4. Manter confidencialidade dos detalhes de vulnerabilidade
5. Reportar a fornecedores se produtos terceirizados forem afetados
- Minimizar extração de dados durante testes
- Armazenar com segurança todos os relatórios e evidências
- Usar criptografia para descobertas sensíveis
- Cumprir regulamentos de proteção de dados (GDPR, HIPAA, etc.)
- Destruir dados após conclusão do engajamento
# Contêiner não inicia
docker ps # Verificar se está em execução
docker logs mini-kali-slim # Ver erros
# Conflitos de porta
lsof -i :9756 # Verificar uso de porta
docker run -i --rm -p 9757:9756 mini-kali-slim -d # Usar porta diferente
# Problemas de OpenRouter
# - Verificar chave API: echo $OPENROUTER_API_KEY
# - Verificar status: https://status.openrouter.ai/
# Problemas de VLLM
curl http://localhost:8000/v1/models # Verificar se VLLM está em execução
# - Verificar memória: free -h
# - Garantir GPU disponível: nvidia-smi
# Respostas lentas
# - Mudar para modelo mais rápido em config.json
# - Verificar recursos do sistema (top, htop)
# Agente preso em loop
# - Reduzir complexidade de tarefa
# - Verificar saída de ferramenta para erros
# - Revisar logs de agente para loops infinitos
# Dependências ausentes
cd blacksmithAI/blacksmithAI
uv sync # Reinstalar
- Código Aberto: GPL-3.0-only (uso comunitário, modificação, redistribuição)
- Licença Comercial: Disponível para integração de código fechado
- Contato: yohannesgk@kahanlabs.com
