zakirkun/guardian-cli

Guardian CLI – Referência da Skill

1. Visão Geral do Projeto

Guardian (v2.0) é uma aplicação CLI em Python 3.11+ que automatiza fluxos de trabalho de teste de penetração usando um sistema multi-agente de IA. É projetado exclusivamente para avaliações de segurança autorizadas.

guardian-cli/
├── ai/               # Integrações com provedores de IA e templates de prompt
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # Ponto de entrada CLI (Typer) e comandos
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # Motor de orquestração multi-agente
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – decide o próximo passo do teste
│   ├── tool_agent.py     # ToolAgent     – seleciona e executa ferramentas
│   ├── analyst_agent.py  # AnalystAgent  – interpreta a saída das ferramentas
│   ├── reporter_agent.py # ReporterAgent – gera relatórios finais
│   ├── memory.py         # PentestMemory, ToolExecution, Finding dataclasses
│   └── workflow.py       # WorkflowEngine – orquestrador de alto nível
├── tools/            # 19 wrappers de ferramentas de segurança (um arquivo Python cada)
├── workflows/        # Definições de workflow em YAML (8 embutidos)
├── utils/            # logger, scope_validator, helpers
├── config/           # Arquivo de configuração guardian.yaml
├── reports/          # Diretório de saída para relatórios gerados e estado da sessão
└── docs/             # Guias (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

---

2. Arquitetura

2.1 Pipeline de Agentes

Entrada do Alvo
    │
    ▼
WorkflowEngine.run_workflow()  ──ou──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — Raciocínio estratégico da IA
    │
    ├──► ToolAgent.execute_tool()            — Executa a ferramenta de segurança escolhida
    │
    ├──► AnalystAgent.interpret_output()     — Analisa e vincula descobertas às execuções
    │
    └──► ReporterAgent.execute()             — Gera relatório markdown / HTML / JSON

Cada agente herda de BaseAgent e usa um objeto PentestMemory compartilhado que armazena:

Armazenamento	Classe	Propósito
findings	Finding	Vulnerabilidades descobertas
tool_executions	ToolExecution	Comando completo + saída bruta
completed_actions	list[str]	Rastreador de progresso da fase
current_phase	str	reconnaissance → scanning → analysis → reporting

2.2 Abstração do Provedor de IA

Todos os provedores implementam a mesma interface BaseProvider, tornando-os intercambiáveis em tempo de execução:

Provedor	Variável de Ambiente	Modelo Padrão
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

Alterne o provedor via config/guardian.yaml ou a flag --provider na CLI.

---

3. Comandos da CLI

Execute com python -m cli.main <comando> (ou guardian <comando> após a instalação).

Comando	Propósito
init	Criar/validar config/guardian.yaml
scan	Varredura de vulnerabilidade única em um alvo
recon	Reconhecimento passivo / ativo
analyze	Reanalisar uma sessão existente
report	Gerar / regenerar um relatório para uma sessão
workflow list	Listar workflows disponíveis
workflow run	Executar um workflow nomeado contra um alvo
ai	Consultar a IA sobre uma descoberta ou prompt personalizado
models	Listar provedores de IA e modelos configurados
version	Mostrar versão

Flags Comuns

--target <IP/domínio/CIDR>   # Obrigatório para scan/recon/workflow run
--provider <openai|claude|gemini|openrouter>
--name <nome-do-workflow>    # Para workflow run
--format <markdown|html|json>
--session <SESSION_ID>       # Para regeneração de relatório

---

4. Sistema de Workflow

4.1 Executando um Workflow

# Listar workflows disponíveis
python -m cli.main workflow list

# Teste de penetração web
python -m cli.main workflow run --name web_pentest --target https://alvo.exemplo.com

# Avaliação completa de rede
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Pentest autônomo orientado por IA
python -m cli.main workflow run --name autonomous --target exemplo.com

4.2 Workflows Embutidos

Arquivo	Nome	Descrição
recon.yaml	recon	Reconhecimento passivo + ativo
web_pentest.yaml	web_pentest	Descoberta HTTP, varredura de vulnerabilidades, relatório
network_pentest.yaml	network	Varredura de portas, detecção de serviços, análise
advanced_recon.yaml	advanced_recon	Enumeração profunda de subdomínios + DNS
full_vuln_scan.yaml	full_vuln_scan	Varredura abrangente de vulnerabilidades
wordpress_audit.yaml	wordpress_audit	Auditoria específica para WordPress
autonomous.yaml	autonomous	Modo onde a IA decide tudo

4.3 Esquema YAML do Workflow

name: meu_workflow
description: "Descrição curta"

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # nome da ferramenta (deve corresponder ao wrapper em tools/)
    objective: "Descrever o que encontrar"
    parameters:             # Substituir padrões de config/guardian.yaml
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: "Correlacionar descobertas"

  - name: generate_report
    type: report
    # format padrão definido em config output.format

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

Prioridade de Parâmetros: Workflow YAML > config/guardian.yaml > Padrões da ferramenta

4.4 Correspondência Fuzzy de Workflow

O motor resolve automaticamente --name web → web_pentest.yaml usando correspondência de substring no nome do arquivo.

---

5. Ferramentas de Segurança Integradas (19)

Categoria	Ferramentas
Rede	nmap, masscan
Reconhecimento Web	httpx, whatweb, wafw00f
Subdomínio / DNS	subfinder, amass, dnsrecon
Vulnerabilidade	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
Descoberta de Conteúdo	gobuster, ffuf, arjun
Análise de Segurança	xsstrike, gitleaks, cmseek

Cada ferramenta possui um wrapper Python autocontido em tools/<nome_da_ferramenta>.py que:

1. Monta o comando shell a partir dos parâmetros
2. Executa de forma assíncrona (subprocesso asyncio)
3. Retorna {"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}

Guardian funciona com um subconjunto de ferramentas disponíveis; a IA se adapta com base no que está instalado.

---

6. Configuração (config/guardian.yaml)

Seções principais:

ai:
  provider: openai          # Provedor ativo
  openai:
    model: gpt-4o
    api_key: null            # Ou defina a variável de ambiente OPENAI_API_KEY
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # Desabilitar ações destrutivas
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # segundos

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

scope:
  blacklist:                 # Nunca escaneie estes
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

---

7. Saída e Evidências

Cada sessão de varredura produz:

Arquivo	Conteúdo
reports/report_<SESSION_ID>.md	Relatório completo de teste de penetração
reports/session_<SESSION_ID>.json	Estado bruto da sessão (descobertas, execuções, fase)

A captura de evidências inclui:

• ID de Execução vinculado a cada descoberta (campo execution_id em Finding)
• Saída bruta completa (trechos de até 2000 caracteres) de cada execução de ferramenta
• Rastro de raciocínio da IA embutido nos relatórios (quando include_reasoning: true)

Os formatos de relatório são selecionados via chave de configuração output.format ou a flag --format da CLI e mapeiam para extensões de arquivo .md, .html, .json.

---

8. Adicionando uma Nova Ferramenta

1. Crie tools/minhaferramenta.py herdando de BaseTool (veja tools/base_tool.py)
2. Implemente async def run(self, target: str, **kwargs) -> dict; retorne o dicionário de resultado padrão
3. Registre a ferramenta em tools/__init__.py
4. Referencie-a pelo nome em qualquer etapa de workflow YAML (tool: minhaferramenta)

Veja docs/TOOLS_DEVELOPMENT_GUIDE.md para documentação completa.

---

9. Adicionando um Novo Provedor de IA

1. Crie ai/providers/meuprovedor_provider.py herdando de BaseProvider (ai/providers/base_provider.py)
2. Implemente async def complete(self, messages, system_prompt) -> dict
3. Registre na fábrica de provedores em ai/ai_client.py
4. Adicione o bloco de configuração em config/guardian.yaml sob ai:

---

10. Desenvolvimento

# Configuração
python -m venv venv
.\venv\Scripts\activate        # Windows
pip install -e ".[dev]"

# Execução
python -m cli.main --help

# Teste
pytest tests/

# Lint / Formatação
black .
ruff check .

Dependências principais: typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2

---

11. Legal e Ética

⚠️ Guardian foi projetado exclusivamente para testes de segurança autorizados e fins educacionais. Você é totalmente responsável por obter permissão explícita por escrito antes de testar qualquer sistema. Acesso não autorizado é ilegal (CFAA, GDPR e leis equivalentes em todo o mundo).