Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Unworldly는 AI 코딩 에이전트가 사용자 기기에서 수행하는 파일 변경 및 셸 명령을 기록하는 로컬 블랙박스 시스템입니다. 이는 DVR처럼 세션을 재생하고 위험 행동을 표시하며, ISO 42001 규격의 감사 추적(audit trail)으로 봉인된 검증 가능한 기록을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Unworldly: a flight recorder for AI coding agents
CI
PyPI version
PyPI downloads
License: MIT
ISO 42001
Python
AI 코딩 에이전트를 위한 블랙박스입니다. 코딩 에이전트가 사용자의 기기에서 수행하는 파일 변경 사항과 셸 명령을 기록합니다. DVR처럼 세션을 재생하고, 위험한 행동을 표시하며, 위변조 방지 기능이 있는 ISO 42001 규격 준수 감사 추적(audit trail)으로 봉인합니다.
로그 없이 코드를 실행하지 않을 것입니다. 왜 코딩 에이전트가 블랙박스 없이 사용자의 기기를 편집하도록 내버려 두는 것일까요?
pip install unworldly-recorder
unworldly watch
# 이 프로젝트의 모든 파일 변경 및 셸 명령은 이제 기록됩니다.
Unworldly는 코딩 에이전트를 위한 로컬 블랙박스입니다. 즉, 사용자의 기기에서 실행되며 파일을 편집하고 셸 명령을 실행하는 방식(Claude Code, Cursor, Aider, Cline 등과 유사)으로 작동하는 에이전트들을 위한 것입니다. 이를 통해 시스템에 어떤 변경이 가해졌는지 봉인되고 재생 가능한 기록을 제공합니다.
아직까지는 클라우드/SDK 에이전트를 추적하는 도구는 아닙니다. 이러한 에이전트는 인-프로세스(in-process) API 호출 및 툴 호출 형태로 작업하며, 이는 수동적인 관찰자가 볼 수 있는 파일이나 프로세스의 흔적을 남기지 않습니다. 만약 이것이 사용 사례라면, MCP & OpenTelemetry 로드맵을 확인해 주세요. 저희가 다음에 정확히 메우고자 하는 간극입니다.
과장하기보다는 무엇을 포착하는지 명확하게 알려드리는 편이 낫습니다. 아래 **무엇을 포착하며 — 그리고 볼 수 없는 것**를 확인해 보세요.
코딩 에이전트는 파일을 편집하고, 명령을 실행하며, 패키지를 설치하고, 자격 증명(credentials)에 접근하는 등 종종 사용자의 개입 없이 작동합니다. 세션이 종료되면, 실제로 디스크와 셸에서 무슨 일이 일어났는지에 대한 영구적이고 검증 가능한 기록이 없습니다. Unworldly는 바로 그 기록을 제공합니다.
# 설치
pip install unworldly-recorder
...
Unworldly는 네 가지 레벨에서 에이전트를 캡처합니다. 사용 중인 에이전트에 맞는 레이어를 사용하세요. 모든 세션은 어떤 레이어가 기록했는지 기록하며, 해당 레이어가 볼 수 없었던 상태를 보고합니다.
| 레이어 | 명령어 / API | 캡처 항목 | 용도 |
|---|---|---|---|
| L1 파일 + 쉘 | unworldly watch (+ 손실 없는 기록을 위한 hook install) | 파일 변경 사항 + 쉘 명령 | 로컬 코딩 에이전트 (Claude Code, Cursor, Aider, Cline) |
| ... | |||
L2/L3/L4는 L1과 동일한 위험 점수 산정(risk scoring), 비밀 정보 마스킹(secret redaction), SHA-256 해시 체인, verify/report/replay 기능을 제공합니다. 자세한 내용은 specs/agent-instrumentation/spec.md를 참조하세요. |
╔═══════════════════════════════════════════════════╗
║ UNWORLDLY v0.6.0 ║
║ AI 에이전트를 위한 비행 기록 장치 (Flight Recorder) ║
...
위의 기록은 예시적입니다. 각 행동이 포착된 후 어떻게 분류되는지 보여줍니다. 명령이 얼마나 완전히 캡처되느냐는 캡처 모드에 따라 달라지므로, 다음 섹션을 참조하세요.
커버리지에 대해 솔직하게 보고하는 것은 부가 기능(footnote)이 아니라 핵심 기능입니다. 봉인된 감사 추적 기록(sealed audit trail)의 가치는 실제로 로그에 기록된 내용만큼만 합니다.
| 활동 | 캡처됨? | 방법 |
|---|---|---|
| 감시되는 프로젝트 내 파일 생성/수정/삭제 | ✅ 신뢰성 있음 | watchdog 파일 시스템 이벤트 |
| ... | ||
| 폴링 모드가 최선 노력(best-effort)인 이유: 기본 모니터는 간격으로 OS 프로세스 목록을 샘플링하기 때문에, 샘플링 사이에 시작하고 끝나는 명령어는 절대 감지할 수 없습니다. 완전하고 손실 없는 명령어 로그를 위해서는 셸 후크 모드(shell-hook mode)를 활성화하세요: |
unworldly hook install # bash/zsh/pwsh의 셸 rc에 preexec 후크 추가
만약 에이전트가 결정하는 것(도구 호출)을, 단순히 시스템에 미치는 부작용만 아는 것이 아니라 캡처해야 한다면, 그것은 로드맵의 MCP 캡처 경로를 이용하세요.
SDK로 구축된 에이전트는 파일 시스템에 접근하지 않는 인-프로세스 도구 호출(in-process tool calls) 형태로 작업을 수행하므로, 파일/명령어 모니터링으로는 이를 감지할 수 없습니다. 트레이스 레코더(trace recorder)로 도구를 래핑하여 에이전트의 *결정 경로(decision trail)*를 동일한 봉인되고 검증 가능한 세션에 캡처하세요:
from unworldly import AgentTraceRecorder, trace_tool
rec = AgentTraceRecorder(agent_name="support-bot")
...
MCP를 통해 도구를 사용하는 경우? 대신 세션 자체를 래핑하세요. 모든 call_tool은 로그로 기록된 후 변경 없이 전달됩니다:
from unworldly import AgentTraceRecorder, MCPCaptureProxy
session = MCPCaptureProxy(mcp_client_session, AgentTraceRecorder(agent_name="bot"))
도구 호출은 휴리스틱하게 위험 점수(network/egress, 삭제, 자격 증명 접근 → 위험)가 매겨지며, 명시적인 risk=를 전달하여 이를 재정의할 수 있습니다. 전체 캡처 레이어 설계는 specs/agent-instrumentation/spec.md를 참조하세요.
| Feature | Unworldly | AgentOps | SecureClaw | Manual Logging |
|---|---|---|---|---|
| Coding-agent-agnostic | 모든 로컬 코딩 에이전트 지원 | Python SDK 전용 | OpenClaw 전용 | 에이전트별 설정 |
| ... |
.unworldly/config.json 파일을 통해 사용자 정의 위험 패턴(allowlist/blocklist)을 설정할 수 있습니다.Unworldly는 ISO 42001 AI 관리 시스템 표준의 주요 통제 항목을 구현합니다:
| ISO 42001 통제 | 요구 사항 | Unworldly 구현 |
|---|---|---|
| A.3.2 역할 및 책임성 (Roles & accountability) | 누가 행동하는지 파악해야 함 | 에이전트 식별자를 자동 감지합니다 |
| ... |
# 세션 무결성 검증 — 종료 0 = 유효, 종료 1 = 변조됨
unworldly verify
...
시스템을 수정하는 AI 에이전트를 자동으로 식별합니다:
| 에이전트 | 탐지 방법 |
|---|---|
| Claude Code | CLAUDE_CODE env, claude process |
| ... | |
에이전트를 찾을 수 없나요? 이슈 열기를 하거나 직접 추가하세요 — 이는 unworldly/agent_detect.py의 한 항목입니다. |
| 패턴 | 위험 수준 | 예시 |
|---|---|---|
| 일반 파일 편집 | 안전함 (Safe) | 소스 파일을 생성/편집하는 행위 |
| ... |
{
"commands": {
"allowlist": [
...
프로젝트 루트에 .unworldly/config.json으로 저장하세요.
'기계에서 발생하는 부작용을 기록하는 것'과 '에이전트가 실제로 수행한 것을 기록하는 것' 사이의 격차를 해소하기:
preexec를 통한 손실 없는 명령어 로깅 (폴링 모드 누락 수정) — unworldly hook installMCPCaptureProxy가 에이전트가 수행하는 모든 call_tool을 로깅한 후 전달합니다. 이는 단순한 OS 부작용이 아닌 실제 의사 결정 경로입니다.--hipaa)CONTRIBUTING.md를 참조하세요. PR(Pull Request)을 환영합니다. 특히 새로운 에이전트 탐지(agent detections), 위험 패턴(risk patterns), 그리고 플랫폼 수정 사항(platform fixes)에 대한 기여를 기대합니다.
MIT 라이선스를 따릅니다. LICENSE를 참조하세요.