메타데이터
- 발신자: TLDR
- 원문 URL: https://github.com/perplexityai/numbat
- 발행일: 2026-07-30
- 카테고리: dev-engineering
직역 전문
(참고: 뉴스 기사가 아닌 GitHub 저장소 README이며, 전체 접근이 가능했다. 아래는 README 전체 내용을 문단 단위로 번역한 것이다.)
AI 에이전트 활동에 대한 엔드포인트 가시성(endpoint visibility)을 제공하며, 로컬 탐지(local detection), 선택적 사전 차단(pre-action blocking), 포렌식 재구성(forensic reconstruction) 기능을 갖췄다.
numbat은 로컬 훅(hook)과 플러그인, OTLP/HTTP 로그, 디스크에 저장된 세션 아티팩트를 통해 지원되는 데스크톱, CLI, IDE, 게이트웨이 에이전트들을 관찰한다. 실시간 및 저장된(at-rest) 활동은 하나의 이벤트 모델로 정규화되어 동일한 CEL 규칙 엔진(rule engine)으로 평가된다. 탐지는 로컬에서 실행되며, 기록은 표준출력이나 로컬 파일에 기록되고 선택적으로 HTTP를 통해 전달될 수 있다.
각 호스트와 표면(surface)에 대한 커버리지 매트릭스(coverage matrix)가 공식 기준 문서다. 차단(blocking)은 기본적으로 꺼져 있으며, 지원되는 동기식 사전 조치 훅(synchronous pre-action hooks)으로 범위가 제한된다.
주요 기능
- 훅, 플러그인, OTLP/HTTP 로그 익스포터를 통한 실시간 모니터링.
- 내장 CEL 규칙, 다단계 시퀀스 규칙, 커스텀 YAML 규칙을 활용한 엔드포인트 로컬 탐지.
- 지원되는 사전 조치 훅을 통한 옵트인(opt-in) 차단. 강제 모드(enforce mode)는 기본적으로 비활성화되어 있으며
enforce: true로 표시된 규칙에만 적용된다. 기본 제공 규칙은 모두 모니터링 전용(monitor-only)이다. - numbat 사전 계측 없이도 지원되는 디스크상 세션 아티팩트로부터 포렌식 재구성을 수행.
- 이벤트, 발견사항(findings), 강제 조치 결정, 지표(indicators), 스캔 요약에 대한 버전 관리된 NDJSON 레코드. 이벤트와 발견사항은 출처 참조를 유지하며, JSON 스키마가 와이어 포맷을 정의한다.
- 비밀정보 마스킹(secret redaction)을 포함한 읽기 전용 아티팩트 스캔. 일반 레코드 출력에는 전체 원본 트랜스크립트가 포함되지 않으며, 원본 증거 파일을 케이스 번들에 추가하는 것은 옵트인이다.
- 읽기 전용 에이전트 탐지, 세션별 타임라인, SHA-256 매니페스트가 포함된 이식 가능한 케이스 번들을 위한 인벤토리·조사 도구.
- macOS, Linux, Windows용 단일 바이너리 배포(cgo 없이 빌드).
설치 릴리스 페이지에서 macOS, Linux, Windows(amd64/arm64)용 바이너리를 다운로드할 수 있으며, 각 릴리스에는 SHA-256 체크섬이 포함된다. Go 1.26.5 이상이 있다면 다음으로도 설치할 수 있다.
go install github.com/perplexityai/numbat/cmd/numbat@latest
체크아웃에서 정적 바이너리를 직접 빌드하려면:
- macOS/Linux:
CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat - Windows PowerShell:
$env:CGO_ENABLED = "0"; go build -trimpath -o numbat.exe ./cmd/numbat
사용법 다음 읽기 전용 명령은 훅을 설치하거나 에이전트 설정을 변경하지 않는다.
numbat agents # 발견된 파서 지원 에이전트 나열
numbat scan # 전체 스캔
numbat scan --agent codex # 특정 에이전트만 제한
라이브 캡처를 지원하는 에이전트라면 훅을 설치할 수 있다(예: Codex).
numbat hook install --agent codex --emit all
numbat hook status --agent codex
훅은 모니터링 전용 모드로 시작하며, --emit all 옵션은 이벤트·발견사항·지표·해당하는 강제 조치 결정을 ~/.numbat/records.ndjson에 기록한다.
훅 신뢰(Hook trust): 요구사항은 에이전트와 범위에 따라 다르다. Codex 사용자 훅의 경우 CLI의 /hooks 또는 앱의 Settings > Hooks에서 현재 훅 정의를 검토하고 신뢰해야 하며, --enforce 같은 변경 후에도 마찬가지다. --managed로 설치된 Codex 훅은 정책상 신뢰된다. hook status는 설정만 검증하며 실행이나 전달 여부는 검증하지 않는다.
기본 제공 규칙은 모두 모니터링 전용이다. 탐지를 강제(enforce)하려면 해당 규칙의 전체 YAML을 통제된 오퍼레이터 디렉터리로 복사하고, 동일한 id를 유지한 채 enforce: true를 추가하고 버전을 올린 뒤 다음으로 검증·설치한다.
numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all --rules-dir ./numbat-policy --enforce
README에 포함된 예시 레코드 세 가지
- 훅 이벤트: OpenClaw 에이전트가 클라우드 메타데이터 엔드포인트(
169.254.169.254)에 접근하려는 시도를network.indicator이벤트로 포착하고, 고위험 클라우드 메타데이터 규칙과 매칭시킨 사례. - 시퀀스 발견: Claude Code에서 비밀 파일(
.env.production) 접근 후 외부 업로드 시도가 이어지는 두 단계 훅을 리플레이해,chain.secret_read_then_egress규칙이 탐지한 사례. - 강제 조치 결정:
persistence.ssh_authorized_keys규칙을enforce: true로 설정한 상태에서 Codex의create_file사전 조치가 이 규칙과 매칭되어 numbat이 거부(deny) 응답을 선택한 사례.
명령어 카테고리
- 인벤토리/조사:
agents,scan,timeline - 라이브 캡처:
hook install,hook status,hook uninstall,collect - 레코드 전달:
ship - 규칙 개발:
rules check,rules list,rules test - 케이스 번들:
case build,case verify
scan, collect, hook EVENT, hook install, rules check|list|test 명령은 --rules-dir DIR(반복 가능) 옵션으로 오퍼레이터 규칙을 추가하거나 내장 규칙을 id 기준으로 교체할 수 있다. --no-builtin-rules로 오퍼레이터 전용 카탈로그만 사용할 수도 있다.
제한사항 및 주의사항
- 저장된 상태 재구성(at-rest reconstruction)은 디스크나 메모리 포렌식 수집이 아니며, 에이전트가 저장하지 않은 활동은 복구할 수 없다.
- 발견사항(findings)은 규칙 매칭일 뿐 침해의 증거가 아니다.
- 케이스 번들 매니페스트는 내부 일관성만 보장하며, 서명되지 않은 번들은 출처의 진위나 완전성을 증명하지 않는다.
- 레코드는 마스킹 후에도 민감한 엔드포인트·에이전트 정보를 포함할 수 있다.
- numbat은 아티팩트에서 발견된 에이전트나 명령을 절대 실행하지 않으며, 설정된 HTTP 싱크(sink) 외에는 외부로 요청을 보내지 않는다.
라이선스: Apache License 2.0.
4계층 심층 요약
1. 핵심 주장
Perplexity AI가 오픈소스로 공개한 numbat은 데스크톱·CLI·IDE·게이트웨이 AI 에이전트의 활동을 엔드포인트에서 로컬로 관찰·탐지·(선택적으로) 차단하고, 사후에는 디스크에 남은 세션 아티팩트로부터 포렌식 재구성까지 지원하는 보안 가시성 도구다. 실시간 훅과 저장 데이터 스캔을 동일한 이벤트 모델·CEL 규칙 엔진으로 평가해 일관된 탐지 파이프라인을 제공한다.
2. 근거
- Codex, Claude Code 등 여러 AI 코딩 에이전트에 대한 훅/플러그인 기반 라이브 모니터링을 지원한다.
- CEL 기반 커스텀 규칙과 다단계 시퀀스 규칙으로 "비밀파일 접근 후 외부 전송" 같은 공격 패턴을 탐지할 수 있다.
- 차단(enforcement)은 기본 비활성화, 명시적으로
enforce: true를 설정한 규칙에만 적용되는 옵트인 구조로 안전장치를 마련했다. - 이벤트/발견/강제조치/지표를 스키마 버전 관리된 NDJSON으로 출력해 SIEM 등 외부 시스템과 연동할 수 있다.
- macOS/Linux/Windows용 단일 바이너리로 배포되며 Go로 작성, cgo 없이 빌드되어 이식성이 높다.
3. 사례
- README 예시에서 OpenClaw 에이전트가 클라우드 메타데이터 엔드포인트(169.254.169.254)에 접근하려는 시도를
network.indicator이벤트로 캡처했다. - Claude Code에서
.env.production파일 접근 후 외부 서버로 데이터 전송을 시도하는 2단계 공격 패턴을secret_read_then_egress규칙으로 탐지했다. - Codex의 SSH authorized_keys 파일 쓰기 시도를 enforce 모드 규칙이 실제로 차단(deny)한 사례를 레코드로 예시했다.
4. 시사점
AI 코딩 에이전트가 파일 시스템, 셸, 네트워크에 광범위한 권한을 갖게 되면서, "에이전트가 실제로 무엇을 했는가"를 엔드포인트 레벨에서 감사할 수 있는 도구의 필요성이 커지고 있다. 토니처럼 Codex, Claude Code, OpenClaw 등 여러 에이전트를 동시에 운영하는 개발자/스타트업 입장에서는, numbat 같은 도구로 에이전트의 이상 행동(비밀정보 유출, 퍼시스턴스 조작 등)을 사후에 재구성하거나 실시간으로 차단할 수 있다는 점이, 프로덕션 환경에서 AI 에이전트를 신뢰하고 운영하는 데 실질적으로 참고할 만하다.
핵심 요약 (20줄)
- numbat은 Perplexity AI가 공개한 오픈소스 도구로, AI 에이전트 활동에 대한 엔드포인트 가시성을 제공한다.
- 로컬 탐지, 선택적 사전 차단(pre-action blocking), 포렌식 재구성이라는 세 가지 핵심 기능을 갖췄다.
- 지원되는 데스크톱, CLI, IDE, 게이트웨이 에이전트를 로컬 훅과 플러그인, OTLP/HTTP 로그, 디스크상 세션 아티팩트를 통해 관찰한다.
- 실시간 활동과 저장된(at-rest) 활동을 하나의 이벤트 모델로 정규화해 동일한 CEL 규칙 엔진으로 평가한다.
- 탐지는 항상 로컬에서 실행되며, 기록은 표준출력이나 로컬 파일에 남고 선택적으로 HTTP로 전달할 수 있다.
- 차단 기능은 기본적으로 꺼져 있으며, 지원되는 동기식 사전 조치 훅으로만 제한된다.
- 기본 제공 규칙은 모두 모니터링 전용(monitor-only)이며, enforce: true로 명시한 규칙만 실제로 차단을 수행한다.
- 이벤트, 발견사항, 강제조치 결정, 지표, 스캔 요약을 버전 관리된 NDJSON 레코드로 출력하며 JSON 스키마로 형식을 정의한다.
- 읽기 전용 아티팩트 스캔 시 비밀정보를 자동 마스킹하며, 원본 트랜스크립트 전체를 케이스 번들에 포함하는 것은 별도 옵트인이 필요하다.
- 에이전트 인벤토리 조회, 세션별 타임라인, SHA-256 매니페스트가 포함된 이식 가능한 케이스 번들 생성 기능을 제공한다.
- macOS, Linux, Windows(amd64/arm64)용 단일 바이너리로 배포되며 cgo 없이 Go로 빌드된다.
- 설치는 릴리스 바이너리 다운로드 또는
go install github.com/perplexityai/numbat/cmd/numbat@latest로 가능하다. numbat agents,numbat scan같은 명령은 읽기 전용으로, 훅을 설치하거나 에이전트 설정을 바꾸지 않는다.numbat hook install --agent codex --emit all명령으로 라이브 모니터링 훅을 설치할 수 있으며 기본은 모니터링 전용 모드로 시작한다.- 훅 신뢰(hook trust) 요구사항은 에이전트별로 다르며, Codex의 경우 CLI
/hooks나 앱 설정에서 훅 정의를 직접 검토·신뢰해야 한다. - 탐지를 강제(enforce)하려면 규칙 YAML을 오퍼레이터 디렉터리에 복사해 enforce: true를 추가하고 버전을 올린 뒤 별도 설치해야 한다.
- README 예시로 OpenClaw 에이전트가 클라우드 메타데이터 엔드포인트(169.254.169.254)에 접근을 시도한 네트워크 이벤트가 소개된다.
- 또 다른 예시로 Claude Code에서 .env.production 파일 접근 후 외부 전송을 시도하는 2단계 공격을 secret_read_then_egress 규칙이 탐지한 사례가 제시된다.
- Codex가 SSH authorized_keys 파일을 쓰려는 시도를 enforce 모드의 persistence 규칙이 실제로 거부(deny)한 강제조치 예시도 포함된다.
- numbat은 아티팩트에서 발견된 명령을 절대 실행하지 않으며 설정된 HTTP 싱크 외에는 외부로 요청을 보내지 않고, Apache License 2.0으로 배포된다.