AI 에이전트를 위한 런타임 거버넌스 도구를 만들었습니다 — 왜 당신의 에이전트가 필요로 하는지

Source: Dev.to

당신의 LangChain 에이전트가 rm -rf / 명령을 실행했습니다. 원래는 파일 목록을 출력하려고 했죠.

이것은 가상의 시나리오가 아닙니다. AI 에이전트는 도구—셸 명령, 데이터베이스 쿼리, 결제 API, 파일 작업—를 호출합니다. 모든 도구 호출은 잠재적인 보안 사고가 될 수 있으며, 현재 대부분의 에이전트는 런타임 강제 적용이 전혀 없습니다.

이 문제를 해결하기 위해 ShadowAudit를 만들었습니다. 이것은 결정론적이며 오프라인 우선의 거버넌스 레이어로, 에이전트와 도구 사이에 위치합니다. 호출이 위험 임계값을 초과하면 차단됩니다. LLM 호출도 없고, 클라우드 의존성도 없으며, API 키도 필요하지 않습니다.

pip install shadowaudit

Source: …

문제: 에이전트가 보호되지 않음

AI 에이전트를 만들 때, 쉘, 데이터베이스, 결제 API 등 도구를 제공합니다. 에이전트는 어떤 도구를 어떤 매개변수와 함께 호출할지 스스로 결정합니다— 이것이 바로 자율성의 핵심입니다.

하지만 가드레일 없이 자율성을 부여하는 것은 부주의와 같습니다.

현재 솔루션은 한계가 있다

• 프롬프트 엔지니어링 – “위험한 작업은 하지 말아 주세요.” 에이전트는 이를 무시합니다.
• LLM 기반 가드레일 – 확률적이며, 느리고, 비용이 많이 들며, API 호출이 필요합니다.
• 인간이 개입하는 방식 – 규모에 맞지 않습니다; 시간당 10 000개의 에이전트 결정을 검토할 수 없습니다.

필요한 것은 오프라인에서도 동작하고, 위험한 호출을 실행 전에 차단하는 결정론적 런타임 강제입니다.

ShadowAudit가 하는 일

Agent → ShadowAudit Gate → Tool (allowed)
                         → Blocked (AgentActionBlocked raised)

ShadowAudit는 모든 도구 호출을 위험 분류 체계에 따라 평가합니다. 위험 점수가 임계값을 초과하면 호출이 차단되고, 결정이 로그에 기록되며, 에이전트의 행동 상태가 업데이트됩니다.

5줄의 코드

from langchain.tools import ShellTool
from shadowaudit.framework.langchain import ShadowAuditTool

safe_shell = ShadowAuditTool(
    tool=ShellTool(),
    agent_id="ops-agent-1",
    risk_category="command_execution",
)

safe_shell.run("ls -la")     # ✅ Allowed
safe_shell.run("rm -rf /")   # ❌ AgentActionBlocked raised

원래 도구와 동일한 인터페이스 – 안전한 호출에 대해서는 동작이 전혀 바뀌지 않는 드롭‑인 교체입니다.

CI/CD용 CLI

# Scan your codebase for ungated agent tools
shadowaudit check ./src

# Block deployments if high‑risk tools are ungated
shadowaudit check ./src --fail-on-ungated

# Generate a professional HTML assessment report
shadowaudit assess ./src --taxonomy financial --compliance

# Replay agent traces through the safety gate
shadowaudit simulate --trace-file agent_trace.jsonl --compare

CI 파이프라인에 shadowaudit check --fail-on-ungated를 추가하세요; 게이트가 없는 쉘 도구를 도입하는 커밋은 빌드 실패를 일으킵니다.

아키텍처: 결정론적, 확률적이 아님

오늘날 모든 AI‑안전 도구는 위험을 평가하기 위해 LLM을 사용합니다 – 느리고, 비용이 많이 들며, 비결정론적(같은 입력이 다른 출력을 생성할 수 있음).

ShadowAudit는 플러그인 가능한 전략을 이용한 키워드 기반 점수 매기기를 사용합니다:

1. 분류 체계 조회 – 위험 카테고리 구성(키워드, 임계값 차이, 심각도)을 찾습니다.
2. 점수 매기기 – 플러그인 가능한 스코어러가 페이로드 내용으로부터 위험 점수를 계산합니다.
3. 임계값 비교 – 점수와 분류 체계 차이를 비교하여 통과/실패를 결정합니다.
4. FSM 전이 – 실패 시 차단 상태 머신: 명시적으로 통과된 경우가 아니면 모두 차단됩니다.
5. 감사 로그 – 결정이 타임스탬프, 에이전트 ID, 페이로드 해시, 사유와 함께 기록됩니다.
6. 상태 업데이트 – K(신뢰)와 V(속도) 메트릭이 적응형 점수 매기기를 위해 업데이트됩니다.

그 결과는 감사 가능하고, 재현 가능하며, 설명 가능하여 규정 준수 감사인이 실제로 받아들이는 증거가 됩니다.

Why Offline‑First Matters

ShadowAudit는 완전히 오프라인으로 작동합니다 (SQLite‑백업 상태). Redis도 없고, 클라우드도 없으며, API 키도 필요하지 않습니다.

귀하의 거버넌스 도구가 인터넷 연결을 필요로 한다면, 이미 이러한 고객들을 잃은 것입니다.

사전 구축된 분류 체계

ShadowAudit는 세 가지 시작 분류 체계를 제공합니다:

각 분류 체계는 조정된 임계값을 가지고 있습니다. 사용자 정의 분류 체계를 대화식으로 만들 수 있습니다:

shadowaudit build-taxonomy

Framework Support

두 어댑터는 덕 타이핑을 사용하므로 ShadowAuditTool을 교체하려면 import만 바꾸면 코드 변경이 필요하지 않습니다.

The Numbers

• 133개의 테스트, 100 % 통과율
• 플레이키 테스트 제로 — 설계상 결정적
• ruff + mypy 클린 — 첫날부터 엄격한 린팅
• MIT 라이선스 — 사용하고, 수정하고, 확장하세요
• Python 3.10+ — 레거시 부담 없는 최신 파이썬

다음 단계

ShadowAudit은 alpha (v0.3.2) 단계에 있습니다. 핵심 게이트, CLI, 프레임워크 어댑터 및 평가 도구가 기능을 수행하며 테스트되었습니다. 다음은 로드맵입니다:

• 🔜 AutoGen 어댑터
• 🔜 행동 이상 탐지 — 세션 간 패턴 탐지
• 🔜 Pro 대시보드 — 팀 수준 가시성, 컴플라이언스 보고서, 알림
• 🔜 더 많은 분류 체계 — 의료, 방위, 전자상거래

사용해 보기

pip install shadowaudit

📖 GitHub
📦 PyPI
📁 Examples

AI 에이전트는 다음 공격 표면입니다. 사고가 발생하기를 기다리지 말고 관리하십시오.

작성자: Anshuman Kumar. MIT 라이선스. 오프라인에서도 작동합니다.