BlacksmithAI

Installation

Prerequisites

• Linux, macOS, oder Windows mit WSL2
• Docker 20.10+ und Docker Compose
• Python 3.12+
• Node.js 18+ (für Web UI)
• 4GB+ RAM (8GB empfohlen)

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

• Rolle: Zentrales Kommando und Kontrolle
• Funktion: Missionsplanung, Aufgabendelegation, Berichtsgenerierung
• Verfügbare Tools: Planungstools, Dateisystem-Tools

Recon Agent (Attack Surface Mapping)

• Zweck: Passive und aktive Informationsbeschaffung
• Tools: assetfinder, subfinder, whois, dig, nslookup, hping3, dnsrecon
• Ausgabe: DNS-Einträge, Subdomains, Netzwerktopologie

Scan/Enumeration Agent (Deep Inspection)

• Zweck: Benutzerlisten, API-Überprüfung, Versionserkennung
• Tools: nmap, masscan, enum4linux-ng, nikto, whatweb, fingerprintx, gobuster, wpscan
• Ausgabe: Offene Ports, Dienste, Technologien, Endpunkte

Vulnerability Analysis Agent (Risk Assessment)

• Zweck: Dienste zu CVEs abbilden, Risiken priorisieren
• Tools: nuclei, sslscan
• Ausgabe: Schwachstellen-Liste mit Schweregrad und Exploit-Bewertungen

Exploitation Agent (PoC Execution)

• Zweck: Schwachstellen mit kontrollierten Exploits validieren
• Tools: sqlmap, hydra, medusa, ncrack, benutzerdefinierte Skripte (Python/Go/Perl/Ruby)
• Ausgabe: Kompromittierungsbeweis mit Beweisen

Post-Exploitation Agent (Impact Assessment)

• Zweck: Blast-Radius und Pivot-Möglichkeiten bewerten
• Tools: netcat, socat, ssh tunneling, impacket
• Ausgabe: Lateral-Movement-Pfade, Anmeldedaten-Inventar, Geschäftsauswirkungen

Scan Modes & Workflows

Quick Reconnaissance

# Typische Workflow-Sequenz
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

# Kompletter Bewertungs-Workflow
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

• Vor dem Testen immer schriftliche Genehmigung einholen
• Bereich klar in den Einsatzregeln definieren
• Nur Systeme testen, die Sie besitzen oder für die Sie explizite schriftliche Genehmigung haben
• Verstöße gegen Gesetze (CFAA, GDPR, usw.) können zu zivilen/strafrechtlichen Konsequenzen führen

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

• Datenbeschaffung während des Testens minimieren
• Alle Berichte und Beweise sicher speichern
• Verschlüsselung für sensitive Ergebnisse verwenden
• Datenschutzgesetze (GDPR, HIPAA, usw.) einhalten
• Daten nach Engagement-Ende löschen

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