____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  / /_/ / /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

DefenseClaw는 Python 연산자 CLI, Go 게이트웨이 사이드카, OpenClaw TypeScript 플러그인을 결합합니다. 이들은 단순한 운영 규칙을 함께 적용합니다: 신뢰할 수 없는 에이전트 기능은 스캔되고, 거버넌스되며, 로깅되고, 정책에 따라 안전하지 않다고 판단되면 차단됩니다.

주요 기능

• 승인 제어 - 실행 전 스킬, MCP 서버, 플러그인, 코드를 스캔합니다.
• 런타임 가드레일 - 정규식 규칙, 정책, 선택적 LLM 판정자, Cisco AI Defense 검사를 통해 프롬프트, 완성, 도구 호출을 검사합니다.
• CodeGuard - 비밀, 위험한 실행, 안전하지 않은 역직렬화, 취약한 암호화, 인젝션 패턴, 위험한 파일 액세스에 대한 내장 정적 검사.
• OpenShell 샌드박스 지원 - 네트워크, 파일시스템, 시스템 콜, 정책 제어 기능이 있는 Linux 샌드박스 설정.
• 레지스트리 - 외부 스킬/MCP 카탈로그(기업 HTTPS YAML, smithery.ai, skills.sh, git, ClawHub)를 SSRF 가드, 스캐너 기반 판정, 자산 정책으로의 자동 승격과 함께 수집합니다. docs/REGISTRIES.md를 참조하세요.
• 감사 및 관측 가능성 - 버킷 수집을 위한 단일 config-v8 그래프, 필수 SQLite 기록, 중앙 집중식 수정, 독립적인 JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, 콘솔, 로컬 Grafana/Splunk 대상.
• 연산자 UX - 설정, 상태 점검, 알림, 허용/차단 목록, 스캐너 결과, 정책 워크플로를 위한 CLI 및 TUI.

범위 및 제한 사항

DefenseClaw는 에이전트 AI 배포를 위한 시행 및 증거 계층입니다. 스캐너 결과, 런타임 검사, 정책 결정, 샌드박스 제어, 감사 추적을 결합하여 안전성을 향상시키지만, 에이전트, 스킬, 플루 ugin, 또는 모델 상호작용이 위험 없음을 증명하지는 않습니다.

고위험 배포에서는 DefenseClaw를 사람의 검토, 최소 권한 자격 증명, 샌드박싱, CI 게이트, 프로덕션 모니터링과 함께 사용해야 합니다. 관찰 모드에서는 발견 사항이 차단 없이 로깅됩니다. 작동 모드에서는 구성된 HIGH 및 CRITICAL 발견 사항이 프롬프트, 도구 호출 또는 구성 요소 승인을 차단할 수 있습니다.

문서

프로젝트 Markdown 문서는 docs/ 아래에 중앙 집중화되어 있습니다. 패키지 로컬 README는 번들이나 예제와 함께 두며, 로컬 컨텍스트가 필요합니다.

설치

선행 조건

소스에서 빌드 (개발자 전용)

의도에 따라 명령을 선택하세요:

The source targets and `scripts/install-dev.sh` are development tooling, not an
upgrade path. Direct install targets refuse to overwrite a release-managed
installation or one owned by another checkout. `make all` is the explicit
developer-machine reinstall workflow: when the installed CLI already points
exactly into the current checkout, it may reclaim markerless or prior-release
source state and records a strict ownership marker after rebuilding. This can
run the checkout's current migrations against developer state and must not be
used as a release upgrade. Release-managed installations must use the
release-owned `scripts/upgrade.sh` or `scripts/upgrade.ps1` resolver.
`make install`, `make dev-install`, and `scripts/install-dev.sh` are lower-level
strict plumbing for a fresh or isolated development home; they are not the
normal repeated-development command.

### 릴리스 스크립트로 설치```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

For platform-specific steps, see docs/INSTALL.md.

On native Windows x64, use the native Setup EXE and hook-only connector path in the Native Windows guide. WSL is unsupported. Codex CLI and Claude Code are the only certified Windows connectors.

Quick Start```bash

Check the local install and dependencies

defenseclaw doctor

Initialize config, scanner defaults, and guardrail plumbing

defenseclaw init --enable-guardrail

Scan installed agent capabilities

defenseclaw skill scan all defenseclaw mcp list defenseclaw plugin scan extensions/defenseclaw

Start the Go gateway sidecar

defenseclaw-gateway start

Open the operator dashboard

defenseclaw tui

튜닝하는 동안 guardrail을 관찰 모드로 실행하십시오:```bash
defenseclaw setup guardrail --mode observe --restart

정책이 차단할 준비가 되면 작업 모드로 전환하세요:```bash defenseclaw setup guardrail --mode action --restart

See [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md)를 전체 워크스루에 대해 참조하세요.

---

## 아키텍처

| 구성 요소 | 런타임 | 역할 |
|-----------|---------|------|
| Python CLI | Python | 운영자 명령, 스캐너 오케스트레이션, 구성 설정, 로컬 번들 |
| 게이트웨이 사이드카 | Go | REST API, WebSocket 브리지, 정책 엔진, 가드레일 프록시, 감사 저장소, 텔레메트리 |
| OpenClaw 플러그인 | TypeScript | Fetch 가로채기, 도구 호출 검사 훅, 슬래시 명령, 사이드카 통합 |
| 정책 | YAML/Rego | 승인 결정, 가드레일 조치, 샌드박스/방화벽 동작, 스캐너 프로파일 |
| 문서 | Markdown/JSON | 중앙 집중식 문서, 패키지 로컬 README, DeepWiki 구성 |

게이트웨이는 CLI와 플러그인을 위한 로컬 REST API를 노출하고, WebSocket을 통해 OpenClaw에 연결하며, 로컬 프록시를 통해 LLM 트래픽을 검사하고, 내구성 있는 감사 저장소에 결정을 기록합니다.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

For diagrams and detailed flows, read docs/ARCHITECTURE.md.

스캐닝 및 가드레일

DefenseClaw는 Cisco AI Defense 스캐너와 로컬 정책을 단일 승인 흐름으로 래핑합니다:

스캐너 정책은 policies/scanners/에 있습니다. 가드레일 규칙 팩은 policies/guardrail/에 있습니다.

관찰 가능성

DefenseClaw는 여러 채널을 통해 시행 및 런타임 증거를 기록합니다:

Config v8은 소스를 간결하게 유지하면서 누락된 부분을 완전한 효과적인 계획으로 컴파일합니다:```yaml config_version: 8 observability: {}

That default collects every registered log, trace, and metric and retains every
collected log unredacted in mandatory local SQLite. No remote export occurs until
a destination is added. An enabled destination with no `send` or `routes` receives
every bucket and every signal its kind supports, unredacted: general OTLP gets
logs/traces/metrics, Splunk HEC gets logs, Prometheus gets metrics, and the Galileo
preset gets traces. Multiple destinations receive independent copies.

Review the expanded policy and unredacted legs with:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

사용자 정의 필드 인식 삭제 프로필을 버킷 또는 대상별로 중앙 집중식 none, sensitive, content, strict 중에서 선택하여 사용합니다. 전체 충실도 기본값에는 프롬프트, 출력, 도구 인수/결과, 증거, 경로 및 식별자가 포함될 수 있으므로, 해당 콘텐츠를 수신해서는 안 되는 신뢰 경계를 넘어 내보내기 전에 삭제 프로필을 구성하십시오.

소스 파일에서 버킷 및 삭제 정책을 편집하고, 게이트웨이가 확인하기 전에 유효성을 검사한 후, 생성된 참조를 그대로 복사하지 말고 컴파일된 결과를 검사하십시오.```bash umask 077 cp "$HOME/.defenseclaw/config.yaml"
"$HOME/.defenseclaw/config.yaml.before-observability-edit" ${EDITOR:-vi} "$HOME/.defenseclaw/config.yaml"

defenseclaw config validate &&
defenseclaw config show --effective --section observability &&
defenseclaw observability plan &&
defenseclaw-gateway restart &&
defenseclaw doctor

검증 실패 후 재시작하지 마십시오. 개인 백업을 복원하고, 소스를 수정한 후 다시 검증하십시오. 글로벌 또는 버킷 편집 프로필은 생성된 로컬 SQLite 프로젝션에도 적용됩니다. 원격 신뢰 경계만 편집하면서 전체 충실도 로컬 기록을 유지하려면 글로벌/버킷 프로필을 `none`으로 두고, 해당 원격 대상에 `send.redaction_profile` 또는 경로 프로필을 설정하십시오.

로컬 관측 가능성을 시작하려면:

``````bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

대시보드의 비어 있음은 하나의 상태가 아닙니다. 0은 계측된 신호에 일치하는 이벤트가 0개임을 의미하고, 데이터 없음은 선택한 범위 및 필터에 대해 일치하는 시리즈/로그/추적이 없음을 의미하며, 보고되지 않음은 커넥터/공급자가 토큰이나 비용과 같은 선택적 값을 제공하지 않았음을 의미합니다. HITL, 실패 전용 보기, Trace ID가 선택되기 전의 트레이스 폭포수와 같은 조건부 패널은 데이터 없음을 표시하는 것이 정상입니다. 대상 테스트는 연결만 확인할 뿐 일반적인 대시보드 트래픽을 생성하지 않습니다. 해당 패널을 검증하려면 새로운 실제 에이전트 턴, 도구 호출, 스캔 또는 승인을 생성하십시오.

Agent360의 노드 그래프는 Loki 기반 라이프사이클 DAG입니다. 세션 생성은 별도의 앵커이며, 루트당 하나의 프롬프트 입력 노드는 해당 범위 내에서 고유한 깊이 0의 model.request 사실(fact) 수를 계산하고, 부모-자식 위임은 에이전트별 모델, 도구, 승인, 업데이트, 턴 결과 및 터미널 요약을 제공합니다. 프롬프트 입력은 턴, 모델 요청, 요청, 작업, 그리고 발생 ID 순으로 중복 제거됩니다. 정렬됨/원시 보기는 개별 초기 및 후속 레코드를 유지합니다. 세션 및 생성 앵커는 이전 24시간 동안 복구될 수 있으므로 경계 윈도우를 렌더링할 수 있습니다. 복구된 생성은 해당 자식이 선택한 범위 내에서 그래프에 적합한 활동이 있는 경우에만 유지됩니다.

반복된 모델 호출은 소유 에이전트, 공급자 및 모델별로 그룹화됩니다. 반복된 도구 호출은 소유 에이전트별로 Bash, MCP, Skills, Collaboration, File edits, Web/browser, Visual 또는 Task control로 그룹화됩니다. 인식되지 않은 도구는 보고된 이름을 유지합니다. 정확한 collaboration.send_message 요청은 일반 Collaboration 패밀리에서 제외되어 메시지 그룹으로만 나타납니다. 다른 협업 도구는 해당 패밀리에 남아 있습니다. 요청 레코드는 터미널 상대가 도착하지 않은 경우에도 포함됩니다. 그룹화된 합계는 요청 개수이며, 모든 요청이 여전히 보류 중임을 주장하는 것은 아닙니다. 터미널 상태는 연결된 원시 레코드에서 계속 사용할 수 있습니다. 깊이 0은 루트이며, 재귀적 자식은 깊이 64까지 보고될 수 있습니다. 세부 정보를 클릭하면 각 계통 가장자리가 커넥터에 의해 보고되었는지 DefenseClaw에 의해 추론되었는지 확인할 수 있습니다. 노드 클릭은 정확한 개수와 안정적인 에이전트/루트/부모 ID를 노출하며, 각 그룹 뒤에 있는 원시 OTEL 이벤트에 대한 필터링된 링크를 제공합니다. 선택적 현재/루트/부모 세션 필드는 라이프사이클, 세션, 정렬됨 및 원시 화면에 남아 있습니다. 이는 에이전트 노드 그룹화 키가 아니므로, 누락되거나 늦은 세션 메타데이터가 한 에이전트의 총계를 분할할 수 없습니다.

대시보드는 필드를 다시 수정, 마스킹 또는 숨기지 않습니다. DefenseClaw는 표준 OTEL 내보내기 전에 중앙 집중식 v8 수정을 적용합니다. Grafana는 해당 프로젝션에 실제로 존재하는 모든 필드(생산자가 내보낸 경우 콘텐츠 포함)를 표시하거나 연결합니다. 내보내기 전에 제거되거나 변환된 필드는 로컬 스택에서 복구할 수 없습니다. 업데이트 가장자리는 실제 collaboration.send_message 도구 레코드에서만 발생합니다. 각 발신자에 대해 /root 및 /root/* 대상은 하나의 루트에게 메시지 노드로 축소되며, 대상 에이전트 ID는 내보낸 루트로 확인됩니다. 정확한 루트 작업 경로 및 호출은 정렬됨/원시 드릴다운에 남아 있습니다. 비루트 대상은 정확한 작업 경로별로 명시적으로 그룹화된 상태로 유지되며, 커넥터가 해당 매핑을 보고하지 않은 경우 불투명한 에이전트 ID 조인으로 발명되지 않습니다. 일반 호환성 이벤트는 업데이트로 다시 레이블이 지정되지 않습니다.

선택적 대상은 독립적인 경계 큐를 소유합니다. 기본값은 큐당 2,048개 레코드 및 64MiB입니다. 푸시 배치 기본값은 512개 레코드, 8MiB 및 5초(생략된 Galileo 사전 지연의 경우 1초)입니다. 큐 오버플로는 가장 최근에 시도된 인큐를 삭제하며, 이전 FIFO 작업을 축출하거나 필수 SQLite 및 형제 대상에 영향을 주지 않습니다. 정확한 필드, 경계 및 어댑터 차이점은 docs/OBSERVABILITY.md에 있습니다.

로컬 경로를 교체하지 않고 Galileo Cloud 또는 자체 호스팅 Galileo를 추가하십시오.```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

다음 문서를 참조하세요: [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), [Galileo 가이드](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx), [스키마 소유권 맵](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). Splunk 관련 설정은 [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md)에 있습니다.

기존의 지원되는 모든 POSIX 설치(이미 `0.8.4`를 사용 중인 경우 포함)는 최신 모드에서 버전 재정의 없이 인증된 대상 릴리스 `defenseclaw-upgrade.sh` 자산을 사용하여 `0.8.5` 하드 컷을 넘깁니다. 변경 불가능한 `0.8.4` 내장 파서는 Windows 브리지 매트릭스가 비어 있는 진실된 대상 매니페스트를 수용할 수 없습니다. 고정된 내장 CLI가 출력하는 사용되지 않는 원시 네트워크 힌트를 실행하지 마십시오. 릴리스 소유의 리졸버는 `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut`을 하나의 트랜잭션으로 수행합니다. 마이그레이션은 구성을 백업하고 원자적으로 변환하며, 더 좁은 라우팅/편집 동작과 루트/서브에이전트 Agent360 호환성을 유지하고, 볼륨을 초기화하지 않고 소유한 로컬 대시보드를 새로 고치며, 별도의 apply 명령이 필요하지 않습니다. 인증된 리졸버 부트스트랩에 대한 자세한 내용은 [CLI 참조 — 업그레이드](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade)를 참조하세요.

Splunk Observability Cloud의 경우, 다음 대시보드 번들을 사용하세요: [bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md):```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

개발```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

집중된 테스트 및 개발 가이드는 [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) 및 [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md)에 있습니다.

---

## 기여

기여를 환영합니다. [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md), [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) 및 변경하려는 영역에 대한 집중 문서부터 시작하세요.

## 보안

취약점은 [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md)에 명시된 절차를 통해 보고해 주시기 바랍니다.

## 라이선스

Apache 2.0 - [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE)를 참조하세요.

저작권 2026 Cisco Systems, Inc. 및 그 계열사.