목차

• 개요
• 실전 검증
• 기능
  • 현재 역량 경계
• 아키텍처
• 빠른 시작
• 정적 모델링 (1단계)
• 공격 합성 (2단계)
• 샌드박스 검증 (3단계)
• 판정 엔진 (4단계)
• MCP 감사 모듈
• 시맨틱 오염 엔진
• 지원 런타임
• 테스트 및 품질
• 크레딧
• 라이선스

개요

AgentStalker는 LLM 에이전트를 위한 종단간 보안 감사 프레임워크입니다. 감사를 네 단계 — MODEL → ATTACK → VERIFY → REPORT — 로 분해하고, 이를 타입이 지정된 오염 그래프로 연결하며, 전용 MCP 감사 모듈과 확률적 시맨틱 오염 엔진을 추가합니다. 검증은 계측된 Docker 샌드박스에서 실제 LLM 백엔드를 대상으로 실행되며, 확인된 모든 발견 사항에는 재현 가능한 증거가 첨부됩니다.

이 프레임워크는 Claude Code나 다른 오케스트레이션 LLM을 대체하지 않습니다. LLM 오케스트레이터가 감사로 구성하는 결정론적 도구, YAML 팩트, Jinja2 템플릿을 제공합니다. 이를 통해 프레임워크는 감사 가능하게 유지되고 오케스트레이터의 결정은 검토 가능하게 됩니다.

실전 검증

AgentStalker는 실제 Rust 에이전트 CLI인 CodeWhale v0.8.52(16개 크레이트, 332개 .rs 파일)를 대상으로 실제 DeepSeek API 백엔드와 Docker 샌드박스 격리를 사용하여 종단간 실행되었습니다. 아래의 모든 발견 사항은 재현 가능한 증거 파일로 뒷받침됩니다.

기능

타입이 지정된 계약을 갖춘 4단계 파이프라인. MODEL (AST + 오염 그래프) → ATTACK (맥락화된 페이로드) → VERIFY (샌드박스 재현) → REPORT (결정론적 규칙 + LLM 판정). 각 단계는 다음 단계가 소비하는 JSON 아티팩트를 생성하며, 단계는 독립적으로 교체 가능합니다.

전용 MCP 감사 모듈. 도구 이름, 설명, 전송 방식(stdio/sse/http)의 정적 추출; 세 가지 탐지기(도구 스쿼팅, 설명 오염, 토큰 패스스루); MCPMonitor를 통한 런타임 검증; VerdictEngine 규칙 R009–R011. 대부분의 에이전트 감사 도구가 열어두는 OWASP ASI04 격차를 해소합니다.

확률적 시맨틱 오염. LLM 홉은 불리언 오염이 아니라 확률적 전파자로 모델링됩니다. 각 흐름은 누적 신뢰도를 가지며, 불리언 is_exploitable 계약을 유지하면서 "LLM을 거치는 모든 것이 경보를 울린다"는 오탐 패턴을 줄입니다.

7계층 공격 표면 모델 + MCP. 사용자 입력, 컨텍스트/메모리, 도구 호출, MCP/플러그인, 신원/권한, 다중 에이전트, 관측 가능성 — 각각 타입이 지정된 오염 소스, 싱크, 전파 규칙을 갖습니다.

계측된 7개 컨테이너 샌드박스. 테스트 대상 에이전트, LLM 프록시(LiteLLM), mock-db, mock-mail, mock-api, eBPF 모니터(Tracee), nginx — 도구 허용 목록, 메타데이터로의 SSRF 차단, 민감 경로 접근 제어를 강제하는 OPA 정책 계층 포함.

14개 페이로드 카테고리 + 10개 다중 턴 체인. 페이로드는 first_pass/detection/sandbox_monitoring 메타데이터를 가지므로, 동일한 SQLi 페이로드가 LangChain query_db를 대상으로 하든 AutoGen db_exec를 대상으로 하든 올바르게 맥락화됩니다.

LLM 폴백을 갖춘 결정론적 판정 엔진. 11개 규칙(R001–R011)이 고신뢰 사례의 약 95%를 커버하며, 일치하지 않는 증거는 LLM-as-judge로 넘어갑니다.

이중 스택 언어 지원. Python(LangChain, AutoGen, CrewAI, LlamaIndex, LangGraph, MCP) 및 Rust(Codex 스타일 CLI, rmcp 서버). 언어는 pyproject.toml / Cargo.toml에서 자동 감지됩니다.

현재 역량 경계

이는 변명이 아니라 범위 결정 사항이며, 프레임워크가 오늘 하지 않는 일을 알 수 있도록 미리 명시합니다.

• Rust 정적 모델링은 Python보다 약합니다. Rust AST 추출기는 도구 정의를 Python보다 덜 정확하게 해석합니다(도구 이름이 조각일 수 있음). 동적 검증은 이에 의존하지 않지만, 완전 자동화된 Rust 감사는 정확도가 떨어집니다.
• 빠른 오염 모드는 속도를 위해 커버리지를 희생하며, 전체 BFS 모드는 대규모 코드베이스에서 느립니다. 빠른 추적기(소스 본문 + 호출자 ≤5개)는 직접 호출자 체인 밖의 싱크를 놓칠 수 있고, 전체 BFS 호출 그래프는 300개 이상의 파일에서 합리적인 시간 내에 완료되지 않습니다. 이것이 현재 해결 중인 핵심 정밀도/성능 긴장 관계입니다.
• eBPF 브레이크포인트(시맨틱 시스템 콜 상관관계)와 정적-동적 브리지는 로드맵 항목입니다. 시맨틱 오염 엔진은 골격으로 제공되며(v2 브레이크포인트 1), 브레이크포인트 2와 3은 검증을 위해 Linux + Tracee + 실제 에이전트 런타임이 필요하며 아직 구현되지 않았습니다.
• MCP 런타임 검증에는 등록된 MCP 서버가 필요합니다. 정적 MCP 발견 사항(스쿼팅, 설명 오염, 토큰 패스스루)은 모든 소스에서 작동하지만, 런타임 검증(MCPMonitor)은 에이전트가 실제로 MCP 서버를 등록할 때만 작동합니다. OAuth 범위, 세션 하이재킹, SBOM 탐지기는 문서화되어 있지만 구현되지 않았습니다.
• 샌드박스 컨테이너 강화는 범위 밖입니다. 컨테이너 탈출, 이미지 오염, 커널 CVE는 다루지 않습니다.
• 대규모 벤치마크 없음. 이 프레임워크는 하나의 실제 에이전트(CodeWhale)에서 검증되었으며, 표준화된 100개 에이전트 벤치마크는 아직 존재하지 않으며 로드맵에 있습니다.

아키텍처

flowchart LR
    subgraph S1[Stage 1 MODEL]
        A1[AST + Taint Graph] --> A2[agent_model.json]
    end
    subgraph S2[Stage 2 ATTACK]
        B1[Payload Contextualization] --> B2[attack_graph.json]
    end
    subgraph S3[Stage 3 VERIFY]
        C1[Sandbox Replay] --> C2[evidence/*.json]
    end
    subgraph S4[Stage 4 REPORT]
        D1[Verdict Rules R001-R011] --> D2[audit_report.md]
    end
    A2 --> B1
    B2 --> C1
    C2 --> D1

graph TB
    core[core/ — AST extractors, taint trackers, MCP auditor, semantic engine, pattern library]
    payloads[payloads/ — 14 payload categories]
    templates[templates/ — multi-turn attack chains, Jinja2 Dockerfile/compose]
    sandbox[sandbox/ — adapters, executors, 8-layer monitoring, correlation, configs]
    report[report/ — report templates, evidence schema]
    core --> sandbox
    payloads --> sandbox
    templates --> sandbox
    sandbox --> report

빠른 시작

사전 요구 사항

세 가지 모드

# Quick — static only, 5-10 min, CI gate
/AgentStalker --source ./my-agent --mode quick

# Standard — static + attack graph, 30-60 min, pre-release audit
/AgentStalker --source ./my-agent --mode standard

# Deep — full pipeline with sandbox replay, hours, red-team prep
/AgentStalker --source ./my-agent --mode deep \
  --agent-endpoint http://localhost:8000/chat \
  --llm-key sk-xxx

⚠️ 실행 중에는 모드를 다운그레이드할 수 없습니다. 런타임 예산이 부족하면 오케스트레이터는 커버리지를 줄이는 대신 공격 계획을 확장합니다.

테스트 스위트 실행

pip install -e ".[test]"
pytest tests/ -q   # 76 tests, no Docker/eBPF/LLM key needed

정적 모델링 (1단계)