ContextHound

LLM 기반 애플리케이션의 코드베이스에서 프롬프트 인젝션 및 멀티모달 보안 취약점을 스캔하는 정적 분석 도구입니다. 오프라인으로 실행되며 API 호출이 필요하지 않습니다.

---

ContextHound 생태계

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: 검토 대기 중 · 소스 코드

---

☕ 프로젝트 지원

---

ContextHound가 필요한 이유

LLM 기반 애플리케이션이 프로덕션 코드베이스에서 보편화됨에 따라 프롬프트 인젝션은 가장 악용 가능성이 높은 공격 표면 중 하나로 부상했습니다. 대부분의 보안 스캐너는 이를 인식하지 못합니다.

ContextHound는 프롬프트 계층에 정적 분석을 도입합니다:

• 인젝션 경로가 모델에 도달하기 전에 포착
• 프롬프트에 포함된 유출된 자격 증명 및 내부 인프라 식별
• 시스템 프롬프트에서 탈옥에 취약한 표현 탐지
• 무기화될 수 있는 제약 없는 에이전트 도구 사용 확인
• RAG 코퍼스 중독 및 검색된 콘텐츠가 시스템 명령어로 주입되는 사례 탐지
• 인코딩 기반 밀수 (문자열 필터를 우회하는 Base64 명령어) 포착
• 안전하지 않은 LLM 출력 소비: 스키마 검증 없는 JSON 및 정화 없는 Markdown 식별
• 멀티모달 공격 표면 탐지: 사용자 제공 이미지 URL을 비전 API로 전달, 비전 메시지 파일 읽기를 통한 경로 순회, 프롬프트로 주입되는 전사 출력, 시스템 명령어에 주입되는 OCR 텍스트
• 에이전트 위험 식별: 무제한 에이전트 루프, 검증되지 않은 메모리 쓰기, 계획 인젝션, 시스템 프롬프트 내용을 수신하는 도구 매개변수
• 우수한 보안 관행 보상: 프롬프트에 완화 조치가 포함되면 점수 감소

CLI 명령어, npm 스크립트 또는 GitHub Action으로 기존 워크플로에 통합할 수 있으며, 외부 종속성이 전혀 없습니다.

---

기능

95개의 보안 규칙	인젝션, 유출, 탈옥, 안전하지 않은 도구 사용, 명령어 인젝션, RAG 중독, 인코딩, 출력 처리, 멀티모달, 스킬 마켓플레이스, 에이전트, MCP, 공급망, DoS 등 14개 범주
수치 위험 점수 (0-100)	낮음, 중간, 높음, 심각 임계값이 있는 정규화된 저장소 수준 점수
완화 조치 탐지	프롬프트에 명시적인 안전 언어를 포함하면 점수 감소
7가지 출력 형식	콘솔, JSON, SARIF, GitHub Annotations, Markdown, JSONL 스트리밍, 대화형 HTML
GitHub Action 포함	높은 위험 시 CI 실패 처리, SARIF 결과 자동 업로드
다중 언어 스캔	TypeScript/JavaScript뿐만 아니라 Python, Go, Rust, Java, C#, PHP, Ruby, Swift, Kotlin, Vue, Bash에서 LLM API 사용 탐지
규칙 필터링	접두사-글로브 문법(CMD-*)을 사용한 excludeRules / includeRules, minConfidence 필터
증분 캐시	.hound-cache.json이 변경되지 않은 파일의 재실행을 건너뜀; --no-cache로 비활성화
플러그인 시스템	설정 파일의 "plugins": ["./my-rule.js"]를 통해 로컬 .js 파일에서 사용자 정의 규칙 로드
기준 / 차이 모드	--baseline results.json — 이전 스캔에 없던 결과만 보고 및 실패 처리
감시 모드	--watch — 파일 변경 시 재스캔 및 델타 결과 표시
병렬 스캔	동시 파일 처리 (--concurrency <n>, 기본값 8)
완전 오프라인	API 호출 없음, 텔레메트리 없음, 유료 종속성 없음

---

설치

전역 설치 — hound 명령어를 PATH에 추가합니다:```bash npm install -g context-hound

**프로젝트별 설치** — 하나의 저장소에 범위가 지정됨, `npx hound` 또는 npm 스크립트를 통해 실행됨:```bash
npm install --save-dev context-hound

제로 설치 — 설치가 필요 없으며, 캐시된 npm 레지스트리 사본을 사용합니다:```bash npx context-hound scan --dir .

## 빠른 시작```bash
# 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

# 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

종료 코드:

코드	의미
0	통과 — 점수가 임계값 미만, failOn 위반 없음
1	처리되지 않은 오류 또는 잘못된 인수
2	임계값 위반 — 저장소 점수 ≥ 임계값, 또는 파일 임계값 초과
3	--fail-on 위반 — 지정된 심각도의 발견 사항 발견

---

GitHub Actions

워크플로우에 추가하여 프롬프트 위험이 너무 높을 때 병합을 차단하세요:```yaml

.github/workflows/context-hound.yml

name: Prompt Audit

on: [push, pull_request]

jobs: hound: runs-on: ubuntu-latest permissions: contents: read security-events: write

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: '20'

  - run: npm install -g context-hound

  - run: hound scan --format console,sarif,github-annotations --out results.sarif

  - name: Upload to GitHub Code Scanning
    if: always()
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: results.sarif

발견 사항은 저장소의 **보안 > 코드 스캔** 탭에 표시됩니다. `github-annotations` 형식은 인라인 PR 댓글을 게시하고 GitHub 단계 요약에 요약 테이블을 작성합니다.

---

## 구성