BlacksmithAI

Instalação

Pré-requisitos

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)

Instalar uv (Gerenciador de Pacotes Python)

# macOS & Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verificar instalação
uv --version

Instalar Docker

# Ubuntu/Debian
sudo apt update && sudo apt install -y docker.io docker-compose

# macOS
brew install --cask docker

# Verificar
docker --version && docker compose version

Instalar Node.js & pnpm (apenas Web UI)

# 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 e Configurar BlacksmithAI

# 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

Configuração

Configuração de Ambiente

# Copiar modelo de ambiente
cp blacksmithAI/.env.example blacksmithAI/.env

# Editar arquivo .env
nano blacksmithAI/.env

Configuração de OpenRouter

# Adicionar a .env
OPENROUTER_API_KEY=your-openrouter-api-key-here

Configuração de VLLM (LLM Local)

# 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

Configuração do Provedor LLM

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

Configuração do Provedor Personalizado

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

Uso Básico

Modo CLI (Interface de Terminal)

# 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

Modo Web UI (3 Terminais Necessários)

# 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

Gerenciamento de Docker

# 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

Arquitetura do Agente

Agente Orquestrador

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

Agente Recon (Mapeamento de Superfície de Ataque)

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

Agente de Varredura/Enumeração (Inspeção Profunda)

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

Agente de Análise de Vulnerabilidades (Avaliação de Risco)

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

Agente de Exploração (Execução de PoC)

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

Agente de Pós-Exploração (Avaliação de Impacto)

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

Modos de Varredura e Fluxos de Trabalho

Reconhecimento Rápido

# 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

Teste de Penetração Completo

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

Apenas Avaliação de Vulnerabilidade

# 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

Referência de Ferramentas

Ferramentas de Reconhecimento

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

Varredura & Enumeração

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

Análise de Vulnerabilidade

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

Ferramentas de Exploração

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

Pós-Exploração

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)

Saída & Relatório

Geração de Relatório

# 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

Estrutura do Relatório

{
  "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"]
}

Configuração Avançada

Adicionando Provedores LLM Personalizados

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

VLLM com Diferentes Modelos

# 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

Comandos do Makefile

# 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

Integração com Ferramentas Existentes

Usando BlacksmithAI com Ferramentas OSINT

# Coletar dados com ferramentas externas
assetfinder -subs-only target.com > subdomains.txt

# Alimentar em BlacksmithAI
# Agentes executarão scans direcionados em subdomínios descobertos

Pontos de Integração

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

Integração de Script Personalizado

# 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

Melhores Práticas

Planejamento de Pré-Avaliação

# 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

Execução Segura

# 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

Qualidade de Relatório

# 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

Seleção de LLM

# 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

Considerações Legais e Éticas

Requisitos de Autorização

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

Divulgação Responsável

# 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

Proteção de Dados

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

Troubleshooting

Problemas de Docker

# 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

Erros do Provedor LLM

# 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

Desempenho do Agente

# 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

Recursos

GitHub: https://github.com/yohannesgk/blacksmith
Versão Hospedada: https://bs.kahanlabs.com
Comunidade Discord: https://discord.gg/y9Rfag3cVk
Documentação de Ferramentas: blacksmithAI/tools.md
Documentação de Agentes: blacksmithAI/agents/tools_doc/

Licença

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