1. Python: uv

• uv este un manager de pachete Python rapid și modern, precum și un instrument de gestionare a mediilor de execuție
• un fel de combinație „turbo” între pip, pipx și virtualenv.

# Se poate instala prin scriptul oficial de instalare
curl -LsSf https://astral.sh/uv/install.sh | sh

Dacă preferați o versiune împachetată în Python:

pip install uv
# sau
pipx install uv

Pentru verificare se poate rula urmatoarea comanda:

uv –version

Nota Bene:

Se recomandă scriptul autonom pentru funcționalitate completă și actualizări automate
Pentru Windows, utilizați PowerShell:

powershell -ExecutionPolicy ByPass -c „irm https://astral.sh/uv/install.ps1 | iex”

2. Docker și Docker Compose

Docker ne permite să containerizăm și să rulăm servicii backend, baze de date etc.

Instalare pe Ubuntu / Debian

sudo apt update
sudo apt install -y docker.io docker-compose

macOS

brew install –cask docker

După instalare, porniți Docker Desktop și verificați:

docker –version
docker compose version

Dacă vedeți afișarea versiunii, sunteți gata de lucru.

Sfat: Pe Linux, s-ar putea să doriți să vă adăugați utilizatorul la grupul docker:

sudo usermod -aG docker $USER
# Apoi reporniți terminalul

3. Node.js 18+

Este utilizat Node.js pentru instrumentele frontend. Este necesară versiunea Node 18+ pentru compatibilitate cu pnpm și cu ecosistemul modern.

Ubuntu / Debian:

# Utilizarea configurării NodeSource (recomandată pentru versiuni precise)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash –
sudo apt install -y nodejs

macOS:

Instalați cu Homebrew:

brew install node@18

Pentru verificare instalare:

node –version
npm –version

4. pnpm (Fast JavaScript Package Manager)

pnpm este recomandat pentru instalări rapide și consecvente, precum și pentru fișiere de blocare previzibile.

Puteți instala folosind una dintre următoarele metode:

Din npm

npm install -g pnpm

Folosind un script independent(npm nu este necesar)

curl -fsSL https://get.pnpm.io/install.sh | sh –

Cu Corepack(manager de instrumente integrat în Node.js)

corepack enable
corepack prepare pnpm@latest –activate

De verificat apoi instalare:

pnpm –version

De verificat si mediul de dezvoltare

Încercați aceste verificări:

uv –version
node –version
pnpm –version
docker –version
docker compose version

Configurarea vLLM

Dacă doriți să utilizați modelele locale vLLM:

Setup LLM:

cd blacksmithAI/blacksmithAI
uv add vllm
uv add huggingface_hub

uv run hf auth login #dacă nu sunteți autentificat

Servire LLM

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

Instalarea propriu-zisă a BlacksmithAI

Pasul 1: Clonați depozitul

git clone https://github.com/yohannesgk/blacksmith.git

Pasul 2: Instalați dependențele Python

# Instalați dependențele folosind uv
cd blacksmithAI/blacksmithAI
uv sync

Pasul 3: Compilați imaginea Docker mini-kali

Containerul mini-kali oferă toate instrumentele de testare de penetrare într-un mediu sigur și izolat.

# porniți-l cu
cd blacksmithAI/blacksmithAI
docker compose up -d

Pasul 4: Instalarea dependențelor frontend(opțional)

Săriți peste acest pas dacă utilizați doar interfața terminalului.

cd blacksmithAI/frontend
pnpm install
cd ../..

Începere rapidă cu Makefile

Pentru o configurare mai simplă, utilizați comenzile Makefile furnizate. Rulați make help pentru a vedea toate comenzile disponibile.
Configurare completă(o singură comandă):

make setup

Această comandă efectuează:

• Instalarea dependențelor Python (make install)
• Crearea imaginii Docker (make docker-build)
• Instalarea dependențelor frontend (make frontend-install)

Configurare inițială

După instalare, configurați-vă mediul:

# 1. Copiați fișierul de exemplu pentru mediu
cp blacksmithAI/.env.example blacksmithAI/.env

# 2. Editați fișierul .env cu cheile API
nano blacksmithAI/.env

# 3. Editați config.json pentru furnizorul dvs. LLM
nano blacksmithAI/config.json

Pentru rularea în modul CLI BlacksmithAI

make start-cli

sau

uv run main.py

Această comandă:

• Pornește containerul Docker mini-kali(O mini instanta Kali Linux într-un container Docker)
• Lansează interfața CLI

Modul interfață web

Interfața web necesită mai multe terminale. Executați aceste comenzi în terminale separate:

# Terminalul 1: Porniți containerul Docker
make docker-up

# Terminalul 2: Porniți frontend-ul
cd frontend && pnpm build && pnpm start

# Terminalul 3: Porniți serverul de dezvoltare LangGraph
cd blacksmithAI && uv run langgraph dev

sau

cd blacksmithAI && uv run langgraph up

Apoi accesați: http://localhost:3000

Pentru VLLM(LLM local)

# Instalați VLLM
make vllm-install

# Porniți serverul VLLM
make vllm-serve
# Sau pentru sisteme mai mici:
make vllm-serve-small

Comenzi disponibile în Makefile:

make help Afișează toate comenzile disponibile
make install Instalează dependențele Python
make setup Finalizează configurarea inițială
make frontend-install Instalează dependențele frontend-ului
make docker-build Creează imaginea Docker pentru mini-kali
make docker-up Pornește containerul Docker
make docker-down Oprește containerul Docker
make docker-logs Vizualizează jurnalele Docker
make vllm-install Instalează VLLM pentru LLM local
make vllm-serve Pornește serverul VLLM (model 123B)
make vllm-serve-small Pornește serverul VLLM (model 7B)
make start-cli Pornește modul CLI
make start-ui Afișează instrucțiunile de configurare a interfeței web
make start-all Pornește rapid modul CLI
make stop Oprește toate serviciile
make clean Curăță containerele Docker
make status Afișează starea containerului Docker
make check-deps Verifică dacă dependențele sunt instalate
make check-config Verifică fișierele de configurare
make quickstart Afișează ghidul de pornire rapidă

Pornire rapidă

# Configurare inițială
make setup
cp blacksmithAI/.env.example blacksmithAI/.env
# Editează fișierul .env cu cheile tale API

# Pornește CLI
make start-cli

# Pornește interfața web(3 terminale)
make docker-up
cd frontend && pnpm build && pnpm start
cd blacksmithAI && uv run langgraph dev

# Oprește totul
make stop

Configurare

Creați un fișier .env pornind de la exemplu:

cp blacksmithAI/.env.example blacksmithAI/.env

Utilizare OpenRouter(furnizor LLM în cloud):

Editați fișierul .env și adăugați cheia API:

OPENROUTER_API_KEY=cheia-API-openrouter-aici

Utilizare VLLM (furnizor LLM local):

Nu sunt necesare variabile de mediu. Asigurați-vă că serverul VLLM rulează:

# Exemplu de pornire a serverului VLLM
vllm serve <numele-modelului> –port 8000

Configurarea aplicației

Editați fișierul blacksmithAI/config.json pentru a configura furnizorii și modelele LLM:

{
„defaults”: {
„provider”: «openrouter», // sau „vllm”, sau personalizat (openai)
},
„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,
„stream_usage”: true,
„max_tokens”: null
},
„default_embedding_model_config”: {
„max_retries”: 3,
„embedding_ctx_length”: 8191
}
},
„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,
„stream_usage”: true,
„max_tokens”: null
},
„default_embedding_model_config”: {
„max_retries”: 3,
„embedding_ctx_length”: 8191
}
}
}
}

Puteți adăuga suport pentru mai mulți furnizori, cum ar fi openai, claude… și mulți alții, prin simpla editare a fișierului config.json și adăugarea cheii API în .env

De exemplu, dacă doriți să adăugați suport pentru openai, puteți adăuga acest lucru la providers în config.json:

 “openai”: {
“base_url”: “….”,
“default_model”: “gpt-5-mini”,
“default_embedding_model”: “text-embedding-3-small”,
“default_model_config”: {
“context_size”: 200000,
“max_retries”: 3,
“stream_usage”: true,
“max_tokens”: null
},
“default_embedding_model_config”: {
“max_retries”: 3,
“embedding_ctx_length”: 8191
}
}

Deoarece numele furnizorului este setat aici la `openai`, trebuie să adăugați OPENAI_API_KEY=**** în fișierul de mediu. Așadar, adăugați numele furnizorului cu majuscule (provider_name) + API_KEY în fișierul de mediu.
Setați noul furnizor ca implicit modificând:

„defaults”: {
„provider”: „openai”
},

Acum totul este configurat pentru openai.

Puteți scala cu ușurință folosind metoda de mai sus și puteți adăuga mai mult suport.
Opțiuni de configurare

• defaults.provider: Furnizorul LLM implicit de utilizat
• base_url: Punctul final API pentru furnizor
• default_model: Identificatorul modelului LLM
• default_embedding_model: Model pentru încorporări(utilizat în baza de date vectorială)
• context_size: Dimensiunea ferestrei de context a modelului selectat (necesară pentru summerizare, pentru a preveni depășirea ferestrei de context)
• max_retries: Numărul de încercări de reîncercare pentru cererile eșuate
• max_tokens: Numărul maxim de tokenuri în răspunsuri (null = valoarea implicită a modelului)

Utilizare

Opțiunea 1: Interfața terminalului(CLI)

Interacționează direct prin terminal, beneficiind de control deplin asupra agentului.

blacksmith_cli

# Pornește containerul Docker mini-kali
docker run -i –rm -p 9756:9756 mini-kali-slim -d

sau

cd blacksmithAI/blacksmithAI
docker compose up -d

# Rulare BlacksmithAI
cd blacksmithAI/blacksmithAI && uv run main.py

sau

cd blacksmithAI && make start-cli

Urmați instrucțiunile afișate pentru a iniția sarcinile de testare de penetrare.\

Opțiunea 2: Interfața web

Interfață

Se poate accesa interfața pentru gestionarea testelor de penetrare.

# Terminal 1: Porniți containerul mini-kali
docker run -i –rm -p 9756:9756 mini-kali-slim -d

sau

cd blacksmithAI/blacksmithAI
docker compose up -d

# Terminalul 2: Porniți interfața frontend
cd blacksmithAI/frontend
pnpm build
pnpm start

# Terminalul 3: Porniți serverul de dezvoltare LangGraph
cd blacksmithAI/blacksmithAI
uv run langgraph dev

Accesați interfața utilizatorului la adresa: http://localhost:3000

Opțiunea 3: Versiunea cloud

Este disponibilă o versiune găzduită pentru testare rapidă, fără configurare locală.

Instrumente și funcționalități

BlacksmithAI oferă acces la instrumente profesionale de testare de penetrare prin intermediul containerului Docker mini-kali. Toate instrumentele sunt concepute pentru execuție neinteractivă, prin stdin/stdout.

Instrumente de recunoaștere

Creează harta suprafeței de atac prin colectarea pasivă și activă de informații:

assetfinder – descoperă subdomeniile și resursele
subfinder – enumerează subdomeniile
whois – oferă informații privind înregistrarea domeniilor
dig – caută înregistrărilor DNS
nslookup – instrument de interogare DNS
hping3 – scanează rețeaua și analiza pachetelor
dnsrecon – enumerare și recunoaștere DNS

Scanare și enumerare

nmap – este cartograful de rețea și scaner de porturi
masscan – este scanerul de porturi de mare viteză
enum4linux-ng – enumerează SMB/Windows
nikto – scanează servere web(identifică potentiale vulnerabilităti)
whatweb – identifică tehnologiile web
fingerprintx – identifică amprentarea serviciilor
gobuster – enumeră directoarele și DNS-ului(dar poate oferi si mini-atacuri)
wpscan – scaner de vulnerabilități WordPress

Analiza vulnerabilităților

nuclei – scaner de vulnerabilități rapid și personalizabil
sslscan – analizator de configurații SSL/TLS si verificare versiune criptare(cifrare)

Instrumente de exploatare

sqlmap –  injectare SQL automatizată
hydra – oferă forțarea parolelor prin metoda brute-force
medusa – auditor paralel de autentificare în rețea
ncrack – oferă spargerea autentificării în rețea
python/go/perl/ruby – scripturi personalizate de exploatare

Post-exploatare

Evaluează impactul și identifică oportunitățile de pivotare după o exploatare reușită

netcat – “debugator” de rețea și transfer de date
socat – reluare multifuncțională
ssh -D – tunelare proxy SOCKS
impacket – asigură manipularea de protocol Windows(psexec, secretsdump)

Utilitare generală

Instrumente de asistență pentru diverse sarcini.

curl Transfer de date cu sintaxă URL
httpie Client HTTP ușor de utilizat
trufflehog Scaner de parole și date de autentificare

Funcționalități viitoare

• Browser web: MCP-Playwright pentru navigare web automatizată
• Interpret de cod: Interpret de cod MCP pentru execuția Python
• Bază de date de exploatări: Integrare cu Exploit-DB sau alți furnizori de scripturi de exploatare
• Instrumente interactive: Suport pentru Metasploit și alte cadre interactive

Fluxul de lucru al agenților

BlacksmithAI urmează o metodologie structurată de testare de penetrare prin executarea coordonată a agenților:

1. Agentul Orchestrator

Rol: Comandant general

Orchestratorul este punctul central de coordonare care:

• Menține planul de misiune la nivel înalt
• Gestionează o listă de sarcini de îndeplinit
• Delegtă sarcinile către subagenți specializați
• Generează rapoarte finale structurate cu constatările, gravitatea, dovezile și îndrumări de remediere

2. Agent de recunoaștere

Rol: Cartografierea suprafeței de atac

Realizează o hartă detaliată a mediului țintă:

• OSINT pasiv: înregistrări DNS, certificate SSL, date WHOIS
• Scanare activă a rețelei: identificarea porturilor și a serviciilor
• Identificarea statck-ului potrivit: identificarea tehnologiilor și a versiunilor

3. Agent de scanare și enumerare

Rol: Inspecție aprofundată

După cartografierea suprafeței de atac, acest agent:

• Efectuează enumerarea utilizatorilor
• Analizează API-urile și punctele finale
• Identifică versiunile și configurările incorecte
• Identifică potențialele puncte de intrare

4. Agent de analiză a vulnerabilităților

Rol: Evaluarea riscurilor

Analizează rezultatele scanării pentru a:

• Corela serviciile cu vulnerabilitățile cunoscute(CVE-uri, defecte logice,bugs)
• Stabil priorități în funcție de impact si posibilitatea de exploatare.
• Genera  rezumate concise ale dovezilor
• Crea  ipoteze de atac

5. Agent de exploatare

Rol: Executarea demonstrării de concept

Validează vulnerabilitățile prin exploatare controlată:

• Execută exploit-uri într-un mod controlat
• Validează impactul fără a provoca daune colaterale
• Furnizează dovezi clare ale compromiterii
• Obține dovezi(de ex., acces la shell, extragerea datelor)

6. Agent post-exploatare

Rol: Evaluarea impactului

După o exploatare reușită:

• Evaluează raza de acțiune a compromiterii
• Identifică căile de pivotare pentru mișcarea laterală
• Descoperă credențialele și mecanismele de autentificare

Vizualizarea workflow-ului(fluxului de lucru)

Orchestrator
↓
Agent de recunoaștere > Harta suprafeței de atac
↓
Agent de scanare/enumerare > Informații detaliate despre servicii
↓
Agent de analiză a vulnerabilităților > Prioritizarea vulnerabilităților
↓
Agent de exploatare > Demonstrare de concept
↓
Agent post-exploatare > Evaluarea impactului
↓
Orchestrator > Raport final

Troubleshooting probleme cu dependinte sau diverse probleme ce pot apărea:

Depanare probleme cu Docker

Containerul nu pornește

# Verificați dacă Docker rulează
docker ps

# Vizualizați jurnalele containerului
docker logs mini-kali-slim

Porturi asignat deja si aflat in conflict

# Verificați ce utilizează portul 9756
lsof -i :9756

# Utilizați un alt port
docker run -i –rm -p 9757:9756 mini-kali-slim -d

Probleme legate de furnizorul LLM

Erori de conexiune OpenRouter

• Verificați cheia API din fișierul .env
• Verificați starea OpenRouter: https://status.openrouter.ai/
• Asigurați-vă că aveți conexiune la internet

Erori de conexiune VLLM

• Verificați dacă serverul VLLM rulează: curl http://localhost:8000/v1/models
• Verificați configurația portului în config.json
• Asigurați-vă că aveți suficientă memorie GPU/memorie pentru VLLM

Probleme legate de frontend

Erori de compilare

# Ștergeți și recompilați
cd blacksmithAI/frontend
rm -rf node_modules .next
pnpm install
pnpm build

Interfața utilizatorului nu se conectează

• Asigurați-vă că serverul de dezvoltare LangGraph rulează
• Verificați dacă există erori în consola browserului
• Verificați dacă portul 3000 nu este ocupat

Probleme legate de performanța agentului

Răspunsuri lente

• Treceți la un model LLM mai rapid
• Verificați resursele sistemului (RAM/CPU)

Agentul s-a blocat într-o buclă

• Reduceți complexitatea sarcinii
• Consultați documentația instrumentului
• Verificați jurnalele agentului pentru a identifica eventualele erori

Erori frecvente

„Module not found”

# Reinstalează dependențele
cd blacksmith/blacksmithAI
uv sync

„Permission denied”

# Corectează permisiunile fișierelor cu
chmod +x blacksmith/blacksmithAI/main.py