Kali Factory Anleitung

Sicherere host-lokale Steuerungsebene für KI-Agenten, die Zugriff auf Kali Linux OSINT-Tools benötigen.

Dieses Paket spiegelt die Struktur der GPU Factory wider — typisierte Job-Übermittlung mit Bearer-Auth, Ausführung über eine Warteschlange (Worker) und Ausführung von Docker-Containern auf Basis einer Allowlist — jedoch angewendet auf ein anderes Problem: die Bereitstellung von Zugriff auf Kalis Aufklärungs- und Traffic-Analyse-Tools, ohne Agenten eine unauthentifizierte Shell zu geben.

• FastAPI-Steuerungs-API

• Redis-Warteschlange

• RQ-Worker

• Docker-first Container-Ausführung mit einem gehärteten Kali-Image

• Typisierte Jobs (osint, traffic capture, JS analysis, leak hunting) statt roher Shell-Befehle

• Bearer-Token-Authentifizierung

• Lokaler MCP-Server für MCP-fähige Agenten

• Optionaler ChromaDB-Sidecar zur Speicherung von Aufklärungsergebnissen über mehrere Durchläufe hinweg

Warum existiert dies?

Kali liefert Hunderte von Tools aus, von denen viele für legitime Wettbewerbsanalysen und Sicherheitsforschung nützlich sind, während andere für eine agentengesteuerte Automatisierung nicht geeignet sind. Der naive Ansatz — einen Agenten in eine Kali-Shell zu werfen und ihn machen zu lassen — führt zu drei Problemen:

1. Der Agent hat Zugriff auf jedes Tool, einschließlich Exploitation-Frameworks (metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb), die aus einem Automatisierungskontext niemals erreichbar sein sollten.

2. Tool-Aufrufe sind unstrukturierte Shell-Strings, was sowohl anfällig für Argument-Injection-Fehler ist als auch eine saubere Prüfung unmöglich macht.

3. Es gibt kein Ratenlimit, Zeitlimit oder Ausgabebudget für das, was der Agent tun kann — ein einziger fehlerhafter Agent kann ein Ziel überlasten oder die Festplatte füllen.

Dieses Paket löst alle drei Probleme, indem es Kali über eine API für typisierte Jobs bereitstellt, bei der jedes aufrufbare Tool in einem Manifest deklariert ist, jedes Argument durch Pydantic validiert wird, jeder Container-Start durch ein Image-Präfix auf einer Allowlist steht und jeder Aufruf ein Bearer-Token erfordert.

Zentrale Sicherheitseigenschaften

• Kein shell=True

• Kein generischer Endpunkt zum "Ausführen beliebiger Befehle"

• Jobs werden mit expliziten Schemata validiert

• Container-Ausführung ist durch Image-Präfixe auf einer Allowlist beschränkt

• Tool-Ausführung innerhalb des Containers ist durch den Binärnamen auf einer Allowlist beschränkt

• API erfordert ein Bearer-Token

• Worker und API sind separate Prozesse

• Exploitation-/Credential-Cracking-/Wireless-Tools werden beim Image-Build explizit entfernt

• Egress-Logging für jedes Tool, das auf das Netzwerk zugreift

Job-Typen

• kali_probe

  • validiert, dass der Kali-Container erreichbar ist und die Tool-Allowlist intakt ist

• osint_run

  • führt ein typisiertes OSINT-Tool aus der Allowlist (amass, whatweb, gobuster, dnsenum, etc.) mit strukturierten Argumenten aus

• traffic_capture

  • führt mitmdump für eine begrenzte Dauer aus und gibt eine Capture-Datei zurück

• js_analysis

  • führt linkfinder / secretfinder / arjun gegen eine JavaScript-URL aus

• leak_scan

  • führt trufflehog gegen eine GitHub-Organisation / ein Repository auf committete Zugangsdaten aus

• subdomain_enum

  • führt amass enum (nur passive Quellen) gegen eine Zieldomäne aus

• web_fingerprint

  • führt whatweb aus, um den Tech-Stack eines Ziels zu identifizieren

• nuclei_exposures

  • führt nuclei gegen ein Ziel aus, jedoch nur mit der Vorlagen-Untergruppe exposures/

  • cves/, vulnerabilities/, default-logins/, fuzzing/ Vorlagenverzeichnisse sind explizit blockiert

Schnellstart

1. Umgebungsvariablen kopieren:

cp .env.example .env
./scripts/bootstrap-secrets.sh

2. Das API-Token wird gespeichert in:

.secrets/api_token

und .env verweist darauf über KALI_FACTORY_API_TOKEN_FILE.

3. Redis starten:

docker compose up -d redis

4. Kali-Runtime-Image bauen:

docker build -t kali-factory/recon:latest runtimes/kali/

5. Python-Umgebung erstellen:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

6. API ausführen:

./scripts/start-api.sh

7. Worker ausführen:

./scripts/start-worker.sh

8. MCP-Server ausführen:

./scripts/start-mcp.sh

Beispielanfragen

Gesundheitsstatus:

curl http://localhost:8081/health

Kali-Probe:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"kali_probe"}'

Subdomain-Enumeration:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"subdomain_enum",
    "domain":"example.com",
    "max_runtime_sec": 300
  }'

Web-Fingerprint:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"web_fingerprint",
    "url":"https://example.com"
  }'

GitHub-Leak-Scan:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"leak_scan",
    "github_org":"example-org"
  }'

Dateien

• START_HERE_FOR_AGENTS.md — Einstiegsleitfaden für Agenten, die diese Steuerungsebene nutzen

• runtimes/kali/Dockerfile — Kali-Container-Image mit den installierten Allowlist-Tools

• runtimes/kali/tools.json — deklaratives Tool-Manifest (Allowlist + Argument-Vorlagen)

• scripts/bootstrap-secrets.sh — API-Token-Datei erstellen und Berechtigungen setzen

• scripts/start-api.sh — Start-Wrapper für die API

• scripts/start-worker.sh — Start-Wrapper für den Worker

• scripts/start-mcp.sh — Start-Wrapper für den lokalen MCP-Server

• scripts/install-user-services.sh — Installation der systemd-Units auf Benutzerebene

• src/kali_factory/api/ — API-Server (FastAPI)

• src/kali_factory/worker/ — RQ-basierte Job-Ausführung

• src/kali_factory/models/ — Pydantic-Job-Schemata

• src/kali_factory/jobs/ — Handler pro Job-Typ

• src/kali_factory/policy/ — Auth, Durchsetzung der Allowlist, Ratenbegrenzung

• src/kali_factory/mcp/server.py — stdio MCP-Adapter über die lokale Kali Factory API

• compose.yaml — Redis (und optional ChromaDB) Sidecars

• Dockerfile — App-Container für API/Worker

• .env.example — erforderliche Einstellungen

• DEPLOYMENT.md — host-spezifische Ausführungs- und Service-Anleitung

Empfohlene weitere Härtung

• API hinter Tailscale, Caddy oder ein anderes internes Gateway legen

• API-Token rotieren

• Audit-Logging in eine Datei oder SQLite hinzufügen

• Explizite Job-Kontingente und Ratenbegrenzungen pro Tool hinzufügen

• Allowlist pro Ziel hinzufügen (Agenten nur Domains scannen lassen, die Sie besitzen oder für die Sie eine Testgenehmigung haben)

• Egress-Logging auf dem Kali-Container aktivieren, damit jede ausgehende Anfrage erfasst wird

Servicemodell

• kali-factory-api.service sollte dauerhaft laufen

• kali-factory-worker.service sollte dauerhaft laufen

• der MCP-Server sollte nicht als dauerhafter Dienst laufen

• MCP-Clients sollten scripts/start-mcp.sh bei Bedarf über stdio starten

Beziehung zu anderen Factory-Paketen

Die beiden Pakete teilen sich die gleiche architektonische Form (FastAPI + Redis + RQ + Bearer-Auth + typisierte Jobs + Allowlist-Docker-Exec) und sind so konzipiert, dass sie auf demselben Host mit nicht überlappenden Ports koexistieren (8080 für GPU Factory, 8081 für Kali Factory).

Ein zukünftiger parallel-OS-Orchestrator kann Agentenanfragen an die Factory weiterleiten, die der benötigten Laufzeitumgebung entspricht.

Was Kali Factory nicht ist

• Kein Schwachstellenscanner. nuclei ist enthalten, aber auf exposures/-Vorlagen beschränkt. CVE- / Exploit- / Default-Login- / Fuzzing-Vorlagen sind explizit blockiert.

• Kein Exploitation-Framework. Metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb, hydra, medusa, ncrack, nikto, wpscan, responder, impacket, crackmapexec werden beim Build-Zeitpunkt aus dem Runtime-Image entfernt.

• Kein Tool für unautorisierte Tests. Nur gegen Ziele verwenden, die Sie besitzen oder für die Sie eine explizite Testgenehmigung haben. Die API protokolliert jeden Job; Missbrauch liegt in Ihrer Verantwortung.

Lizenz

Apache 2.0 (siehe LICENSE).