zakirkun/guardian-cli

Guardian CLI – Skill-Referenz

1. Projektübersicht

Guardian (v2.0) ist eine Python-3.11+-CLI-Anwendung, die Penetrationstest-Workflows mithilfe eines Multi-Agenten-KI-Systems automatisiert. Es ist ausschließlich für autorisierte Sicherheitsbewertungen konzipiert.

guardian-cli/
├── ai/               # KI-Anbieter-Integrationen & Prompt-Vorlagen
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # CLI-Einstiegspunkt (Typer) & Befehle
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # Multi-Agenten-Orchestrierungs-Engine
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – entscheidet nächsten Testschritt
│   ├── tool_agent.py     # ToolAgent     – wählt Tools aus & führt sie aus
│   ├── analyst_agent.py  # AnalystAgent  – interpretiert Tool-Ausgaben
│   ├── reporter_agent.py # ReporterAgent – erstellt Abschlussberichte
│   ├── memory.py         # PentestMemory, ToolExecution, Finding-Dataclasses
│   └── workflow.py       # WorkflowEngine – Top-Level-Orchestrator
├── tools/            # 19 Sicherheitstool-Wrapper (eine Python-Datei pro Tool)
├── workflows/        # YAML-Workflow-Definitionen (8 integrierte)
├── utils/            # Logger, scope_validator, Hilfsfunktionen
├── config/           # guardian.yaml-Konfigurationsdatei
├── reports/          # Ausgabeverzeichnis für generierte Berichte & Sitzungsstatus
└── docs/             # Anleitungen (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

---

2. Architektur

2.1 Agenten-Pipeline

Zieleingabe
    │
    ▼
WorkflowEngine.run_workflow()  ──oder──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — Strategisches KI-Schlussfolgern
    │
    ├──► ToolAgent.execute_tool()            — Führt das ausgewählte Sicherheitstool aus
    │
    ├──► AnalystAgent.interpret_output()     — Parst & verknüpft Erkenntnisse mit Ausführungen
    │
    └──► ReporterAgent.execute()             — Erstellt Markdown-/HTML-/JSON-Bericht

Jeder Agent erbt von BaseAgent und verwendet ein gemeinsames PentestMemory-Objekt, das Folgendes speichert:

Speicher	Klasse	Zweck
findings	Finding	Entdeckte Schwachstellen
tool_executions	ToolExecution	Vollständiger Befehl + Rohausgabe
completed_actions	list[str]	Phasenfortschrittsverfolgung
current_phase	str	reconnaissance → scanning → analysis → reporting

2.2 KI-Anbieter-Abstraktion

Alle Anbieter implementieren dasselbe BaseProvider-Interface und sind zur Laufzeit austauschbar:

Anbieter	Umgebungsvariable	Standardmodell
openai	OPENAI_API_KEY	gpt-4o
claude	ANTHROPIC_API_KEY	claude-3-5-sonnet-20241022
gemini	GOOGLE_API_KEY	gemini-2.5-pro
openrouter	OPENROUTER_API_KEY	anthropic/claude-3.5-sonnet

Wechseln Sie den Anbieter über config/guardian.yaml oder das CLI-Flag --provider.

---

3. CLI-Befehle

Führen Sie die Befehle mit python -m cli.main <befehl> (oder guardian <befehl> nach der Installation) aus.

Befehl	Zweck
init	Erstellen/Validieren von config/guardian.yaml
scan	Einmaliger Schwachstellenscan eines Ziels
recon	Passive / aktive Aufklärung
analyze	Erneute Analyse einer vorhandenen Sitzung
report	Bericht für eine Sitzung generieren / neu generieren
workflow list	Verfügbare Workflows auflisten
workflow run	Einen benannten Workflow gegen ein Ziel ausführen
ai	KI zu einem Fund oder benutzerdefiniertem Prompt befragen
models	Konfigurierte KI-Anbieter und Modelle auflisten
version	Version anzeigen

Allgemeine Flags

--target <IP/Domain/CIDR>   # Erforderlich für scan/recon/workflow run
--provider <openai|claude|gemini|openrouter>
--name <workflow-name>       # Für workflow run
--format <markdown|html|json>
--session <SESSION_ID>       # Für die Bericht-Neugenerierung

---

4. Workflow-System

4.1 Ausführen eines Workflows

# Verfügbare Workflows auflisten
python -m cli.main workflow list

# Web-Penetrationstest
python -m cli.main workflow run --name web_pentest --target https://target.example.com

# Vollständige Netzwerkbewertung
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Autonomer KI-gesteuerter Pentest
python -m cli.main workflow run --name autonomous --target example.com

4.2 Integrierte Workflows

Datei	Name	Beschreibung
recon.yaml	recon	Passive + aktive Aufklärung
web_pentest.yaml	web_pentest	HTTP-Erkennung, Schwachstellenscan, Bericht
network_pentest.yaml	network	Portscan, Diensterkennung, Analyse
advanced_recon.yaml	advanced_recon	Tiefgehende Subdomain- + DNS-Aufklärung
full_vuln_scan.yaml	full_vuln_scan	Umfassender Schwachstellenscan
wordpress_audit.yaml	wordpress_audit	WordPress-spezifisches Audit
autonomous.yaml	autonomous	KI-entscheidet-alles-Modus

4.3 Workflow-YAML-Schema

name: my_workflow
description: „Kurze Beschreibung“

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # Tool-Name (muss mit dem Wrapper in tools/ übereinstimmen)
    objective: „Beschreiben, wonach gesucht werden soll“
    parameters:             # Überschreibt default-Werte aus config/guardian.yaml
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: „Erkenntnisse korrelieren“

  - name: generate_report
    type: report
    # Format standardmäßig aus config output.format

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

Parameter-Priorität: Workflow-YAML > config/guardian.yaml > Tool-Standardwerte

4.4 Fuzzy-Workflow-Zuordnung

Die Engine löst --name web automatisch in web_pentest.yaml auf, indem sie eine Teilzeichenfolgensuche im Dateinamensstamm durchführt.

---

5. Integrierte Sicherheitstools (19)

Kategorie	Tools
Netzwerk	nmap, masscan
Web-Aufklärung	httpx, whatweb, wafw00f
Subdomain / DNS	subfinder, amass, dnsrecon
Schwachstellen	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
Inhaltserkennung	gobuster, ffuf, arjun
Sicherheitsanalyse	xsstrike, gitleaks, cmseek

Jedes Tool verfügt über einen eigenständigen Python-Wrapper in tools/<toolname>.py, der:

1. Den Shell-Befehl aus den Parametern erstellt
2. Diesen asynchron ausführt (asyncio-Subprozess)
3. {"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float} zurückgibt

Guardian funktioniert mit einer Teilmenge der verfügbaren Tools; die KI passt sich basierend darauf an, was installiert ist.

---

6. Konfiguration (config/guardian.yaml)

Wichtige Abschnitte:

ai:
  provider: openai          # Aktiver Anbieter
  openai:
    model: gpt-4o
    api_key: null            # Oder OPENAI_APIKEY als Umgebungsvariable setzen
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # Destruktive Aktionen deaktivieren
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # Sekunden

output:
  format: markdown           # markdown | html | json
  save_path: ./reports
  verbosity: normal          # quiet | normal | verbose | debug

scope:
  blacklist:                 # Diese nie scannen
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

---

7. Ausgabe & Nachweise

Jede Scan-Sitzung erzeugt:

Datei	Inhalt
reports/report_<SESSION_ID>.md	Vollständiger Penetrationstestbericht
reports/session_<SESSION_ID>.json	Roh-Sitzungsstatus (Erkenntnisse, Ausführungen, Phase)

Die Beweissicherung umfasst:

• Ausführungs-ID, die mit jeder Erkenntnis verknüpft ist (execution_id-Feld auf Finding)
• Vollständige Rohausgabe (bis zu 2000-Zeichen-Auszüge) jeder Tool-Ausführung
• KI-Schlussfolgerungsspur, eingebettet in Berichte (wenn include_reasoning: true)

Berichtsformate werden über den Konfigurationsschlüssel output.format oder das CLI-Flag --format ausgewählt und den Dateiendungen .md, .html, .json zugeordnet.

---

8. Hinzufügen eines neuen Tools

1. Erstellen Sie tools/mytool.py, das von BaseTool erbt (siehe tools/base_tool.py)
2. Implementieren Sie async def run(self, target: str, **kwargs) -> dict; geben Sie das standardmäßige Ergebniswörterbuch zurück
3. Registrieren Sie das Tool in tools/__init__.py
4. Referenzieren Sie es namentlich in jedem Workflow-YAML-Schritt (tool: mytool)

Die vollständige Dokumentation finden Sie in docs/TOOLS_DEVELOPMENT_GUIDE.md.

---

9. Hinzufügen eines neuen KI-Anbieters

1. Erstellen Sie ai/providers/myprovider_provider.py, das von BaseProvider erbt (ai/providers/base_provider.py)
2. Implementieren Sie async def complete(self, messages, system_prompt) -> dict
3. Registrieren Sie es in der Provider-Factory von ai/ai_client.py
4. Fügen Sie den Konfigurationsblock unter ai: in config/guardian.yaml hinzu

---

10. Entwicklung

# Einrichtung
python -m venv venv
.\venv\Scripts\activate        # Windows
pip install -e ".[dev]"

# Ausführung
python -m cli.main --help

# Tests
pytest tests/

# Lint / Format
black .
ruff check .

Kernabhängigkeiten: typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2

---

11. Rechtliches & Ethik

⚠️ Guardian ist ausschließlich für autorisierte Sicherheitstests und zu Bildungszwecken konzipiert.
Sie sind vollständig dafür verantwortlich, vor dem Testen eines Systems eine ausdrückliche schriftliche Genehmigung einzuholen.
Unautorisierter Zugriff ist illegal (CFAA, DSGVO und gleichwertige Gesetze weltweit).