이것은 핵심 주장이며 오늘날 에이전트 손상, 프롬프트 인젝션, 로그 도난, 스킬 유출에 대해 방어 가능합니다. 어떤 것이 보호되고 어떤 것이 보호되지 않는지에 대한 솔직한 구분 — 더 강력한 '호스트 손상 시 아무것도 유출되지 않음' 주장이 도달 가능한 계층을 포함하여 — 에 대해서는 [docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md)를 읽어보세요.

볼트 자체(저장 시 암호화, 암호문 파생 키)는 실제 구성 요소이며 방화벽이 단일 시스템에서 실행될 수 있는 이유입니다. 곧 제공될 [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md) 계층은 추가로 프록시를 기밀 컴퓨팅 엔클레이브로 감싸 완전히 손상된 VPS조차 키를 읽을 수 없도록 합니다.

[![Crates.io](https://img.shields.io/crates/v/wardn.svg)](https://crates.io/crates/wardn)
[![License](https://img.shields.io/crates/l/wardn.svg)](LICENSE)

## 문제

오늘날 모든 AI 에이전트 프레임워크는 API 키를 환경 변수나 `.env` 파일에 저장합니다. 손상된 에이전트, 악성 스킬, 일반적인 스틸러, 또는 LLM 로그에서 `Authorization: Bearer sk-...`를 유출하는 프롬프트 인젝션은 여러분의 자격 증명에 완전히 접근할 수 있습니다.```
~/.env              → OPENAI_KEY=sk-proj-real-key      # plaintext, readable by anyone
agent context       → "Use OPENAI_KEY=sk-proj-real-key" # leaked into LLM context window
agent logs          → Authorization: Bearer sk-proj-... # sitting in log files

## 아키텍처```mermaid
flowchart TB
    subgraph Agent["AI Agent Process"]
        A1["Agent Code"]
        A2["ENV: OPENAI_KEY=wdn_placeholder_a1b2..."]
    end

    subgraph Wardn["wardn daemon · localhost:7777"]
        direction TB
        P["HTTP Proxy"]
        MCP["MCP Server\n(stdio)"]

        subgraph Pipeline["Request Pipeline"]
            direction LR
            S1["Identify\nAgent"] --> S2["Resolve\nPlaceholder"] --> S3["Check\nAuth"] --> S4["Rate\nLimit"] --> S5["Inject\nReal Key"]
        end

        subgraph ResponsePipeline["Response Pipeline"]
            direction RL
            R1["Strip Real\nKeys"] --> R2["Replace with\nPlaceholders"]
        end

        subgraph Vault["Encrypted Vault"]
            V1["AES-256-GCM"]
            V2["Argon2id KDF"]
            V3["Placeholder Map\nper agent × credential"]
        end
    end

    subgraph External["External APIs"]
        E1["api.openai.com"]
        E2["api.anthropic.com"]
        E3["..."]
    end

    A1 -- "placeholder token\nin headers/body" --> P
    A1 -. "MCP: get_credential_ref\nlist_credentials\ncheck_rate_limit" .-> MCP
    MCP -. "placeholder token\n(never real keys)" .-> A1
    P --> Pipeline
    Pipeline --> External
    External --> ResponsePipeline
    ResponsePipeline -- "response with\nplaceholders only" --> A1
    Pipeline <--> Vault
    ResponsePipeline <--> Vault

    style Agent fill:#1a1a2e,stroke:#e94560,color:#fff
    style Wardn fill:#0f3460,stroke:#16213e,color:#fff
    style Pipeline fill:#16213e,stroke:#e94560,color:#fff
    style ResponsePipeline fill:#16213e,stroke:#e94560,color:#fff
    style Vault fill:#1a1a2e,stroke:#00d2ff,color:#fff
    style External fill:#0a0a0a,stroke:#533483,color:#fff

## 데모

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12823/1fa6109ffd855ec98c173c5edd2d7ee77f6b0c918a3cdecb1ea5fbfe8326161d.gif" alt="wardn 데모" width="800">
</p>

## 신뢰 수준, 정직하게

| 계층 | 위치 | 보유 내용 |
|---|---|---|
| **자가 호스팅 (현재)** | 당신의 노트북, VPS, CI | 저장 시 암호화된 볼트, 에이전트에 대한 방화벽 주장. **호스트의 루트에 대해서는 방어하지 않습니다.** |
| **호스팅 (예정)** | wardn 관리 또는 BYO 클라우드 | 기밀 컴퓨팅 엔클레이브 (Nitro / SEV-SNP) + 원격 증명 + 프록시로 암호화 흐름. 실제 "호스트 손상 시 아무것도 유출되지 않음" 주장. |

자가 호스팅 계층은 핵심 주장이며 현재 제공됩니다. 호스팅 계층은 엄격한 업그레이드 경로로서 비용과 운영 복잡성이 수반되며, 그 설계는 [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md)에 있습니다. 적용되는 것과 적용되지 않는 것의 완전하고 정직한 목록:

👉 **[docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md)** — 적용/미적용 표, "소프트웨어 볼트로 호스트 손상을 제거할 수 없다"는 점이 명확히 언급되어 있으며, 업그레이드 경로가 포함되어 있습니다.

## 설치```bash
# Prebuilt binary (Linux/macOS, amd64/arm64), checksum-verified
curl -sSf https://raw.githubusercontent.com/rohansx/wardn/main/install.sh | sh

# or from crates.io
cargo install wardn

# or Homebrew, once the tap is published (see Formula/wardn.rb)
brew install rohansx/wardn/wardn

그렇습니다. 이제 Claude Code는 환경에서 실제 키를 읽는 대신 wardn의 MCP 서버를 사용하여 플레이스홀더 토큰을 가져옵니다.

### 다음에 발생하는 일

1. Claude Code가 `get_credential_ref`를 호출 → `wdn_placeholder_a1b2...`를 가져옵니다 (실제 키가 아님)
2. 에이전트가 플레이스홀더와 함께 wardn 프록시를 통해 요청을 보냅니다
3. 프록시가 플레이스홀더를 실제 키로 교체하여 API로 전달합니다
4. 프록시가 응답에서 실제 키를 제거한 후 에이전트에 반환합니다

실제 키는 에이전트의 메모리, 로그 또는 LLM 컨텍스트 창에 절대 들어가지 않습니다.

## 로컬 대시보드

데몬이 실행되면 (`wardn serve` 또는 `wardn run`에 의해 생성됨), 브라우저에서
**http://127.0.0.1:7777/ui**를 엽니다. 읽기 전용, 로컬 전용 보기:

- **자격 증명** — 모든 저장된 자격 증명과 해당 ACL(허용된 에이전트,
  허용된 도메인, 속도 제한 + 예산 배지)
- **최근 활동** — method, domain, path, status, agent, request_id 및 기록된 비용(`request_completed`,
  `credential_injected`, `rate_limit`, `budget_exceeded`, `loop_detected`,
  `request_error`)을 포함한 최근 50개의 프록시 이벤트
- **예산** — 각 자격 증명의 구성된 예산(max, spent,
  remaining, window, mode)과 50%/80%를 넘으면 경고 → 나쁨으로 변하는 진행 표시줄

2초마다 자동으로 폴링됩니다. 변경 엔드포인트는 없습니다 — 대시보드에서 나가는 유일한
방법은 API 자체(`/api/summary`, `/api/credentials`,
`/api/audit?limit=N`, `/api/budgets`)입니다.```bash
# Static, anonymous, never sees real keys
curl http://127.0.0.1:7777/api/summary | jq

## CLI 참조

### 볼트 관리```bash
wardn vault create                        # create encrypted vault
wardn vault set OPENAI_KEY                # store credential (prompts for value, no echo)
wardn vault get OPENAI_KEY                # get placeholder token (never the real value)
wardn vault get OPENAI_KEY --agent bot    # get placeholder for specific agent
wardn vault list                          # list all credentials
wardn vault rotate OPENAI_KEY             # rotate value, placeholders unchanged
wardn vault remove OPENAI_KEY             # remove credential

# Custom vault path
wardn --vault /path/to/vault.enc vault list

### Claude Code / Cursor 통합```bash
wardn setup claude-code                   # register wardn as MCP server in Claude Code
wardn setup cursor                        # register wardn as MCP server in Cursor

# Or manually:
claude mcp add --transport stdio --scope user wardn -- wardn serve --mcp --agent claude-code

#### 사용 가능한 MCP 도구

| 도구 | 반환하는 내용 | 보안 |
|------|----------------|----------|
| `get_credential_ref` | 자리 표시자 토큰 (`wdn_placeholder_...`) | 실제 값은 절대 반환되지 않음 |
| `list_credentials` | 자격 증명 이름 + 메타데이터 | 에이전트의 액세스 권한에 따라 필터링됨 |
| `check_rate_limit` | 남은 할당량, 재시도 정보 | 읽기 전용 |

### 자격 증명 마이그레이션```bash
wardn migrate --dry-run                             # audit Claude Code dir for exposed keys
wardn migrate --source claude-code                  # scan + migrate to vault
wardn migrate --source open-claw                    # scan OpenClaw config
wardn migrate --source directory --path ./my-proj   # scan any directory

각 임포터는 최초 사용 시 볼트 패스프레이즈를 입력하라는 메시지를 표시하거나(`WARDN_PASSPHRASE`/운영체제 키체인에서 읽어오거나) 합니다. 기존 값은 조용히 덮어써집니다. 임포터는 값 전용이며, 메타데이터(허용된 에이전트/도메인/비율 제한/예산)는 보존됩니다.

### 자동화

CI/스크립트의 경우 `WARDN_PASSPHRASE` 및 `WARDN_VALUE` 환경 변수를 설정하여 대화형 프롬프트를 생략하세요.```bash
WARDN_PASSPHRASE=my-pass wardn vault list
WARDN_PASSPHRASE=my-pass WARDN_VALUE=sk-proj-xxx wardn vault set OPENAI_KEY

### Vault 작업```rust
use wardn::{Vault, config::CredentialConfig};

// Create an encrypted vault
let vault = Vault::create("vault.enc", "my-passphrase")?;

// Store a credential
vault.set_with_config("OPENAI_KEY", "sk-proj-real-key-123", &CredentialConfig {
    allowed_agents: vec!["researcher".into(), "writer".into()],
    allowed_domains: vec!["api.openai.com".into()],
    rate_limit: Some(RateLimitConfig { max_calls: 200, per: TimePeriod::Hour }),
})?;

// Agent gets a placeholder (not the real key)
let placeholder = vault.get_placeholder("OPENAI_KEY", "researcher")?;
// → "wdn_placeholder_a1b2c3d4e5f6g7h8"

// Rotate the real key — all placeholders keep working
vault.rotate("OPENAI_KEY", "sk-proj-new-key-456")?;

### MCP Server```rust
use wardn::mcp::WardenMcpServer;

// Serve over stdio (for Claude Code, Cursor, etc.)
WardenMcpServer::serve_stdio(vault, rate_limiter, "agent-id".into()).await?;

Set `RUST_LOG=wardn=info` (or `debug`/`trace`) to control verbosity. Logs go to stderr, never stdout.

## 구성```toml
[warden]
vault_path = "~/.vibeguard/vault.enc"

[warden.credentials.OPENAI_KEY]
rate_limit = { max_calls = 200, per = "hour" }
allowed_agents = ["researcher", "writer"]
allowed_domains = ["api.openai.com"]

[warden.credentials.ANTHROPIC_KEY]
rate_limit = { max_calls = 100, per = "hour" }
allowed_agents = ["researcher"]
allowed_domains = ["api.anthropic.com"]

## 개발```bash
# Integration tests use a fast (insecure) KDF so the suite runs in
# milliseconds instead of paying the real Argon2id cost per test —
# always pass this feature flag when running tests locally or in CI:
cargo test --features test-fast-kdf

cargo build
cargo clippy --all-targets --features test-fast-kdf

subgraph KDF["Key Derivation"]
    Argon["Argon2id\nm=19456 t=2 p=1"]
end

subgraph Encrypt["Encryption"]
    AES["AES-256-GCM"]
    Nonce["Random Nonce\n(12 bytes)"]
end

subgraph Output["WDNV File"]
    direction TB
    Magic["WDNV (4B)"]
    Ver["Version (2B)"]
    SaltOut["Salt (16B)"]
    Payload["Nonce ‖ Ciphertext ‖ Tag"]
end

Pass --> Argon
Salt --> Argon
Argon -- "256-bit key" --> AES
Creds --> AES
Nonce --> AES
AES --> Payload

style Input fill:#1a1a2e,stroke:#e94560,color:#fff
style KDF fill:#16213e,stroke:#00d2ff,color:#fff
style Encrypt fill:#16213e,stroke:#00d2ff,color:#fff
style Output fill:#0f3460,stroke:#533483,color:#fff

### 파일 형식```
Bytes 0-3:   Magic "WDNV"
Bytes 4-5:   Version (u16 LE)
Bytes 6-21:  Argon2id salt (16 bytes)
Bytes 22+:   AES-256-GCM encrypted payload (nonce ‖ ciphertext ‖ tag)