AgentShield
배포하기 전에 MCP 및 AI 에이전트 확장 기능에서 위험한 동작을 찾아냅니다.
CI
Release
Website
License: MIT OR Apache-2.0
Crates.io
VS Code
Open VSX
docs.rs
AgentShield는 최신 AI 스택 전반에 걸쳐 도구 사용이 가능한(tool-enabled) AI 에이전트를 배포하는 팀을 위한 오프라인 고성능 Rust 보안 엔진입니다. 네이티브 어댑터는 MCP 서버, OpenClaw 스킬, Hermes Agent 설정, CrewAI, LangChain/LangGraph, GPT Actions, 그리고 Cursor Rules를 지원합니다. 동일한 검사는 OpenAI Agents SDK, Claude Code, Claude Desktop MCP 설정, 브라우저 사용(Browser Use), FastMCP, GitHub MCP 서버, Playwright MCP 및 기타 도구 중심 워크플로우를 기반으로 구축된 저장소를 강화하는 데 도움을 줍니다.
이 엔진은 에이전트가 해당 도구를 호출하기 전에 명령어 주입(command injection), 자격 증명 유출(credential exfiltration), SSRF(Server-Side Request Forgery), 안전하지 않은 파일 접근(unsafe file access), 런타임 패키지 설치, 프롬프트 주입 표면(prompt-injection surfaces), 그리고 의존성 위생 문제(dependency hygiene issues)를 포착합니다.
AgentShield는 CLI, GitHub Action, VS Code 확장 프로그램 또는 Rust 라이브러리로 실행됩니다. 이 엔진은 소스 코드를 사용자의 장치에 유지하는 방식으로 100% 오프라인으로 작동하며, 콘솔, JSON, GitHub Code Scanning용 SARIF, 그리고 독립형 HTML 보고서를 출력합니다. 현재 배포 버전은 1.0.3(일반 사용 가능)입니다.
한눈에 보기
AgentShield: 배포 전 MCP 및 AI 에이전트 확장 기능의 위험 행위 탐지
| Area | AgentShield가 수행하는 작업 |
|---|
| 스캐너 표면 (Scanner surface) | 11가지 프레임워크/클라이언트 패밀리를 하나의 IR(중간 표현, Intermediate Representation)로 표준화합니다: MCP, OpenClaw, Hermes Agent, CrewAI, LangChain/LangGraph, GPT Actions, Cursor Rules, Vercel AI SDK, AutoGen, LlamaIndex, Semantic Kernel. |
| ... | |
런타임 가드(runtime guard) 범위 및 로드맵은 docs/RUNTIME_GUARD.md를 참조하십시오.
연동 가능 환경 (Works With)
AgentShield는 에이전트가 로컬 도구(local tools), 원격 API(remote APIs), 브라우저 자동화, 파일 작업, 셸 명령어 또는 MCP 서버를 호출할 수 있는 모든 곳에서 유용합니다.
왜 AgentShield인가요? (Why AgentShield?)
AI 에이전트들은 명령을 실행하고, 파일을 읽고 쓰며, HTTP 요청을 수행하고, 패키지를 설치하며, 외부 서비스를 호출할 수 있는 도구들과 연결되고 있습니다. 단 하나의 악성 또는 코딩이 미흡한 확장 기능만으로도 다음 행위가 가능합니다:
- 자격 증명(credentials) 유출: 환경 변수나 로컬 비밀 파일(secret files)을 읽어 공격자가 제어하는 엔드포인트로 전송할 수 있습니다.
- 임의 명령 실행: 사용자 제어 입력값을 셸 또는 프로세스 API에 전달하여 임의 명령을 실행할 수 있습니다.
- 런타임 백도어 설치: 도구 핸들러 내부에서 패키지 관리자 호출을 통해 런타임(runtime) 시 백도어를 설치할 수 있습니다.
- SSRF 요청 프록시: 도구 인자로부터 파생된 URL을 가져와 SSRF(Server-Side Request Forgery) 요청을 프록시할 수 있습니다.
- 민감 데이터 모델 컨텍스트 유출: 보호되지 않은 프롬프트, 도구 결과 또는 규칙 파일을 통해 민감한 데이터를 모델 컨텍스트(model context)로 유출할 수 있습니다.
AgentShield는 정적 분석(static analysis), 프레임워크 어댑터(framework adapters), 정책 평가(policy evaluation), 억제(suppressions), 기준선(baselines), 이그레스 정책 생성(egress policy generation), 증명서(attestations) 및 GitHub Code Scanning을 위한 SARIF 출력을 통해 이러한 패턴들을 포착합니다.
일반 보안 스캐너와 함께 사용하세요
AgentShield는 범용 보안 도구들을 보완하는 역할을 하며, SAST(정적 애플리케이션 보안 테스트), 비밀 정보 스캐닝 또는 광범위한 의존성 분석을 대체하는 것은 아닙니다. 실질적인 보안 스택은 다음과 같습니다:
| Tool | 주요 커버리지 | AgentShield를 유지해야 하는 이유 |
|---|
| CodeQL | 코드 취약점 및 품질 문제에 대한 일반 SAST | CodeQL은 범위가 넓지만, AgentShield는 MCP 도구, 프롬프트, 도구 스키마, 그리고 이그레스(egress)와 같은 에이전트/도구 표면을 모델링합니다. |
| ... | | |
사용자가 CodeQL, Gitleaks, Semgrep CE, 그리고 AgentShield를 함께 실행하는 시작용 GitHub Actions 워크플로우를 원할 때 agentshield ci install --suite를 사용하십시오. | | |
비교 분석 (How it compares)
| 기능 | AgentShield | mcp-scan | Invariant Labs |
|---|
| Rust 단일 바이너리 | 예 | 아니오 | 아니오 |
| ... | | | |
빠른 시작 (Quick Start)
VS Code 확장 프로그램 (VS Code Extension)
인라인 보안 진단 및 전구 모양의 빠른 수정 기능을 위해 AgentShield VS Code 확장 프로그램을 설치하십시오:
- 인라인 진단: 코드를 입력하거나 파일을 저장할 때 발견된 취약점이 강조 표시됩니다.
- 전구 모양의 빠른 수정 기능 (
Cmd + . / Alt + Enter): 안전하지 않은 역직렬화기(yaml.load $ o$ safe_load) 및 고정되지 않은 의존성에 대한 즉각적인 1클릭 복구 기능을 제공합니다.
- 상호작용적 제외(Interactive Suppressions): 근거를
.agentshield.toml에 직접 저장하여 오탐을 무시할 수 있습니다.
GitHub Action
.github/workflows/security.yml 파일에 추가하십시오:
name: Agent Security
on: [push, pull_request]
...
SARIF 업로드가 활성화되면 발견된 취약점은 PR 주석 및 저장소의 보안 > 코드 스캐닝 탭에 나타납니다.
이 Action은 path가 하위 디렉터리인 경우에도, 자체 저장소를 스캔하기 때문에 .agentshield.toml과 agentshield/rules를 찾아 적용합니다. 다른 설정 파일을 지정하려면 config 입력을 사용하십시오.
[!중요]
보안 팀 없이 빠르게 배포하고 계신가요?
AgentShield에 ⭐ 별표를 주어 북마크 해 주세요. 다음 배포 전에 50ms 스캔을 실행하여 절대로 악성 도구나 유출된 자격 증명을 프로덕션으로 푸시하지 않도록 하십시오.
CLI
curl -fsSL https://aiconnai.github.io/agentshield/install.sh | sh
...
Pre-commit Hook
.pre-commit-config.yaml에 AgentShield를 추가하여 커밋(commit) 전에 취약한 도구를 차단할 수 있습니다:
repos:
- repo: https://github.com/aiconnai/agentshield
rev: v1.0.3
...
Python SDK
AgentShield를 테스트 스위트(test suites) 또는 도구 정의에 직접 통합할 수 있습니다.
[!NOTE]
agent-shield Python 패키지는 아직 PyPI에 게시되지 않았습니다. 소스에서 설치해야 합니다. 빌드 과정에서 스캐너가 컴파일되므로 Rust 툴체인(toolchain)이 필요하며, 이 과정을 통해 agentshield 모듈과 agentshield 바이너리 두 가지 모두가 설치됩니다:
pip install "git+https://github.com/aiconnai/[email protected]"
import agentshield
from agentshield import shield
...
게시된 crates.io 버전에서 정적 스캐닝(static scanning)만 필요하다면, cargo install agent-shield도 지원됩니다. crates.io가 업데이트되기 전에 최신 릴리스 라인이 필요할 때는 위의 GitHub 태그 명령을 사용하십시오.
Pre-built binaries
Linux, macOS 및 Windows 타겟용은 최신 릴리스(latest release)에서 다운로드하십시오.
컨테이너 사용자(container consumers)를 위한 릴리스 이미지 태그는 다음과 같습니다:
ghcr.io/aiconnai/agentshield:1.0.3
Docker
GHCR 이미지는 런타임 wrap 지원 및 실험적인 런타임 가드 명령을 포함하여 full 기능 세트로 빌드됩니다. 이 이미지는 linux/amd64와 linux/arm64용으로 게시되었습니다.
docker pull ghcr.io/aiconnai/agentshield:1.0.3
docker run --rm -v "$PWD:/scan" ghcr.io/aiconnai/agentshield:1.0.3 scan .
docker run --rm ghcr.io/aiconnai/agentshield:1.0.3 --version
만약 GHCR 패키지가 조직 내에서 비공개(private)인 경우, 먼저 인증해야 합니다:
gh auth refresh -h github.com -s read:packages
gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdin
From source
git clone https://github.com/aiconnai/agentshield.git
cd agentshield
cargo build --release
...
RTK를 사용한 토큰 최적화 로컬 검사 (Token-Optimized Local Checks with RTK)
AgentShield는 로컬 개발 중, 특히 cargo test, cargo clippy, 그리고 JSON 또는 SARIF를 방출하는 스캐너 실행 시 노이즈가 많은 명령어 출력을 생성할 수 있습니다. 만약 rtk가 설치되어 있다면, 사람과 코딩 에이전트에게 표시되는 출력을 줄이기 위해 선택적 래퍼(wrapper)를 사용하십시오:
scripts/rtk-check.sh quick
scripts/rtk-check.sh test
scripts/rtk-check.sh clippy
...
이 래퍼는 의도적으로 로컬 전용입니다. RTK는 오직 로컬 명령어 출력만 필터링합니다. 사용자가 소비하는 AgentShield의 JSON, SARIF, HTML 또는 콘솔 출력 계약(contracts)을 변경해서는 안 되며, 이는 클라이언트, CI, 또는 GitHub Code Scanning에 해당됩니다.
디버깅, 감사(audit), 보안 결정에는 원시 출력을 사용하십시오:
scripts/rtk-check.sh raw -- cargo test
scripts/rtk-check.sh raw -- cargo run -- scan tests/fixtures/mcp_servers/safe_calculator --format sarif --output target/agentshield/scan.sarif
정책:
- 빠른 로컬 피드백을 위해 필터링된 출력을 사용하십시오.
- 테스트 실패, 파서 버그(parser bugs), 탐지기 동작(detector behavior) 또는 보안에 민감한 발견 사항을 조사할 때는 원시 출력을 사용하십시오.
- 클라이언트나 CI가 이를 소비하는 경우 항상 완전한
json 및 sarif 보고서를 파일에 작성하십시오.
지원되는 프레임워크 (Supported Frameworks)
AgentShield는 리포지토리 내에서 일치하는 모든 어댑터(adapters)를 실행하며, 첫 번째 일치 항목에서 중단되지 않습니다.
| 프레임워크 | 상태 | 어댑터 커버리지 |
|---|
| MCP (Model Context Protocol) | 지원됨 | MCP 서버 매니페스트, Python/TypeScript/JavaScript 소스, 도구 스키마, 종속성, 출처(provenance) |
| ... | | |
CLI 명령어 (CLI Commands)
| Command | Purpose |
|---|
agentshield discover | 실행(execution), 네트워크 접근(network access) 또는 자동 스캔 없이 허용 목록에 지정된 로컬 클라이언트 구성 경로를 읽습니다. 동의 및 출력을 제어하려면 --no-default-paths, 반복되는 --root, --format console|json, 그리고 --explain을 사용하십시오. |
유용한 scan 옵션에는 --config, --rules-dir, --trust-target-config, --format, --fail-on, --output, --ignore-tests, --explain, --experimental-risk, --baseline, --write-baseline, 그리고 --emit-egress-policy가 포함됩니다.
구성된 [scan] include 및 [scan] exclude 필터는 탐지기(detectors)가 실행되기 전에 소스 및 메타데이터 기반의 발견 사항을 범위 지정합니다.
기존 발견 사항이 있는 성숙한 저장소의 경우, 먼저 베이스라인(baseline)을 작성하고 CI에서 사용하십시오:
agentshield scan --write-baseline .agentshield-baseline.json
agentshield scan --baseline .agentshield-baseline.json --explain
agentshield ci install --baseline .agentshield-baseline.json
--explain은 의도적으로 콘솔 전용입니다. JSON, SARIF 또는 HTML 출력에 텍스트를 추가하지 않습니다. Explain 출력에는 스캔 루트(scan root), 메타데이터 루트(metadata root)가 다를 경우 해당 내용, 그리고 집중된 차단 발견 사항에 대한 핫스팟 요약이 포함됩니다.
--experimental-risk는 별도의 콘솔/JSON 전용 모드이며 --explain과 결합할 수 없습니다. 이 버전별 인덱스는 정보 제공용입니다: 이는 발견 사항, PASS/FAIL, 정책 임계값(policy thresholds), 베이스라인, 억제(suppressions) 또는 프로세스 종료 상태를 변경하지 않습니다. SARIF, HTML 및 DSSE는 변경되지 않습니다.
탐지 규칙 (Detection Rules)
AgentShield는 명령어 실행, 데이터베이스 도구에서의 SQL 인젝션, 시스템 프롬프트 주입 표면(system prompt injection surfaces), 안전하지 않은 네트워크 바인드(insecure network binds), 안전하지 않은 임시 파일 생성, 자격 증명 유출(credential exfiltration), 복합 독성 흐름(composite toxic flows), 웹훅을 통한 로컬 파일 유출, SSRF, 임의 파일 접근, 런타임 패키지 설치, 프롬프트 주입 표면, 과도한 기능(excessive capabilities), 의존성 위생 관리(dependency hygiene), 동적 코드 실행, 메타데이터 서비스 접근, 안전하지 않은 역직렬화(unsafe deserialization), 안전하지 않은 에이전트 체크포인트, 인증되지 않은 MCP SSE 전송, 도구 응답 프롬프트 주입, 에이전트 메모리 오염, 그리고 비밀 정보 유출을 포괄하는 37개의 내장 컨텍스트 규칙(SHIELD-001..037)을 제공합니다.
설치된 버전의 권위 있는 규칙 목록은 CLI를 사용하십시오:
agentshield list-rules
agentshield list-rules --format json
사용자 정의 선언적 규칙(Custom Declarative Rules)
