BlacksmithAI

Installation

Prerequisites

• Linux, macOS, or Windows with WSL2
• Docker 20.10+ and Docker Compose
• Python 3.12+
• Node.js 18+ (for Web UI)
• 4GB+ RAM (8GB recommended)

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

Configuration des fournisseurs LLM

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

Configuration des fournisseurs personnalisés

# 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

Mode UI Web (3 terminaux requis)

# 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

Gestion Docker

# 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

• Role: Central command and control
• Function: Mission planning, task delegation, report generation
• Available Tools: Planning tools, filesystem tools

Recon Agent (Attack Surface Mapping)

• Purpose: Passive & active information gathering
• Tools: assetfinder, subfinder, whois, dig, nslookup, hping3, dnsrecon
• Output: DNS records, subdomains, network topology

Scan/Enumeration Agent (Deep Inspection)

• Purpose: User enumeration, API probing, version discovery
• Tools: nmap, masscan, enum4linux-ng, nikto, whatweb, fingerprintx, gobuster, wpscan
• Output: Open ports, services, technologies, endpoints

Vulnerability Analysis Agent (Risk Assessment)

• Purpose: Map services to CVEs, prioritize risks
• Tools: nuclei, sslscan
• Output: Vulnerability list with severity and exploitability scores

Exploitation Agent (PoC Execution)

• Purpose: Validate vulnerabilities with controlled exploits
• Tools: sqlmap, hydra, medusa, ncrack, custom scripts (Python/Go/Perl/Ruby)
• Output: Proof of compromise with evidence

Post-Exploitation Agent (Impact Assessment)

• Purpose: Assess blast radius and pivot opportunities
• Tools: netcat, socat, ssh tunneling, impacket
• Output: Lateral movement paths, credential inventory, business impact

Scan Modes & Workflows

Reconnaissance rapide

# Typical workflow sequence
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

Test de pénétration complet

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

Évaluation des vulnérabilités uniquement

# 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

Outils de reconnaissance

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

Analyse et énumération

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

Analyse des vulnérabilités

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

Outils d’exploitation

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

Génération de rapports

# 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

Structure du rapport

{
  "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 avec différents modèles

# 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

Points d’intégration

• 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

Intégration de scripts personnalisés

# 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

Planification pré-évaluation

# 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

Exécution sécurisée

# 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

Qualité du rapport

# 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

Sélection du modèle LLM

# 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

Exigences d’autorisation

• Always obtain written permission before testing
• Define scope clearly in rules of engagement
• Test only systems you own or have explicit written authorization to test
• Violation of laws (CFAA, GDPR, etc.) can result in civil/criminal liability

Divulgation responsable

# 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

Protection des données

• Minimize data extraction during testing
• Securely store all reports and evidence
• Use encryption for sensitive findings
• Comply with data protection regulations (GDPR, HIPAA, etc.)
• Destroy data after engagement completion

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

Erreurs des fournisseurs LLM

# 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

Performance de l’agent

# 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