### 2단계: Python 환경 설정

**Linux/macOS:**```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .

### Step 3: AI 공급자 구성

Guardian은 여러 AI 공급자를 지원합니다. `config/guardian.yaml`에서 원하는 공급자를 구성하십시오:```yaml
# config/guardian.yaml
ai:
  # Choose your provider: openai, claude, gemini, openrouter, or requesty
  provider: openai
  
  # OpenAI Configuration (recommended)
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # Or set OPENAI_API_KEY env var
  
  # Claude Configuration
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # Or set ANTHROPIC_API_KEY env var
  
  # Gemini Configuration
  gemini:
    model: gemini-2.5-pro
    api_key: null  # Or set GOOGLE_API_KEY env var
  
  # OpenRouter Configuration
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: null  # Or set OPENROUTER_API_KEY env var

  # Requesty Configuration (OpenAI-compatible gateway)
  requesty:
    model: openai/gpt-4o-mini
    api_key: null  # Or set REQUESTY_API_KEY env var

### 단계 4: 구성 초기화```bash
# Verify installation
python -m cli.main --help

# Check AI provider status
python -m cli.main models

### 사용 예시 시나리오

#### 1. 빠른 웹 애플리케이션 펜 테스트```bash
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

#### 3. 매개변수를 사용한 사용자 정의 워크플로우```bash
# Run with workflow-specific parameters
# Parameters in workflow YAML override config defaults
python -m cli.main workflow run --name web_pentest --target example.com

#### 5. AI 제공자 전환```bash
# Use OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

# Use Claude
python -m cli.main workflow run --name web_pentest --target example.com --provider claude

# Use Gemini
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini

# Local Ollama (no cloud)
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama

# Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, Groq)
python -m cli.main workflow run --name web_pentest --target example.com --provider openai_compatible

`config/guardian.yaml`에서 분석가 근거를 활성화하십시오:```yaml
rag:
  enabled: true
  top_k: 5

세 가지 역할(공격 팀, 방어 팀, 심판)은 모호한 결과에 대해서만 토론합니다 — 확실한 판결은 토론을 건너뛰어 토큰 비용을 제한합니다.

#### 8. 시각적 분류 (vision-LLM)```bash
# Captures full-page screenshots and feeds them to a vision-capable provider
python -m cli.main workflow run --name web_visual_pentest --target https://example.com --provider openai

#### 10. 텔레메트리 + 학습된 랭커 (오프라인)```bash
# Anonymise sessions into JSONL (no raw targets, no commands, no secrets)
python -m cli.main telemetry export ./reports --out telemetry.jsonl

# Train the offline tool ranker
python -m cli.main telemetry train telemetry.jsonl

# Inspect what the ranker learned
python -m cli.main telemetry status

> **Windows 사용자**: `guardian` 대신 `python -m cli.main`을 사용하십시오

---

## 🔧 설정

### 전체 설정 참조

`config/guardian.yaml`을 편집하여 Guardian의 동작을 사용자 정의하십시오.```yaml
# AI Configuration
ai:
  provider: openai  # openai, claude, gemini, openrouter, requesty
  
  openai:
    model: gpt-4o
    api_key: sk-your-key  # Or use OPENAI_API_KEY env var
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null
  
  gemini:
    model: gemini-2.5-pro
    api_key: null
  
  temperature: 0.2
  max_tokens: 8000

# Penetration Testing Settings
pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  max_parallel_tools: 3        # Concurrent tool execution
  max_depth: 3                 # Maximum scan depth
  tool_timeout: 300            # Tool timeout in seconds

# Output Configuration
output:
  format: markdown             # markdown, html, json
  save_path: ./reports
  include_reasoning: true
  verbosity: normal            # quiet, normal, verbose, debug

# Scope Validation
scope:
  blacklist:                   # Never scan these
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
  require_scope_file: false
  max_targets: 100

# Tool Configuration (defaults)
tools:
  httpx:
    threads: 50
    timeout: 10
    tech_detect: true
  
  nuclei:
    severity: ["critical", "high", "medium"]
    templates_path: ~/nuclei-templates
  
  nmap:
    default_args: "-sV -sC"
    timing: T4

**매개변수 우선순위:**
- 워크플로우 파라미터는 구성 파라미터를 **재정의**합니다
- 구성 파라미터는 도구 기본값을 **재정의**합니다
- 자체 포함된 재사용 가능한 워크플로우

---

## 📖 문서

### 사용자 가이드
- **[빠른 시작 가이드](https://github.com/zakirkun/guardian-cli/blob/HEAD/QUICKSTART.md)** - 5분 안에 시작하고 실행하기
- **[명령어 참조](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)** - 모든 명령어에 대한 자세한 문서
- **[구성 가이드](https://github.com/zakirkun/guardian-cli/blob/HEAD/config/guardian.yaml)** - 전체 구성 참조
- **[워크플로우 가이드](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - 사용자 정의 워크플로우 만들기
- **[평가 가이드](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/EVAL_GUIDE.md)** - 평가 도구 실행 및 확장
- **[플러그인 가이드](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/PLUGIN_GUIDE.md)** - 타사 제공업체 및 도구 배포
- **[변경 로그](https://github.com/zakirkun/guardian-cli/blob/HEAD/CHANGELOG.md)** - 버전 기록 및 마이그레이션 참고 사항

### 개발자 가이드
- **[사용자 정의 도구 만들기](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - 나만의 도구 통합 구축
- **[워크플로우 개발](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - 사용자 정의 테스트 워크플로우 만들기
- **[사용 가능한 도구](https://github.com/zakirkun/guardian-cli/blob/HEAD/tools/README.md)** - 통합 도구 개요

### 아키텍처 개요```
Guardian Architecture:
┌─────────────────────────────────────────┐
│         AI Provider Layer               │
│  (OpenAI, Claude, Gemini, OpenRouter,   │
│   Requesty)                             │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│       Multi-Agent System                │
│  Planner → Tool Agent → Analyst →      │
│            Reporter                      │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Workflow Engine                    │
│  - Parameter Priority                   │
│  - Evidence Capture                     │
│  - Session Management                   │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Tool Integration Layer             │
│  (19 Security Tools)                    │
└─────────────────────────────────────────┘

---

## 🆕 최신 업데이트

### 버전 4.0.0 — 신규 연구개발 + 적용 범위 확장

**트랙 A — AI/에이전트 연구개발 (7개 항목)**

| ID | 항목 | 주요 내용 |
|---|---|---|
| A1 | RAG 지식 베이스 | `core/knowledge_base.py` SQLite + FTS5 + 선택적 임베딩; `kb_references` 슬롯을 통한 분석가 근거 설정; `guardian kb {seed,update,query,status}` |
| A2 | 다중 에이전트 토론 분류 | MEDIUM-fp 결과에 대해서만 Red/Blue/Judge; 새로운 분석 단계 유형 `agent: debate` |
| A3 | Vision-LLM 스크린샷 분석 | `tools/playwright_screenshot.py` + `core/agents/visual_triage.py`; OpenAI + Claude `generate_with_images` |
| A4 | 플러그인 계약 + 로컬 제공자 | 제공자 및 도구에 대한 엔트리 포인트 검색; **Ollama** + **OpenAI 호환** 제공자 제공 |
| A5 | 학습된 도구 선택 (오프라인) | `core/learners/tool_ranker.py` + `core/telemetry.py`; `ai.use_learned_ranker: true`를 통한 선택적 사용 |
| A6 | 평가 하네스 | `evals/{__init__,scoring,fixtures_loader,test_*}.py` + 골든 픽스처; 3단계 (파서, 워크플로우, 에이전트 근거) |
| A7 | 판단 모델 업그레이드 | `BaseAgent.think_deeply(judge_model=...)` 스왑 및 복원; ~10x 비용 절감을 위한 기록 기반 판단 |

**트랙 B — 도구 적용 범위 확장 (7개 항목)**

| ID | 카테고리 | 추가된 도구 |
|---|---|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | 모바일 안드로이드 | mobsf, apkleaks, objection |
| B10 | API 퍼저 | schemathesis, restler, cariddi |
| B11 | SAST + 시크릿 | semgrep, trufflehog, dependency-check |
| B12 | LLM 레드팀 | garak, pyrit, prompt_fuzz |
| B13 | Burp/ZAP 브리지 | zap, burp |
| B14 | 출력 내보내기 | SARIF v2.1.0, DefectDojo, Slack |

**품질 기준:**
- 296개 테스트 통과 (v3 기준 153개 대비 +93%)
- 모든 v3 강화 유지: 프롬프트 인젝션 구분자, 키 스크럽, DNS 확인 범위, 원자적 체크포인트, 로그 로테이션, 지연 도구 로딩
- `guardian --help` 시작 시간이 50개 도구에도 불구하고 500ms 미만 유지
- 새 CLI 표면: `guardian kb`, `guardian telemetry`
- 8개의 새로운 워크플로우 제공: `web_pentest_with_debate`, `web_visual_pentest`, `ad_assessment`, `mobile_android`, `llm_redteam`, `sast_review`, `api_pentest_v2`, 기존 v3 워크플로우 포함

### 버전 3.0.0 — 강화 + 엔진 v2

- 모든 도구 출력에 프롬프트 인젝션 구분자 (`<UNTRUSTED_TOOL_OUTPUT>`) 적용
- DAG 스케줄러, Pydantic 스키마, 원자적 체크포인트, `--resume`
- 11개의 새 래퍼 (클라우드/컨테이너/SBOM/GraphQL/JWT/OSINT)
- CVSS v3.1 재계산 + 드리프트 탐지
- 로그 로테이션, 쓰기 시 키 스크럽
- 활성+ 도구에 대한 확인 게이트 연결

### 버전 2.0.0

- 다중 제공자 AI (OpenAI, Claude, Gemini, OpenRouter, Requesty)
- `execution_id`를 통한 증거 연결
- 워크플로우 파라미터 우선순위 시스템

---

## 🤝 기여하기

기여를 환영합니다! 방법은 다음과 같습니다:

### 개발 환경 설정```bash
# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

**AI 제공자 오류**```bash
# Verify API key is set
python -m cli.main models

# Check provider configuration
cat config/guardian.yaml | grep -A 5 "ai:"

**워크플로우가 로드되지 않음**```bash
# Check workflow file exists
ls workflows/web_pentest.yaml

# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"

더 많은 도움이 필요하시면, [이슈를 열어주세요](https://github.com/zakirkun/guardian-cli/issues).

---

## 📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 [LICENSE](https://github.com/zakirkun/guardian-cli/blob/HEAD/LICENSE) 파일을 참조하세요.

---

## 🙏 감사의 말

- **OpenAI** - GPT-4 기능
- **Anthropic** - Claude AI
- **Google** - Gemini AI
- **LangChain** - AI 오케스트레이션 프레임워크
- **ProjectDiscovery** - 오픈소스 보안 도구 (httpx, subfinder, nuclei)
- **Nmap** - 네트워크 탐색 및 보안 감사
- **보안 커뮤니티** - 도구 개발자 및 연구자

---

## 📞 지원 및 연락처

- **GitHub 이슈**: [버그 신고 또는 기능 요청](https://github.com/zakirkun/guardian-cli/issues)
- **토론**: [커뮤니티 토론 참여](https://github.com/zakirkun/guardian-cli/discussions)
- **문서**: [문서 읽기](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)
- **보안**: 취약점은 [email protected]으로 개인적으로 보고해 주세요.

---

## 🌟 스타 기록

<a href="https://github.com/zakirkun/guardian-cli/stargazers">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date" />
    스타 기록 차트
  </picture>
</a>

---
---

<div align="center">

**Guardian** - 지능적이고 윤리적인 자동화된 침투 테스트

보안 커뮤니티가 ❤️로 만들었습니다

[⬆ 맨 위로](#-guardian)

</div>