Guardian CLI – SKILL 레퍼런스은(는) 무엇을 하나요?

1. 프로젝트 개요

Guardian (v2.0)은 Python 3.11+ 기반의 CLI 애플리케이션으로, 다중 에이전트 AI 시스템을 사용하여 침투 테스트 워크플로우를 자동화합니다. 승인된 보안 평가만을 위해 설계되었습니다.

guardian-cli/
├── ai/               # AI 제공자 통합 및 프롬프트 템플릿
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # CLI 진입점 (Typer) 및 명령어
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # 다중 에이전트 오케스트레이션 엔진
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – 다음 테스트 단계 결정
│   ├── tool_agent.py     # ToolAgent     – 도구 선택 및 실행
│   ├── analyst_agent.py  # AnalystAgent  – 도구 출력 해석
│   ├── reporter_agent.py # ReporterAgent – 최종 보고서 생성
│   ├── memory.py         # PentestMemory, ToolExecution, Finding 데이터클래스
│   └── workflow.py       # WorkflowEngine – 최상위 오케스트레이터
├── tools/            # 19개 보안 도구 래퍼 (각각 하나의 Python 파일)
├── workflows/        # YAML 워크플로우 정의 (8개 내장)
├── utils/            # 로거, 범위 검증기, 헬퍼
├── config/           # guardian.yaml 설정 파일
├── reports/          # 생성된 보고서 및 세션 상태 출력 디렉터리
└── docs/             # 가이드 (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

2. 아키텍처

2.1 에이전트 파이프라인

대상 입력
    │
    ▼
WorkflowEngine.run_workflow()  ──또는──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — 전략적 AI 추론
    │
    ├──► ToolAgent.execute_tool()            — 선택된 보안 도구 실행
    │
    ├──► AnalystAgent.interpret_output()     — 결과를 구문 분석하고 실행에 연결
    │
    └──► ReporterAgent.execute()             — 마크다운 / HTML / JSON 보고서 생성

각 에이전트는 BaseAgent를 상속하며, 다음과 같은 공유 PentestMemory 객체를 사용합니다:

저장소	클래스	목적
`findings`	`Finding`	발견된 취약점
`tool_executions`	`ToolExecution`	전체 명령어 + 원시 출력
`completed_actions`	`list[str]`	단계 진행 추적기
`current_phase`	`str`	정찰 → 스캔 → 분석 → 보고

2.2 AI 제공자 추상화

모든 제공자는 동일한 BaseProvider 인터페이스를 구현하므로 런타임에 상호 교체 가능합니다:

제공자	환경 변수	기본 모델
`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`

config/guardian.yaml 또는 --provider CLI 플래그를 통해 제공자를 전환합니다.

3. CLI 명령어

python -m cli.main <command> (또는 설치 후 guardian <command>)로 실행합니다.

명령어	목적
`init`	`config/guardian.yaml` 생성/검증
`scan`	대상에 대한 일회성 취약점 스캔
`recon`	수동/능동 정찰
`analyze`	기존 세션 재분석
`report`	세션에 대한 보고서 생성/재생성
`workflow list`	사용 가능한 워크플로우 목록
`workflow run`	대상에 대해 명명된 워크플로우 실행
`ai`	발견 내용이나 사용자 정의 프롬프트에 대해 AI에 질의
`models`	구성된 AI 제공자 및 모델 목록
`version`	버전 표시

공통 플래그

--target <IP/도메인/CIDR>   # scan/recon/workflow run에 필수
--provider <openai|claude|gemini|openrouter>
--name <워크플로우 이름>       # workflow run용
--format <markdown|html|json>
--session <SESSION_ID>       # 보고서 재생성용

4. 워크플로우 시스템

4.1 워크플로우 실행

# 사용 가능한 워크플로우 나열
python -m cli.main workflow list

# 웹 침투 테스트
python -m cli.main workflow run --name web_pentest --target https://target.example.com

# 전체 네트워크 평가
python -m cli.main workflow run --name network --target 192.168.1.0/24

# 자율 AI 기반 침투 테스트
python -m cli.main workflow run --name autonomous --target example.com

4.2 내장 워크플로우

파일	이름	설명
`recon.yaml`	recon	수동 + 능동 정찰
`web_pentest.yaml`	web_pentest	HTTP 발견, 취약점 스캔, 보고서
`network_pentest.yaml`	network	포트 스캔, 서비스 탐지, 분석
`advanced_recon.yaml`	advanced_recon	심층 서브도메인 + DNS 열거
`full_vuln_scan.yaml`	full_vuln_scan	포괄적인 취약점 스윕
`wordpress_audit.yaml`	wordpress_audit	WordPress 전용 감사
`autonomous.yaml`	autonomous	AI가 모든 것을 결정하는 모드

4.3 워크플로우 YAML 스키마

name: my_workflow
description: "간단한 설명"

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # 도구 이름 (tools/ 래퍼와 일치해야 함)
    objective: "찾을 내용 설명"
    parameters:             # config/guardian.yaml 기본값 재정의
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: "결과 상관 관계 분석"

  - name: generate_report
    type: report
    # 형식은 config output.format 기본값 사용

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

매개변수 우선 순위: 워크플로우 YAML > config/guardian.yaml > 도구 기본값

4.4 퍼지 워크플로우 매칭

엔진은 --name web을 web_pentest.yaml로 자동 변환합니다. 파일명 스템의 하위 문자열 매칭을 사용합니다.

5. 통합 보안 도구 (19개)

카테고리	도구
네트워크	nmap, masscan
웹 정찰	httpx, whatweb, wafw00f
서브도메인 / DNS	subfinder, amass, dnsrecon
취약점	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
콘텐츠 발견	gobuster, ffuf, arjun
보안 분석	xsstrike, gitleaks, cmseek

각 도구는 tools/<toolname>.py에 자체 포함된 Python 래퍼를 가지며, 다음을 수행합니다:

매개변수에서 셸 명령어를 빌드합니다.
비동기적으로 실행합니다 (asyncio 서브프로세스).
{"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}를 반환합니다.

Guardian은 사용 가능한 도구의 하위 집합과 함께 작동하며, AI는 설치된 도구에 따라 적응합니다.

6. 설정 (`config/guardian.yaml`)

주요 섹션:

ai:
  provider: openai          # 활성 제공자
  openai:
    model: gpt-4o
    api_key: null            # 또는 OPENAI_API_KEY 환경 변수 설정
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # 파괴적 작업 비활성화
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # 초

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

scope:
  blacklist:                 # 이러한 대상은 스캔하지 않음
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

7. 출력 및 증거

모든 스캔 세션은 다음을 생성합니다:

파일	내용
`reports/report_<SESSION_ID>.md`	전체 침투 테스트 보고서
`reports/session_<SESSION_ID>.json`	원시 세션 상태 (발견 내용, 실행, 단계)

증거 캡처에는 다음이 포함됩니다:

모든 발견 내용에 연결된 실행 ID (Finding의 execution_id 필드)
모든 도구 실행의 전체 원시 출력 (최대 2000자 스니펫)
보고서에 포함된 AI 추론 추적 (include_reasoning: true 설정 시)

보고서 형식은 output.format 구성 키 또는 --format CLI 플래그를 통해 선택되며, 파일 확장자 .md, .html, .json에 매핑됩니다.

8. 새 도구 추가

tools/mytool.py를 생성하고 BaseTool 상속 (tools/base_tool.py 참조)
async def run(self, target: str, **kwargs) -> dict 구현; 표준 결과 사전 반환
tools/__init__.py에 도구 등록
모든 워크플로우 YAML 단계에서 이름으로 참조 (tool: mytool)

전체 문서는 docs/TOOLS_DEVELOPMENT_GUIDE.md를 참조하세요.

9. 새 AI 제공자 추가

ai/providers/myprovider_provider.py를 생성하고 BaseProvider 상속 (ai/providers/base_provider.py)
async def complete(self, messages, system_prompt) -> dict 구현
ai/ai_client.py 제공자 팩토리에 등록
config/guardian.yaml의 ai: 아래에 구성 블록 추가

10. 개발

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

# 실행
python -m cli.main --help

# 테스트
pytest tests/

# 린트 / 포맷
black .
ruff check .

핵심 종속성: typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2

11. 법적 고지 및 윤리

⚠️ Guardian은 승인된 보안 테스트 및 교육 목적으로만 설계되었습니다.
시스템 테스트 전에 명시적인 서면 허가를 받는 것은 전적으로 귀하의 책임입니다.
무단 액세스는 불법입니다 (CFAA, GDPR 및 전 세계의 동등한 법률 위반).

Guardian CLI – SKILL 레퍼런스