agent-shield-runtime v0.1.0: 5가지 AI 에이전트 방어 센서를 연결하는 배포 훅 (hook)

에이전트의 방어 센서는 아무것도 호출하지 않는다면 무용지물입니다. 이 저장소(repo)는 모든 도구 호출(tool-call)을 가로채어 실행하기 전에 5가지 센서로 평가합니다.

문제점

AI 에이전트 방어 생태계(scope-lib, adi-shield, wallet-guard, goal-anchor, trajectory-sentinel)에서 5가지 센서는 이미 구현되어 있고 감사(audit)를 마쳤습니다. 하지만 이들은 라이브러리일 뿐입니다. 실제 에이전트에서 아무도 이들을 호출하지 않습니다. 패키지가 설치되어 있더라도 훅(hook)이 없다면, 에이전트는 도구 호출(tool-calls)을 직접 실행하며 센서들은 디스크에 머물러 있게 됩니다. 단위 테스트(unit tests)에서 보여준 탐지 기능이 프로덕션(production) 환경에서는 발생하지 않는 것입니다.

해결책

agent-shield-runtime은 여섯 번째 저장소입니다. 에이전트의 **모든 도구 호출(tool-call)**을 가로채어 실행하기 전에 5가지 센서로 순서대로 전달하는 배포 훅(deployment hook)입니다:

1. scope-lib — 범위 평가 (3가지 기준, fail-safe).
2. adi-shield — 5가지 벡터를 통한 프롬프트 인젝션(ADI, prompt injection) 탐지.
3. wallet-guard — 루프 및 예산 가드레일 (guardrails).
4. goal-anchor — 목표 무결성 (급격한 이탈).
5. trajectory-sentinel — 공유 버스를 통한 신호의 통합 상관관계 분석.

만약 어떤 센서라도 block을 반환하면, 해당 동작은 실행되지 않습니다. confirm이 발생하면 인간의 확인을 위해 일시 중지됩니다. 모든 센서가 allow를 반환할 때만 네이티브 도구(native tool)가 실행됩니다.

작동 방식

런타임(runtime)은 에이전트의 실행기(executor)를 감쌉니다. 핵심 코어는 GenericToolCall만을 알고 있으며, 프레임워크 어댑터(LangChain, AutoGen, 자체 루프)가 네이티브 도구 호출(native tool-call)을 해당 형식으로 번역하여 격리된 상태로 존재합니다. 이를 통해 런타임은 특정 에이전트에 결합(coupling)되지 않고 재사용 가능하며, 5가지 센서 또한 변경할 필요가 없습니다. 이 저장소는 오직 오케스트레이션(orchestration)만을 수행합니다.

검증된 결과

• 설치된 5개의 실제 (REAL) 센서(센서 모킹(mock) 없이)를 대상으로 한 5개의 엔드투엔드 (end-to-end) 통합 테스트 (tests/test_integration_e2e.py): AC1 (차단 시 거부 및 실행 안 함), AC2 (ADI 주입 차단), AC3 (급격한 드리프트 확인), AC5 (센서 수정 없는 통합).
• 깨끗한 환경에서의 GitHub Actions CI 통과 (ruff + pytest + bandit + gitleaks).
• AGPL-3.0-or-later 라이선스 (FSF 공식 텍스트 그대로 사용).

남겨진 과제 (솔직하게)

• 미세한 WebTrap은 해결되지 않았습니다. 이 훅(hook)은 탐지 범위를 확장하는 것이 아니라 _배포 커버리지 (deployment coverage)_를 확장합니다. 범위의 외관을 유지하는 미세한 드리프트 벡터(T1/T2/T4)는 goal-anchor의 레이어 1(Layer 1)에서 여전히 탐지되지 않습니다 (수정된 벤치마크: 실제 TPR=0.25, FPR=0.0). 이를 해결하려면 실제 의미론적(semantics) 분석이 필요하지만, 현재 단계에서는 무게감 문제로 제외되었습니다.
• 실제 프레임워크 어댑터 대기 중. 현재는 범용 어댑터만 존재하며, LangChain/AutoGen의 네이티브 실행기(executor)와 연결하는 것이 다음 이정표(H3)입니다.
• 독립적인 감사 진행 중. 외부 감사자가 저장소를 클론하여 신선한 상태에서 검증할 수 있도록 저장소를 공개했습니다.

테스트해보기

git clone https://github.com/amurlaniakea/agent-shield-runtime.git
cd agent-shield-runtime
python -m venv .venv && . .venv/bin/activate
...

스택 (Stack)

링크

• Repo: https://github.com/amurlaniakea/agent-shield-runtime
• 센서: scope-lib, adi-shield, wallet-guard, goal-anchor, trajectory-sentinel

라이선스: AGPL-3.0-or-later · 저자: Pedro Sordo Martínez