iulianvostrut/contexthoundLLM 프롬프트 인젝션, 데이터 유출, 탈옥(jailbreak), 안전하지 않은 에이전트/도구 취약점을 코드베이스에서 스캔하는 정적 분석 CLI입니다. 완전히 오프라인으로 실행되며, CI/CD와 통합되고, 콘솔, JSON, SARIF 보고서를 출력합니다.
코드베이스에서 LLM 프롬프트 인젝션 및 멀티모달 보안 취약점을 스캔하는 정적 분석 도구입니다. 오프라인으로 실행되며 API 호출이 필요하지 않습니다.
ContextHound는 전체 개발 및 브라우징 워크플로우에서 사용할 수 있습니다:
| 도구 | 기능 | 설치 |
|---|---|---|
| CLI / npm 패키지 | 코드베이스에서 프롬프트 인젝션 취약점을 스캔합니다. GitHub Actions와 통합되며 SARIF, JSON, HTML 등을 출력합니다. | npm install -g context-hound |
| VS Code 확장 | 코딩하는 동안 인라인으로 결과를 표시하고, 코드 액션, 출력 채널, 상태 표시줄을 제공합니다. | VS Code Marketplace |
| 브라우저 확장 | 모든 AI 채팅 인터페이스에서 실시간 스캔 필, LLM API 트래픽용 DevTools 패널, 팝업 스캐너를 제공합니다. Chrome 및 Firefox. | Firefox: 무료 설치 · Chrome: 검토 대기 중 · 소스 |
LLM 기반 애플리케이션이 프로덕션 코드베이스에서 흔해짐에 따라, 프롬프트 인젝션은 가장 악용되기 쉬운 공격 표면 중 하나로 떠올랐습니다. 대부분의 보안 스캐너는 이를 인식하지 못합니다.
ContextHound는 프롬프트 계층에 정적 분석을 도입합니다:
CLI 명령, npm 스크립트, pre-commit 훅 또는 GitHub Action으로 기존 워크플로우에 통합됩니다. 네트워크 호출을 하지 않으며 네 개의 작은 런타임 의존성만 가집니다.
| 122개의 보안 규칙 | 15개 계열에 걸쳐: 인젝션, 유출, 탈옥, 안전하지 않은 도구 사용, 명령 인젝션, RAG 오염, 인코딩 및 숨겨진 콘텐츠, 출력 처리, 멀티모달, 에이전트 스킬, 에이전틱, MCP, 공급망, 리소스 소비, 지속성 |
| OWASP 매핑 | 모든 규칙이 OWASP Top 10 for LLM Applications (2025) 및 Agentic Applications (2026) ID를 가지며, hound explain, --verbose, SARIF 태그 및 모든 보고서에 표시됩니다 |
| 수치 위험 점수 (0-100) | 낮음, 중간, 높음, 심각 임계값을 가진 정규화된 저장소 수준 점수 |
| 완화 조치 탐지 | 프롬프트의 명시적 안전 문구가 점수를 낮춥니다 |
| 9가지 출력 형식 | Console, JSON, SARIF, GitHub Annotations, Markdown, JSONL 스트리밍, 대화형 HTML, CSV 및 JUnit XML |
| GitHub Action 포함 | 위험한 변경 시 CI를 실패시키고, SARIF를 Code Scanning에 업로드하며, 풀 리퀘스트에 요약 댓글을 유지할 수 있습니다 |
| 자동 수정 | hound fix가 숨겨진 유니코드 문자(ENC-002 ~ ENC-005)를 미리 보고 제거합니다 |
| 다국어 스캔 | TypeScript와 JavaScript뿐만 아니라 Python, Go, Rust, Java, C#, PHP, Ruby, Swift, Kotlin, Vue 및 Bash에서 LLM API 사용을 탐지합니다 |
| 규칙 필터링 | 접두사 글롭 구문(CMD-*)을 사용하는 excludeRules/includeRules; minConfidence 필터 |
| 증분 캐시 | .hound-cache.json이 재실행 시 변경되지 않은 파일을 건너뜁니다; --no-cache로 비활성화 |
.gitignore 준수 | git이 무시하는 파일은 건너뜁니다; .houndignore가 동일한 구문으로 제외 항목을 추가합니다 |
| 플러그인 시스템 | 설정의 "plugins": ["./my-rule.js"]를 통해 로컬 .js 파일에서 사용자 정의 규칙을 로드합니다 |
| 베이스라인 / diff 모드 | --baseline results.json은 이전 스캔에 없던 결과만 보고하고 실패시킵니다; --diff는 변경된 파일만 스캔합니다 |
| 감시 모드 | --watch가 파일 변경 시 재스캔하고 델타 결과를 표시합니다 |
| 병렬 스캔 | 동시 파일 처리(--concurrency <n>, 기본값 8) |
| 완전 오프라인 | API 호출 및 텔레메트리 없음 |
전역 설치는 hound 명령을 PATH에 추가합니다:
npm install -g context-hound
프로젝트별 설치는 하나의 저장소에 범위가 지정되며 npx hound 또는 npm 스크립트를 통해 실행됩니다:
npm install --save-dev context-hound
설치 없이, npx가 패키지를 가져와 실행합니다:
npx context-hound scan --dir .
# Scaffold a config file
hound init
# Scan your project
hound scan --dir ./my-ai-project
# Or via npm script (scans current directory)
npm run hound
# Verbose output, shows remediations and confidence levels
hound scan --verbose
# Fail the build on any critical finding
hound scan --fail-on critical
# Export JSON and SARIF reports
hound scan --format console,json,sarif --out results
# GitHub Annotations (for CI step summaries)
hound scan --format github-annotations
# Markdown report with findings tables
hound scan --format markdown --out report
# Stream findings as JSONL (one JSON object per line)
hound scan --format jsonl | jq '.severity'
# List all rules
hound scan --list-rules
# Explain a rule (or a rule family by prefix)
hound explain INJ-001
hound explain PST --format json
# Fast PR gate: scan only files changed vs. origin/main
hound scan --diff
# Interactive HTML report (self-contained, open in browser)
hound scan --format html --out report
# Re-scan on file changes
hound scan --watch
# Parallel scanning (default is 8; tune for your machine)
hound scan --concurrency 16
# Disable incremental cache for a clean run
hound scan --no-cache
# Also scan files that git ignores (skipped by default)
hound scan --no-gitignore
# Preview, then remove, hidden Unicode characters flagged by ENC-002 to ENC-005
hound fix
hound fix --write
# Baseline mode: only report findings new since the last saved scan
hound scan --format json --out baseline # save a baseline
hound scan --baseline baseline.json # compare future scans against it
# Load a custom rule from a local plugin file
hound scan # plugin declared in .contexthoundrc.json "plugins" field
# Only run high-confidence rules
hound scan --config .contexthoundrc.json # set minConfidence: "high"
# Fail if any single file scores >= 40
hound scan --fail-file-threshold 40
# Scan files up to 5 MB (default limit is 1 MiB; 0 = no limit)
hound scan --max-file-size 5242880
종료 코드:
| 코드 | 의미 |
|---|---|
0 | 통과: 점수가 임계값 미만이고 failOn 위반 없음 |
1 | 처리되지 않은 오류 또는 잘못된 인수 |
2 | 임계값 초과: 저장소 점수가 임계값 이상이거나 failFileThreshold를 초과한 파일 존재 |
3 | --fail-on 위반: 해당 심각도 이상의 발견 사항 존재 |
ContextHound Action을 사용하여 모든 푸시와 풀 리퀘스트에서 스캔하고, 발견 사항을 GitHub Code Scanning에 업로드하며, 위험한 변경 사항에 대해 병합을 차단하세요:
# .github/workflows/contexthound.yml
name: Prompt Audit
on: [push, pull_request]
jobs:
hound:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write # SARIF upload to Code Scanning
steps:
- uses: actions/checkout@v7
- uses: IulianVOStrut/ContextHound@v2
with:
fail-on: high
결과는 저장소의 Security > Code scanning 탭과 풀 리퀘스트의 주석(annotation)으로 나타납니다.
| 입력 | 기본값 | 설명 |
|---|---|---|
version | Action에 대응하는 릴리스 | 실행할 정확한 context-hound npm 버전 |
dir | . | 스캔할 디렉터리 |
config | .contexthoundrc.json 파일의 경로 | |
threshold | config 또는 60 | 저장소 점수가 이 값 이상일 때 실패 처리 |
fail-on | 이 심각도 이상의 결과가 있으면 실패 처리: critical, high, medium | |
min-confidence | low, medium, high 신뢰도 이상의 규칙만 보고 | |
diff | 이 git ref와 비교하여 변경된 파일만 스캔, 예: origin/${{ github.base_ref }} (checkout 시 fetch-depth: 0 필요) | |
preset | 쉼표로 구분된 규칙 프리셋, 예: owasp-llm-top10 | |
sarif-out | results.sarif | SARIF 보고서를 기록할 위치 |
upload-sarif | true | 보고서를 Code Scanning에 업로드 |
node-version | 먼저 이 Node.js 버전을 설정 (기본값: 러너의 Node.js 사용) | |
comment | false | 풀 리퀘스트에서 요약 댓글을 게시하고 이후 실행 시 업데이트 ( pull-requests: write 필요) |
github-token | github.token | 풀 리퀘스트 댓글에 사용되는 토큰 |
출력: score, findings, passed, sarif-file로, 이후 단계에서 사용할 수 있습니다.