Snyk Agent Scan

머신에 있는 에이전트 구성 요소에서 프롬프트 인젝션과 취약점을 검색하고 스캔합니다
(에이전트, MCP 서버, 스킬 포함).

참고: Agent Scan용 npm 패키지는 게시하지 않습니다. uvx로 설치하거나 독립 실행형 바이너리로 설치하세요.

참고: CLI 출력은 실험적이며 변경될 수 있습니다

Agent Scan v0.5.x (지원 중단 예정)

이 CLI의 원시 출력(이슈 코드, 필드 이름, 심각도 레이블, 응답 구조 포함)은 실험적이며 릴리스 간에 예고 없이 변경될 수 있습니다. 특정 CLI 출력 필드나 이슈 코드에 의존하는 프로덕션 워크플로를 구축하는 것은 권장하지 않습니다.

Agent Scan v0.6 이상

이 CLI의 원시 출력(위험 지표 이름, 점수, 필드 이름, 응답 구조 포함)은 실험적이며 릴리스 간에 예고 없이 변경될 수 있습니다. 특정 CLI 출력 필드나 위험 이름에 의존하는 프로덕션 워크플로를 구축하는 것은 권장하지 않습니다.

Snyk를 사용하여 대규모로 에이전트 보안 위험을 관리하는 엔터프라이즈 고객인 경우, CLI 출력이 Evo 플랫폼으로 전송되어 표시되는 내용과 다를 수 있습니다. 엔터프라이즈 배포를 지원하는 기반 통합, 검색, 위험 평가는 안정적이며 지원됩니다. 모든 변경 사항은 표준 Snyk 제품 관행에 따라 안내됩니다. 배포 지침은 계정 팀에 문의하세요.

NEW 에이전트 스킬 스캔 지원을 추가한 Agent Scan 0.4와 함께 게시된 에이전트 스킬 생태계의 새로운 위협에 대한 기술 보고서를 읽어보세요.

Agent Scan v0.5.x 출력

[!WARNING] Agent Scan v0.5.x는 이슈 코드 출력을 사용합니다. 이 CLI 라인은 지원 중단이 예정되어 있습니다.

Agent Scan v0.6 이상 출력

Agent Scan은 설치된 모든 에이전트 구성 요소(하네스, MCP 서버, 스킬)를 검색하고 프롬프트 인젝션, 민감한 데이터 처리, 자연어에 숨겨진 악성코드 페이로드와 같은 일반적인 위협을 스캔하는 데 도움을 줍니다. --no-skills를 사용하여 스킬에 대한 분석을 무시할 수 있습니다.

보안 경고

⚠️ 중요: MCP 구성을 스캔하면 구성에 정의된 명령이 실행됩니다.

Agent Scan이 MCP 구성 파일을 스캔할 때, 구성에 지정된 명령과 인수를 실행하여 stdio MCP 서버를 시작합니다. 이는 도구 설명을 검색하고 보안 분석을 수행하는 데 필요합니다.

권장 사항:

• 신뢰할 수 없거나 타사 MCP 구성을 평가할 때는 샌드박스(Docker 컨테이너, VM 또는 일회용 환경) 내에서 스캔을 실행하세요
• 대화형 스캔 중에는 동의 프롬프트를 주의 깊게 검토하세요. 각 서버에 대해 실행될 정확한 명령과 인수를 보여줍니다
• **--dangerously-run-mcp-servers**는 모든 MCP 서버 명령을 확인한 신뢰할 수 있는 환경에서만 사용하세요

기본적으로 Agent Scan은 대화형 실행 중 각 stdio MCP 서버를 시작하기 전에 명시적인 사용자 동의(y/n)를 요구합니다. 이를 통해 시스템에서 실행되는 항목을 제어할 수 있습니다.

빠른 시작

Agent Scan을 실행하는 두 가지 방법 중 하나를 선택하세요:

1. 아래 지침에 따라 uvx로 Python 패키지를 실행합니다.
2. GitHub Releases에서 플랫폼에 맞는 독립 실행형 바이너리를 다운로드합니다. 릴리스에는 SBOM, 체크섬, 서명된 체크섬, 소스 코드 아카이브도 포함됩니다.

두 옵션 중 하나를 사용하기 전에:

1. Snyk에 가입하고 https://app.snyk.io/account에서 API 토큰을 받으세요 (API Token → KEY → 클릭하여 표시).
2. 스캔을 실행하기 전에 토큰을 환경 변수로 설정하세요: ```bash export SNYK_TOKEN=your-api-token-here
   root@kitploit:~

uvx로 실행

시스템에 uv가 설치되어 있어야 합니다. 사용 중인 CLI 버전에 맞는 지침을 선택하세요.

Agent Scan v0.5.x

아래 예제는 구체적인 v0.5.x 릴리스로 v0.5.17을 고정합니다:```bash

Scan the whole machine

uvx [email protected]

Scan a specific MCP configuration

uvx [email protected] ~/.vscode/mcp.json

Scan a single agent skill

uvx [email protected] ~/path/to/my/SKILL.md

Scan all Claude skills

uvx [email protected] ~/.claude/skills

> [!WARNING]
> v0.5.x는 issue-code 출력과 `2025-09-02` 분석 API를 사용합니다. 이 CLI 라인은 지원 중단이 예정되어 있습니다.

#### Agent Scan v0.6 이상```bash
# Scan the whole machine
uvx snyk-agent-scan@latest

# Scan a specific MCP configuration
uvx snyk-agent-scan@latest ~/.vscode/mcp.json

# Scan a single agent skill
uvx snyk-agent-scan@latest ~/path/to/my/SKILL.md

# Scan all Claude skills
uvx snyk-agent-scan@latest ~/.claude/skills

v0.6 이상은 위험 기반 출력과 2026-07-10 분석 API를 사용합니다.

두 버전 모두 MCP 서버, 도구, 프롬프트, 리소스, 스킬을 스캔하며, Claude Code/Desktop, Cursor, Gemini CLI, Windsurf와 같은 지원되는 에이전트 구성을 자동으로 탐색합니다.

독립 실행형 바이너리로 실행

최신 GitHub 릴리스에서 운영 체제와 아키텍처에 맞는 바이너리를 다운로드하세요. 릴리스 페이지에서는 SBOM(sbom-<version>.json), 체크섬 파일, GitHub에서 생성된 소스 코드 아카이브도 제공합니다. 다운로드를 검증하려면 독립 실행형 바이너리 검증을 참조하세요.

주요 기능

• MCP 구성, 에이전트 도구, 스킬 자동 탐색
• Claude, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Amp, Amazon Q 및 기타 에이전트 스캔.

Agent Scan v0.5.x

• MCP 서버와 에이전트 스킬 전반에서 15개 이상의 서로 다른 보안 위험을 탐지합니다:
  • MCP: 프롬프트 인젝션, 도구 중독, 도구 섀도잉, 독성 흐름
  • 스킬: 프롬프트 인젝션, 악성 페이로드, 신뢰할 수 없는 콘텐츠, 자격 증명 처리, 하드코딩된 시크릿

Agent Scan v0.6 이상

• MCP 서버와 에이전트 스킬 전반에서 14개의 서로 다른 보안 위험을 탐지합니다:
  • MCP: 프롬프트 인젝션, 신뢰할 수 없는 콘텐츠, 개인 데이터, 파괴적 기능
  • 스킬: 프롬프트 인젝션, 의심스러운 다운로드, 악성 코드, 자격 증명 처리, 시크릿 탐지 등

지원되는 에이전트 및 기능

Agent Scan은 에이전트의 설치 경로가 존재할 때 에이전트와 그 기능(MCP 서버 또는 스킬)을 자동으로 탐색합니다. 아래 표는 각 에이전트가 어떤 운영 체제에서 스캔되는지 보여줍니다.

• ✓: 해당 기능에 대해 최소 하나의 경로가 정의되어 있음.
• ✗: 해당 OS에 에이전트가 나열되어 있지만 해당 기능에 대한 경로가 없음.
• —: 해당 OS에 해당 에이전트가 포함되지 않음.
• 스킬 스킬은 --no-skills를 사용하여 무시할 수 있습니다.

범위별 탐지 범위

위의 매트릭스는 각 에이전트가 어떤 운영 체제에서 스캔되는지 보여줍니다. 이 매트릭스는 탐지를 구성 범위와 구성 요소 유형(스킬 vs MCP 서버)별로 나누어, 운영 체제 전반에 걸쳐 결합한 것입니다. "서버"는 MCP 서버를 의미합니다.

네 가지 범위:

• 시스템 — 모든 사용자에게 적용되는 머신 전체 / 관리자 관리 / 엔터프라이즈 구성 (예: managed-mcp.json, /etc, /Library/Application Support, 또는 ProgramData 아래의 파일).
• 사용자 — 사용자의 홈 디렉터리 구성 (해당 사용자의 모든 프로젝트에 적용).
• 프로젝트 / 워크스페이스 — 열린 프로젝트 또는 워크스페이스에 범위가 지정된 구성.
• 확장 / 플러그인 — 설치된 확장 또는 플러그인 내에 번들로 포함된 구성 요소.

범례: ✓ 탐지됨 · ✗ 에이전트가 이를 지원하지만 Agent Scan이 아직 스캔하지 않음 · N/A 에이전트가 이 범위에 해당 구성 요소가 없음.

† OpenClaw에는 열린 프로젝트 열거 기능이 없습니다: 프로젝트/워크스페이스 스킬은 고정된 ~/.openclaw/workspace/skills에서만 발견됩니다.

‡ Amp는 프로젝트/워크스페이스 스킬을 .agents/skills(및 .claude/skills 호환 경로)에 저장합니다. 현재는 사용자 범위의 ~/.config/agents/skills만 탐지되므로, 프로젝트 범위 스킬은 지원되지만 아직 스캔되지 않습니다.

§ GitHub Copilot은 CLI와 데스크톱 앱을 포함하며, VS Code의 Copilot과 ~/.copilot 홈을 공유하고, VS Code 설치가 아닌 해당 홈에서 탐지됩니다. 자신의 홈을 스캔할 때 COPILOT_HOME 재배치는 존중됩니다. 프로젝트 범위는 저장소 상대 경로인 .mcp.json / .github/mcp.json 파일과 .github/skills, .claude/skills, .agents/skills 디렉터리를 포함하며, 스캔에 전달된 폴더와 Copilot이 permissions-config.json에 기록한 디렉터리 및 그 상위 디렉터리를 대상으로 합니다. 플러그인 범위는 ~/.copilot/installed-plugins를 포함하며, MCP 구성을 재배치하거나 추가 스킬 루트를 선언하는 plugin.json 매니페스트도 포함됩니다. 스캔되지 않음: session-state/*/workspace.yaml의 세션별 프로젝트 루트. Copilot의 사용자 수준 경로는 동일한 파일을 읽는 VS Code 아래에도 나열됩니다.

독립 실행형 바이너리 검증

배포 무결성과 신뢰성을 보장하기 위해 릴리스 체크섬 파일에 GPG 서명을 사용합니다.

단계별 검증 가이드

1. 릴리스 자산 다운로드: GitHub Releases 페이지에서 플랫폼용 바이너리(예: agent-scan-<version>-<os>-<arch>)와 서명된 체크섬 파일(sha256sums.txt.asc)을 같은 디렉터리에 다운로드하세요.

2. 체크섬 파일의 GPG 서명 검증: GPG 공개 키를 같은 디렉터리에 다운로드한 후 다음을 실행하세요: ```bash gpg --import snyk-code-signing-public.pgp gpg --verify sha256sums.txt.asc

   root@kitploit:~

출력에서 gpg: Good signature from "Snyk Limited <[email protected]>"라는 줄을 찾으세요.

3. 바이너리의 무결성을 검증합니다: 서명이 유효한지 확인한 후, 다운로드한 바이너리가 체크섬과 일치하는지 확인하세요:
   • Linux (또는 coreutils가 있는 macOS)에서:
     root@kitploit:~

     grep agent-scan-<version>-<os>-<arch> sha256sums.txt.asc | sha256sum -c -
     

   • macOS (기본 shasum 사용)에서:
     root@kitploit:~

     grep agent-scan-<version>-<os>-<arch> sha256sums.txt.asc | shasum -a 256 -c -
     

   이 명령은 agent-scan-<version>-<os>-<arch>: OK를 출력합니다.

스캐너 기능

Agent Scan v0.5.x

Agent Scan은 머신에 있는 에이전트 구성 요소의 공급망을 스캔하고 검사하는 보안 스캐닝 도구입니다. 프롬프트 인젝션, 도구 중독(tool poisoning), 유해한 흐름(toxic flows), 또는 에이전트 스킬의 취약점과 같은 일반적인 보안 취약점을 스캔합니다.

Agent Scan v0.6 이상

Agent Scan은 프롬프트 인젝션, 신뢰할 수 없거나 사적인 데이터에 대한 노출, 파괴적인 기능, 악성 에이전트 스킬과 같은 위협에 대해 점수가 매겨진 위험 지표를 보고합니다.

Agent Scan은 함께 또는 개별적으로 사용할 수 있는 두 가지 주요 모드로 작동합니다:

1. 스캔 모드: CLI 명령 snyk-agent-scan은 현재 머신에서 에이전트 및 스킬, MCP 서버와 같은 에이전트 구성 요소를 스캔합니다. 완료되면 사용자가 검토할 수 있도록 종합적인 보고서를 출력합니다.

2. 백그라운드 모드 (MDM). Agent Scan은 백그라운드에서 정기적으로 머신을 스캔하고 결과를 Snyk Evo 인스턴스에 보고합니다. 보안 팀이 회사 전체의 에이전트 공급망을 중앙 위치에서 모니터링하는 데 사용할 수 있습니다. 이를 설정하려면 문의해 주세요.

작동 방식

스캔

Agent Scan은 로컬 에이전트의 구성 파일을 검색하여 에이전트, 스킬, MCP 서버를 찾습니다. MCP의 경우 서버에 연결하여 도구 설명을 검색합니다.

MCP 서버에 대한 대화형 동의

⚠️ 보안 참고: MCP 구성을 스캔하면 그 안에 정의된 명령이 실행됩니다. 승인하기 전에 항상 무엇이 실행될지 검토하세요.

기본적으로 Agent Scan은 대화형 실행 중 각 stdio MCP 서버를 시작하기 전에 사용자 동의를 요청합니다. 이 동의 흐름은:

• 실행될 서버 이름, 명령, 환경 변수(가려짐)를 표시합니다
• 각 서버를 개별적으로 승인하거나 거부할 수 있습니다
• 잠재적으로 신뢰할 수 없는 서버가 명시적 허가 없이 실행되는 것을 방지합니다
• 거부된 서버를 user_declined 오류와 함께 기록합니다 (절대 시작되지 않음)

모범 사례:

• 승인하기 전에 명령과 인수를 주의 깊게 검토하세요
• 신뢰할 수 없거나 제3자의 MCP 구성을 스캔할 때는 샌드박스(Docker, VM 또는 일회용 환경) 내에서 Agent Scan을 실행하세요
• 익숙하지 않거나 의심스러운 명령이 있는 서버는 거부하세요

비대화형 환경(예: CI/CD 파이프라인)의 경우, 동의 프롬프트를 우회하고 모든 서버를 자동으로 시작하려면 --dangerously-run-mcp-servers 플래그를 사용해야 합니다. 모든 MCP 서버 명령이 검증된 신뢰할 수 있는 환경에서만 이 플래그를 사용하세요.

분석 및 검증

Agent Scan은 로컬 검사와 Agent Scan API를 통해 발견된 구성 요소를 검증합니다. 분석에 필요한 구성 요소 정보를 전송하며, 여기에는 에이전트 애플리케이션 세부 정보, MCP 서버 구성 및 서명, 도구 이름 및 설명, 스킬 콘텐츠가 포함됩니다. 구성 값과 텍스트의 비밀 정보는 전송 전에 가려집니다.

Agent Scan을 사용함으로써 귀하는 Snyk의 Agent Scan 사용 약관에 동의하게 됩니다.

Agent Scan은 사용 데이터, 즉 MCP 도구 호출의 내용과 결과를 저장하거나 기록하지 않습니다.

CLI 매개변수

전체 플래그 참조는 docs/cli-reference.md에 있습니다. 대부분의 명령과 플래그는 v0.5.x와 v0.6 이상에서 공유됩니다.

공유 명령```text

snyk-agent-scan scan [CONFIG_FILE...] Scan MCP servers and skills (default) snyk-agent-scan inspect [CONFIG_FILE...] Inspect components without analysis snyk-agent-scan help Display help

### 두 버전 라인에서 공통으로 사용되는 옵션

이 옵션들은 v0.5.x와 v0.6 이후 버전 모두에 존재합니다. 각 옵션의 명령 적용 가능 여부는 전체 CLI 레퍼런스에 자세히 설명되어 있습니다.```text
--storage-file FILE               Path to store scan state (default: ~/.mcp-scan)
--analysis-url URL                Analysis endpoint; the default API version depends on the CLI version
--verification-H HEADER           Additional analysis request header (repeatable)
--mcp-oauth-tokens-path PATH      OAuth tokens for protected remote MCP servers
--verbose                         Enable detailed logging
--print-errors                    Show error details and tracebacks
--print-full-descriptions         Show full entity descriptions without truncation
--json                            Emit JSON; the response schema depends on the CLI version
--skip-ssl-verify                 Disable TLS certificate verification
--skills / --no-skills            Include skills (default) or skip them
--scan-all-users                  Scan all readable user home directories
--show-analysis-results           Force synchronous analysis so results display for push-key scans
--ci                              Exit non-zero when findings or operational failures remain
--server-timeout SECONDS          MCP connection timeout (default: 10)
--suppress-mcpserver-io BOOL      Suppress stdio MCP server stderr
--dangerously-run-mcp-servers     Skip consent and start configured stdio MCP servers
--control-server URL              Upload destination (repeatable)
--control-server-H HEADER         Header for the current control-server block
--control-identifier ID           Identifier for the current control-server block
--no-bootstrap                    Accepted compatibility no-op; does not change behavior
--checks-per-server NUM           Accepted compatibility no-op; does not change behavior

Agent Scan v0.5.x

[!WARNING] v0.5.x는 지원 중단이 예정되어 있습니다. 예제에서는 구체적인 v0.5.x 릴리스로 v0.5.17을 고정합니다.```text --analysis-url URL Defaults to the 2025-09-02 analysis API --ignore-issues-codes CODES Comma-separated E/W security finding codes and X failure codes to ignore in CI

v0.5.x는 이슈 코드 발견 항목과 경로 기반 `ScanPathResult` JSON을 출력합니다. [v0.5.x CLI 레퍼런스](https://github.com/snyk/agent-scan/blob/main/docs/cli-reference.md#agent-scan-v05x)와 [이슈 코드 레퍼런스](https://github.com/snyk/agent-scan/blob/main/docs/issue-codes.md)를 참조하세요.

### Agent Scan v0.6 이상```text
--analysis-url URL                Defaults to the 2026-07-10 analysis API
--ignore-risks NAMES              Comma-separated risk names to omit from output and CI evaluation
--ignore-failure-codes CODES      Comma-separated X codes to omit from CI evaluation
--show-full-discovery             List every MCP entity and skill file instead of compact scan summaries

v0.6 이상은 점수가 매겨진 위험 지표와 scan_path_responses JSON을 출력합니다. 사람이 읽을 수 있는 스캔 출력은 기본적으로 간결하며, --show-full-discovery를 사용하면 JSON이나 inspect 출력을 변경하지 않고 확장됩니다. v0.6 이상 CLI 참조, 위험 참조, 실패 코드 참조를 참조하세요.

예시```bash

Scan all known MCP configs and agent skills

snyk-agent-scan

Scan a specific config file or skill

snyk-agent-scan ~/custom/config.json snyk-agent-scan ~/path/to/my/SKILL.md

Inspect without security analysis

snyk-agent-scan inspect

CI mode

snyk-agent-scan --ci --dangerously-run-mcp-servers

## 데모

이 저장소에는 Agent Scan이 보고하는 Model Context Protocol 보안 취약점을 시연하는 취약한 MCP 서버가 포함되어 있습니다.

MCP 보안 취약점을 어떻게 시연하나요?

1. 이 저장소를 클론합니다
2. 클론한 git 저장소 루트 디렉터리에 다음 내용으로 `mcp.json` 설정 파일을 생성합니다:```jsonc
{
  "mcpServers": {
    "Demo MCP Server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp", "run", "demoserver/server.py"],
    },
  },
}

3. 적절한 버전을 실행하세요:

   • Agent Scan v0.5.x (issue-code 출력): uvx --python 3.13 [email protected] scan mcp.json
   • Agent Scan v0.6 이상 (risk-based 출력): uvx --python 3.13 snyk-agent-scan@latest scan mcp.json

참고: mcp.json 구성 파일 경로를 다른 곳에 두는 경우, MCP 서버 구성 내의 args 경로를 MCP 서버(demoserver/server.py) 경로를 반영하도록 조정하고, 올바른 mcp.json 파일 경로로 Agent Scan을 실행하는 uvx 명령도 조정하세요.

Agent Scan은 기여를 받지 않습니다

Agent Scan은 현재 외부 기여를 받지 않습니다.

제안, 버그 보고 또는 기능 요청은 GitHub 이슈로 환영합니다.

개발 환경 설정

소스에서 Agent Scan을 실행하려면 다음 단계를 따르세요:```bash uv run pip install -e . uv run -m src.agent_scan.cli

## 자체 프로젝트 / 레지스트리에 Agent Scan 결과 포함하기

자체 프로젝트나 레지스트리에 Agent Scan 결과를 포함하려면 [문의해 주세요](https://evo.ai.snyk.io/#contact-us). 이를 위한 전용 API가 있습니다. 대규모 스캔에 표준 Agent Scan API를 사용하는 것은 남용으로 간주되어 계정이 차단될 수 있습니다.

## 문서

- [문서 색인](https://github.com/snyk/agent-scan/blob/main/docs/README.md) — 두 CLI 라인에 대한 버전별 문서.
- [CLI 레퍼런스](https://github.com/snyk/agent-scan/blob/main/docs/cli-reference.md) — v0.5.x 및 v0.6-and-later 명령, 플래그, 옵션, 환경 변수.
- [스캐닝](https://github.com/snyk/agent-scan/blob/main/docs/scanning.md) — v0.5.x 및 v0.6-and-later 스캐닝 동작과 예시.
- [JSON 출력](https://github.com/snyk/agent-scan/blob/main/docs/json-output.md) — v0.5.x 경로 키 기반 출력과 v0.6 응답 스키마.
- [이슈 코드](https://github.com/snyk/agent-scan/blob/main/docs/issue-codes.md) — v0.5.x `E*` 및 `W*` 보안 발견 사항 레퍼런스.
- [위험 레퍼런스](https://github.com/snyk/agent-scan/blob/main/docs/risks.md) — v0.6 보안 위험 지표, 점수, 증거 필드.
- [실패 코드](https://github.com/snyk/agent-scan/blob/main/docs/failure-codes.md) — v0.6 운영 탐색, 검사, 분석 실패.

## 추가 자료

- [Introducing MCP-Scan](https://invariantlabs.ai/blog/introducing-mcp-scan)
- [MCP Security Notification Tool Poisoning Attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)
- [WhatsApp MCP Exploited](https://invariantlabs.ai/blog/whatsapp-mcp-exploited)
- [MCP Prompt Injection](https://simonwillison.net/2025/Apr/9/mcp-prompt-injection/)
- [Toxic Flow Analysis](https://invariantlabs.ai/blog/toxic-flow-analysis)
- [Skills Report](https://github.com/snyk/agent-scan/blob/main/.github/reports/skills-report.pdf)

## 변경 이력

[CHANGELOG.md](https://github.com/snyk/agent-scan/blob/main/CHANGELOG.md)를 참조하세요.