BlacksmithAI

Installation

Prerequisites

• Linux, macOS, o Windows con WSL2
• Docker 20.10+ e Docker Compose
• Python 3.12+
• Node.js 18+ (per Web UI)
• 4GB+ RAM (8GB consigliato)

Install uv (Python Package Manager)

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

# Verify installation
uv --version

Install Docker

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

# macOS
brew install --cask docker

# Verify
docker --version && docker compose version

Install Node.js & pnpm (Web UI only)

# 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

# Install pnpm
npm install -g pnpm
# or
corepack enable && corepack prepare pnpm@latest --activate

Clone & Setup BlacksmithAI

# Clone repository
git clone https://github.com/yohannesgk/blacksmith.git
cd blacksmith

# Install Python dependencies
cd blacksmithAI/blacksmithAI
uv sync

# Build mini-kali Docker image
docker compose up -d

# Optional: Install frontend dependencies
cd ../frontend && pnpm install

Configuration

Environment Setup

# Copy environment template
cp blacksmithAI/.env.example blacksmithAI/.env

# Edit .env file
nano blacksmithAI/.env

OpenRouter Configuration

# Add to .env
OPENROUTER_API_KEY=your-openrouter-api-key-here

VLLM Configuration (Local LLM)

# Install VLLM
cd blacksmithAI/blacksmithAI
uv add vllm huggingface_hub

# Start VLLM server
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
  --host 0.0.0.0 \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.75

LLM Provider Configuration

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

Custom Provider Setup

# Add to config.json providers section
"openai": {
  "base_url": "https://api.openai.com/v1/chat/completions",
  "default_model": "gpt-4-turbo",
  "default_embedding_model": "text-embedding-3-small"
}

# Add to .env
OPENAI_API_KEY=your-openai-key

# Update defaults
"defaults": { "provider": "openai" }

Basic Usage

CLI Mode (Terminal Interface)

# Terminal 1: Start mini-kali container
cd blacksmithAI/blacksmithAI
docker compose up -d

# Terminal 2: Run BlacksmithAI CLI
cd blacksmithAI/blacksmithAI
uv run main.py

# Or use Makefile shortcut
make start-cli

Web UI Mode (3 Terminals Required)

# Terminal 1: Start mini-kali Docker container
cd blacksmithAI/blacksmithAI
docker compose up -d

# Terminal 2: Start frontend (from blacksmithAI/frontend directory)
pnpm build && pnpm start

# Terminal 3: Start LangGraph dev server (from blacksmithAI/blacksmithAI)
uv run langgraph dev

# Access at http://localhost:3000

Docker Management

# Start container
docker compose up -d

# View logs
docker logs mini-kali-slim

# Stop container
docker compose down

# Restart container
docker compose restart

# Remove all containers
docker compose down -v

Agent Architecture

Orchestrator Agent

• Ruolo: Comando centrale e controllo
• Funzione: Pianificazione missione, delegazione compiti, generazione rapporti
• Strumenti disponibili: Strumenti di pianificazione, strumenti per il filesystem

Recon Agent (Attack Surface Mapping)

• Scopo: Raccolta informazioni passiva e attiva
• Strumenti: assetfinder, subfinder, whois, dig, nslookup, hping3, dnsrecon
• Output: Record DNS, sottodomini, topologia di rete

Scan/Enumeration Agent (Deep Inspection)

• Scopo: Enumerazione utenti, probe API, rilevamento versioni
• Strumenti: nmap, masscan, enum4linux-ng, nikto, whatweb, fingerprintx, gobuster, wpscan
• Output: Porte aperte, servizi, tecnologie, endpoint

Vulnerability Analysis Agent (Risk Assessment)

• Scopo: Mappare servizi a CVE, prioritizzare rischi
• Strumenti: nuclei, sslscan
• Output: Elenco vulnerabilità con punteggi di gravità e sfruttabilità

Exploitation Agent (PoC Execution)

• Scopo: Validare vulnerabilità con exploit controllati
• Strumenti: sqlmap, hydra, medusa, ncrack, script personalizzati (Python/Go/Perl/Ruby)
• Output: Prova di compromissione con prove

Post-Exploitation Agent (Impact Assessment)

• Scopo: Valutare il raggio di blast e le opportunità di pivot
• Strumenti: netcat, socat, ssh tunneling, impacket
• Output: Percorsi di movimento laterale, inventario credenziali, impatto aziendale

Scan Modes & Workflows

Quick Reconnaissance

# Sequenza tipica del workflow
1. Target specification (domain/IP)
2. Orchestrator initiates recon phase
3. Recon Agent discovers: subdomains, DNS records, mail servers
4. Results fed to Scan/Enum agent

Full Penetration Test

# Workflow di valutazione completa
Orchestrator (planning)
  ↓
Recon Agent (attack surface) → output: services & technologies
  ↓
Scan/Enum Agent (deep inspection) → output: ports & versions
  ↓
Vuln Analysis Agent (risk mapping) → output: CVE list with scores
  ↓
Exploit Agent (PoC validation) → output: working exploits
  ↓
Post-Exploit Agent (impact) → output: lateral movement paths
  ↓
Orchestrator (final report with remediation)

Vulnerability Assessment Only

# Target identified services directly to vuln analysis
1. Provide service information (version, port)
2. Vuln Analysis Agent maps to CVEs
3. Exploit Agent tests high-priority vulnerabilities

Tools Reference

Reconnaissance Tools

Tool	Command	Purpose
assetfinder	assetfinder target.com	Subdomain discovery
subfinder	subfinder -d target.com	Subdomain enumeration
whois	whois target.com	Domain info lookup
dig	dig target.com	DNS record queries
dnsrecon	dnsrecon -d target.com	DNS enumeration
hping3	hping3 -p 80 target.com	Network scanning

Scanning & Enumeration

Tool	Command	Purpose
nmap	nmap -sV target.com	Port scanning & version detection
masscan	masscan 0.0.0.0/0 -p80,443	High-speed port scanning
nikto	nikto -h target.com	Web server vulnerability scanning
gobuster	gobuster dir -u http://target.com -w wordlist.txt	Directory/DNS brute-forcing
wpscan	wpscan --url target.com	WordPress vulnerability scanning
whatweb	whatweb target.com	Web technology identification

Vulnerability Analysis

Tool	Command	Purpose
nuclei	nuclei -target target.com	Fast vulnerability scanning
sslscan	sslscan target.com:443	SSL/TLS configuration analysis

Exploitation Tools

Tool	Purpose
sqlmap	Automated SQL injection testing
hydra	Password brute-forcing
medusa	Parallel network login auditing
ncrack	Network authentication cracking
Custom Scripts	Python/Go/Perl/Ruby exploit development

Post-Exploitation

Tool	Purpose
netcat	Network debugging & data transfer
socat	Multi-purpose relay
ssh -D	SOCKS proxy tunneling for pivoting
impacket	Windows protocol tools (psexec, secretsdump)

Output & Reporting

Report Generation

# Orchestrator generates structured reports containing:
- Executive Summary
- Findings with severity ratings
- Evidence and proof-of-concept details
- Affected systems and services
- Remediation guidance
- Business impact assessment

Report Structure

{
  "mission_name": "Penetration Test - Example Corp",
  "target": "example.com",
  "findings": [
    {
      "vulnerability": "SQL Injection in login form",
      "severity": "CRITICAL",
      "affected_service": "Web Application v2.1",
      "evidence": "SELECT version() returned database version",
      "remediation": "Use prepared statements, input validation"
    }
  ],
  "timeline": "2025-03-10T14:30:00Z",
  "tested_systems": ["web-server", "api-gateway", "database"]
}

Advanced Configuration

Adding Custom LLM Providers

{
  "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 with Different Models

# Small model (7B) - faster, less memory
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
  --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.75

# Large model (123B) - more capable
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
  --host 0.0.0.0 --port 8000 --max-model-len 8192

# Custom model from HuggingFace
uv run hf auth login  # Login to HF first
vllm serve meta-llama/Llama-2-7b-chat-hf \
  --host 0.0.0.0 --port 8000

Makefile Commands

# Setup & Installation
make help              # Show all commands
make setup            # Complete initial setup
make install          # Python dependencies only
make frontend-install # Frontend dependencies

# Docker Management
make docker-build     # Build mini-kali image
make docker-up        # Start container
make docker-down      # Stop container
make docker-logs      # View logs

# VLLM Local LLM
make vllm-install     # Install VLLM
make vllm-serve       # Start VLLM (123B)
make vllm-serve-small # Start VLLM (7B)

# Running BlacksmithAI
make start-cli        # CLI mode
make start-ui         # Web UI (shows setup)
make start-all        # Quick start CLI

# Utilities
make status           # Docker container status
make check-deps       # Verify dependencies
make check-config     # Verify configuration
make clean            # Clean up containers
make stop             # Stop all services

Integration with Existing Tools

Using BlacksmithAI with OSINT Tools

# Collect data with external tools
assetfinder -subs-only target.com > subdomains.txt

# Feed into BlacksmithAI
# Agents will perform targeted scans on discovered subdomains

Integration Points

• Nmap output → Fed to Vuln Analysis for service mapping
• Subdomain lists → Targeted scanning by Scan/Enum agent
• API endpoints → Direct vulnerability testing
• Authentication systems → Brute-force & exploitation attempts

Custom Script Integration

# Write custom exploitation scripts in agent directories
# Agents can execute Python/Go/Perl/Ruby scripts
# Example: Custom SQL injection payload
cat > custom_exploit.py << 'EOF'
import sys
target = sys.argv[1]
# Custom exploitation logic
EOF

# Agents invoke: python custom_exploit.py target.com

Best Practices

Pre-Assessment Planning

# Define scope in writing
- Target list (domains/IPs)
- Testing timeframe
- Authorized systems & attack vectors
- Reporting requirements
- Sensitive data handling

# Validate legal authorization
- Written permission from client/owner
- Rules of engagement (RoE)
- NDA and confidentiality agreements

Safe Execution

# Recommendations
1. Use isolated test environments when possible
2. Start with reconnaissance only
3. Test vulnerabilities sequentially, not in parallel
4. Avoid destructive payloads without explicit approval
5. Monitor system behavior during exploitation
6. Maintain detailed logs of all activities

Report Quality

# Comprehensive findings should include:
- Clear vulnerability description
- CVSS/severity scoring
- Proof-of-concept evidence
- Affected services and versions
- Business impact assessment
- Prioritized remediation steps
- Timeline of exploitation

LLM Selection

# Model choice affects results:
- Faster models: Quick reconnaissance, basic scanning
- Larger models: Complex analysis, better decision-making
- Local VLLM: Privacy-focused, no API dependencies
- OpenRouter: Cost-effective, multiple model options

# Recommendation: Use Sonnet/GPT-4 for complex assessment

Legal & Ethical Considerations

Authorization Requirements

• Ottenere sempre il permesso scritto prima del test
• Definire chiaramente l’ambito nelle regole di impegno
• Testare solo sistemi di cui sei proprietario o per cui hai autorizzazione scritta esplicita
• La violazione di leggi (CFAA, GDPR, ecc.) può portare a responsabilità civile/penale

Responsible Disclosure

# After testing:
1. Document all findings with severity
2. Notify system owner of vulnerabilities
3. Allow reasonable time for patching (typically 90 days)
4. Maintain confidentiality of vulnerability details
5. Report to vendors if third-party products are affected

Data Protection

• Ridurre al minimo l’estrazione di dati durante il test
• Archiviare in sicurezza tutti i rapporti e le prove
• Usare la crittografia per i risultati sensibili
• Rispettare le normative sulla protezione dei dati (GDPR, HIPAA, ecc.)
• Eliminare i dati dopo il completamento dell’impegno

Troubleshooting

Docker Issues

# Container won't start
docker ps  # Check if running
docker logs mini-kali-slim  # View errors

# Port conflicts
lsof -i :9756  # Check port usage
docker run -i --rm -p 9757:9756 mini-kali-slim -d  # Use different port

LLM Provider Errors

# OpenRouter issues
# - Verify API key: echo $OPENROUTER_API_KEY
# - Check status: https://status.openrouter.ai/

# VLLM issues
curl http://localhost:8000/v1/models  # Verify VLLM running
# - Check memory: free -h
# - Ensure GPU available: nvidia-smi

Agent Performance

# Slow responses
# - Switch to faster model in config.json
# - Check system resources (top, htop)

# Agent stuck in loop
# - Reduce task complexity
# - Check tool output for errors
# - Review agent logs for infinite loops

# Dependencies missing
cd blacksmithAI/blacksmithAI
uv sync  # Reinstall

Resources

• GitHub: https://github.com/yohannesgk/blacksmith
• Hosted Version: https://bs.kahanlabs.com
• Discord Community: https://discord.gg/y9Rfag3cVk
• Tools Documentation: blacksmithAI/tools.md
• Agent Documentation: blacksmithAI/agents/tools_doc/

License

• Open Source: GPL-3.0-only (community use, modification, redistribution)
• Commercial License: Available for closed-source integration
• Contact: yohannesgk@kahanlabs.com