ClawShield

AI 에이전트용 보안 프록시. OpenClaw 앞에서 모든 메시지를 검사하여 프롬프트 인젝션, PII 유출, 시크릿이 모델에 도달하거나 네트워크를 벗어나기 전에 차단합니다.

5개의 특화 AI 에이전트, 내장 대시보드, YAML 정책 엔진이 함께 제공됩니다. 명령 하나로 시작하세요.

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Browser    │────▶│  ClawShield      │────▶│   OpenClaw   │
│   (you)      │◀────│  Security Proxy  │◀────│   Gateway    │
└──────────────┘     └──────────────────┘     └──────────────┘
                      ▪ Prompt injection       ▪ Claude, GPT,
                        detection                LM Studio
                      ▪ PII/secrets redaction  ▪ Multi-agent
                      ▪ Policy enforcement       routing
                      ▪ Audit logging          ▪ RAG knowledge

빠른 시작 (Docker)

사전 요구사항: Docker 및 Anthropic API 키.

# 1. Clone the repo
git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public

# 2. Set your API key
cp standalone/.env.template standalone/.env
# Edit standalone/.env and paste your Anthropic API key

# 3. Start
cd standalone
docker compose up -d

브라우저에서 **http://localhost:18801**을 엽니다. 채팅 준비가 된 5개의 AI 에이전트가 있는 ClawShield 대시보드가 표시됩니다.

이것으로 끝입니다. ClawShield가 사용자와 에이전트 사이의 모든 트래픽을 검사합니다.

Anthropic API 키 발급받기

ClawShield는 기본 언어 모델로 (Anthropic API를 통한) Claude를 사용합니다. 키를 발급받는 방법은 다음과 같습니다:

1. console.anthropic.com에 접속하여 가입(또는 로그인)합니다
2. 왼쪽 사이드바에서 API Keys를 클릭합니다
3. Create Key를 클릭합니다
4. 이름(예: "clawshield")을 지정하고 Create를 클릭합니다
5. 키를 복사합니다 — sk-ant-로 시작합니다
6. standalone/.env 파일에 붙여넣습니다:
   root@kitploit:~

   ANTHROPIC_API_KEY=sk-ant-your-key-here
   

비용: Anthropic은 토큰당 요금을 부과합니다. 일반적인 채팅 세션은 몇 센트 정도입니다. 새 계정에는 $5 상당의 무료 크레딧이 제공됩니다. 자세한 내용은 anthropic.com/pricing을 참조하세요.

다른 모델을 사용하고 싶으신가요? ClawShield는 모든 OpenAI 호환 API(GPT, LM Studio, Ollama 등)와 함께 작동합니다. standalone/config/openclaw.json을 편집하여 원하는 제공업체를 지정하세요.

설치 옵션

옵션 1: Docker (권장)

모든 것이 단일 컨테이너에서 실행됩니다 — ClawShield 프록시 + OpenClaw 게이트웨이 + 5개 에이전트.

위의 빠른 시작을 참조하세요.

옵션 2: 사전 빌드된 바이너리

GitHub Releases에서 최신 릴리스를 다운로드하세요:

그런 다음 대화형 설정 마법사를 실행합니다:

# Download the setup wizard too
chmod +x clawshield-setup-*

# Run the wizard — it walks you through everything
./clawshield-setup-linux-amd64

마법사는 다음 작업을 수행합니다:

• Anthropic API 키를 요청합니다
• 에이전트를 구성합니다
• OpenClaw 구성을 생성합니다
• 시작/중지 스크립트를 생성합니다

옵션 3: 소스에서 빌드

Go 1.24+가 필요합니다.

git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public

# Build the proxy
cd proxy/cmd/clawshield-proxy
go build -o clawshield-proxy

# Build the setup wizard
cd ../../clawshield-setup
go build -o clawshield-setup

# Run setup
./clawshield-setup

포함 내용

관측 가능성

ClawShield는 실시간 모니터링을 위해 Prometheus 호환 /metrics 엔드포인트를 제공합니다:

curl http://localhost:18789/metrics

주요 메트릭:

• clawshield_requests_total — 평가된 총 요청 수
• clawshield_decisions_allowed_total / _denied_total / _redacted_total — 결정 결과
• clawshield_scanner_detections_total{scanner,action} — 스캐너 유형별 탐지 건수
• clawshield_evaluation_duration_seconds — 평가 지연 시간 히스토그램
• clawshield_active_connections — 현재 WebSocket 연결 수
• clawshield_crosslayer_events_* — 크로스 레이어 이벤트 버스 활동

보안 프록시

ClawShield의 핵심입니다. 사용자와 AI 게이트웨이 사이의 모든 트래픽을 가로채는 HTTP 리버스 프록시입니다.

스캐너 (각 스캐너는 규칙 ID와 마스킹된 매치 발췌문이 포함된 구조화된 포렌식 감사 기록을 생성합니다):

• 프롬프트 인젝션 탐지 — 제일브레이크 시도, 명령어 덮어쓰기, 역할 조작을 차단합니다
• PII 마스킹 — 이메일, 전화번호, 주민등록번호(SSN), 신용카드를 탐지하고 마스킹합니다
• 시크릿 탐지 — API 키, 토큰, 비밀번호가 유출되기 전에 잡아냅니다
• 취약점 스캐닝 — SQL 인젝션, SSRF, 경로 탐색, 커맨드 인젝션, XSS를 플래그합니다
• 악성코드 분석 — 실행 파일, 스크립트, 압축 폭탄, 알려진 시그니처를 탐지합니다

프로덕션 강화 (레이어 3):

• Python/BCC 의존성을 대체하는 Go 네이티브 eBPF 모니터 — 단일 컴파일 바이너리
• 단계적 성능 저하(graceful degradation): eBPF를 사용할 수 없을 때(CAP_BPF 없음, 오래된 커널, 컨테이너) /proc 폴링으로 자동 폴백
• 헬스 체크 시스템: 3개 방어 레이어 모두에 대한 레이어별 상태 보고(healthy/degraded/down)
• 이벤트 파이프라인 안정성: 손실 카운팅, 백프레셔 로깅, 게시/드롭 이벤트 메트릭
• 방화벽 규칙을 위한 동적 DNS 재해석 — CDN IP가 변경될 때 오래된 규칙 방지
• 시작 시 기능 탐지: 커널 버전, BTF 지원, root/CAP_BPF 확인

정책 핫-리로드:

• 파일 감시 기반 핫-리로드 — policy.yaml을 수정하면 재시작 없이 5초 이내에 변경 사항이 적용됩니다
• 콘텐츠 해시 버전 관리 — 모든 정책 버전은 SHA256 기반 버전 ID를 부여받아 감사 로그에 기록됩니다
• 섀도/카나리 모드 — 적용 전에 로그 전용 모드에서 새 정책을 테스트합니다
• 정책 diff — 리로드할 때마다 정확히 무엇이 변경되었는지(허용 목록 추가, 스캐너 토글 등) 로그에 기록합니다
• 원자적 교체 — 진행 중인 요청은 기존 정책을 계속 사용하고, 새 요청은 새 정책을 사용합니다

스트리밍 응답 스캐닝:

• SSE 및 NDJSON 스트림의 청크 단위 실시간 스캐닝 — 버퍼링 지연 없음
• 슬라이딩 오버랩 윈도우(200자)가 청크 경계에 걸친 패턴을 감지합니다
• 요청에서 응답으로 컨텍스트를 전달하여 오탐(false positive)을 줄입니다(예: 코드 생성 응답에는 스크립트 패턴이 포함될 수 있음)
• 스트리밍 출력에서 시크릿과 PII의 청크별 마스킹

정책 엔진 — YAML 기반, 기본 거부(deny-by-default):

default_action: deny

scanners:
  prompt_injection:
    enabled: true
    action: block
  pii:
    enabled: true
    action: redact
  secrets:
    enabled: true
    action: block

domain_allowlist:
  - "api.anthropic.com"
  - "api.openai.com"

더 많은 예시는 policy/examples/를 참조하세요.

5개 AI 에이전트

각 에이전트는 전문 역할과 자체 RAG 지식 기반을 보유합니다:

감사 로깅

모든 요청과 응답은 다음 항목과 함께 로컬 SQLite 데이터베이스에 기록됩니다:

• 타임스탬프, 소스 IP, 요청 메서드
• 사유가 포함된 스캐너 결정(allow/block/redact)
• 결정 설명 가능성(Decision explainability) — 어떤 스캐너가 발동했는지, 어떤 규칙이 매치되었는지, 매치의 안전하게 마스킹된 발췌문, 신뢰 수준을 포함한 모든 deny/redact 결정에 대한 구조화된 포렌식 상세 정보
• 전체 요청/응답 페이로드(구성 가능)

내장 감사 CLI를 통한 조회:

clawshield-audit --db /var/lib/clawshield/audit.db --last 50
clawshield-audit --db /var/lib/clawshield/audit.db --blocked-only
clawshield-audit --db /var/lib/clawshield/audit.db --scanner injection
clawshield-audit --db /var/lib/clawshield/audit.db --rule-id sqli

전체 스키마는 docs/audit-log-format.md를, 포렌식 조회 세부 사항은 결정 설명 가능성을 참조하세요.

SIEM 통합:

• Critical 및 High 심각도 이벤트의 엔터프라이즈 SIEM 시스템 실시간 전달
• 범용 SIEM 호환성을 위한 OCSF v1.1 Detection Finding 형식
• Syslog(TCP/TLS를 통한 RFC 5424) 및 웹훅(HTTPS POST) 전송
• 구성 가능한 심각도 임계값 — 기본적으로 High(4) 및 Critical(5) 알림만 전달
• 구성 방법은 docs/audit-log-format.md을 참조하세요

네트워크 방화벽 (선택 사항)

에이전트가 접근할 수 있는 도메인/IP를 제한하는 iptables 기반 이그레스(egress) 방화벽:

cd firewall/cmd/clawshield-fw && go build -o clawshield-fw
sudo ./clawshield-fw apply --config firewall/examples/firewall.yaml

eBPF 모니터 (선택 사항)

의심스러운 에이전트 동작을 탐지하기 위한 커널 레벨 syscall 모니터링:

sudo python3 ebpf/cmd/clawshield-ebpf/main.py --config ebpf/config/default.yaml

탐지 항목: 포크 폭탄, 민감한 파일 접근, 권한 상승, 비정상 네트워크 연결.

아키텍처

ClawShield는 **심층 방어(defense-in-depth)**를 사용합니다 — 크로스 레이어 이벤트 버스로 연결된 3개 보안 레이어:

Layer 1: Application (ClawShield Proxy)
  ▪ Scans message content
  ▪ Enforces YAML policies
  ▪ Logs all decisions

Layer 2: Network (ClawShield Firewall)
  ▪ iptables egress rules
  ▪ Domain/IP allowlist
  ▪ Blocks unapproved connections
  ▪ Dynamic temporary rules from cross-layer events

Layer 3: Kernel (ClawShield eBPF)
  ▪ Syscall monitoring
  ▪ Behavioral anomaly detection
  ▪ Real-time alerts

각 레이어는 독립적으로 작동합니다. 하나가 우회되어도 나머지 레이어가 계속 보호합니다.

크로스 레이어 이벤트 버스

3개 레이어는 Unix 소켓 기반 이벤트 버스를 통해 통신하여 레이어 간 적응형 보안 대응을 가능하게 합니다:

┌──────────────┐                          ┌──────────────┐
│  eBPF        │──── Unix Socket ────────▶│  Proxy       │
│  (Layer 3)   │  /tmp/clawshield-       │  (Layer 1)   │
│  Produces:   │   events.sock           │  Produces:   │
│  • privesc   │                          │  • injection │
│  • port_scan │◀── Adaptive Controller ──│  • malware   │
│  • file_access│                         │  • vuln_scan │
└──────────────┘                          └──────────────┘
                         │
                         ▼
                ┌──────────────┐
                │  Firewall    │
                │  (Layer 2)   │
                │  Consumes:   │
                │  • temp block│
                │    rules     │
                └──────────────┘

적응형 대응 예시:

정책 YAML에 adaptive 섹션을 추가하여 크로스 레이어 통합을 활성화하세요. 전체 예시는 policy/examples/adaptive_crosslayer.yaml을 참조하세요.

프로덕션 배포

TLS를 사용하여 실제 서버에 배포하려면 docs/install-guide.md를 참조하세요.

deploy/ 디렉터리에는 다음이 포함됩니다:

• cloud-init.yaml — 강화된 VM 프로비저닝(SSH 잠금, fail2ban, nftables, auditd)
• docker-compose.yml — nginx TLS 종료를 포함한 전체 프로덕션 스택
• nginx/conf.d/ — 레이트 리밋, 보안 헤더, WebSocket 프록시가 포함된 프로덕션 nginx 구성
• deploy.sh — 자동화된 배포 스크립트
• smoke-test.sh — 배포 후 검증

구성

환경 변수

파일

테스트

# Unit tests
go test ./proxy/...
go test ./firewall/...

# Integration tests
go test ./integration/...

기여

이슈 및 풀 리퀘스트는 github.com/SleuthCo/clawshield-public에서 환영합니다.

라이선스

Apache 2.0

감사의 글

OpenClaw를 기반으로 구축되었습니다. AI 에이전트 컨텍스트에 적용된 전통적인 네트워크 보안 아키텍처에서 영감을 받았습니다.