ContextHound

Static analysis tool that scans your codebase for LLM prompt-injection and multimodal security vulnerabilities. Runs offline, no API calls required.

---

The ContextHound ecosystem

ContextHound is available across your entire development and browsing workflow:

Tool	What it does	Install
CLI / npm package	Scans your codebase for prompt injection vulnerabilities. Integrates with GitHub Actions, outputs SARIF, JSON, HTML, and more.	npm install -g context-hound
VS Code extension	Inline findings as you code, code actions, output channel, status bar.	VS Code Marketplace
Browser extension	Real-time scan pill on any AI chat interface, DevTools panel for LLM API traffic, popup scanner. Chrome and Firefox.	Firefox: Install free · Chrome: awaiting review · source

---

☕ Support the project

---

Why ContextHound?

As LLM-powered applications become common in production codebases, prompt injection has emerged as one of the most exploitable attack surfaces; most security scanners have no awareness of it.

ContextHound brings static analysis to your prompt layer:

• Catches injection paths before they reach a model
• Flags leaked credentials and internal infrastructure embedded in prompts
• Detects jailbreak-susceptible wording in your system prompts
• Identifies unconstrained agentic tool use that could be weaponised
• Detects RAG corpus poisoning and retrieved content injected as system instructions
• Catches encoding-based smuggling (Base64 instructions that bypass string filters)
• Flags unsafe LLM output consumption: JSON without schema validation and Markdown without sanitization
• Detects multimodal attack surfaces: user-supplied image URLs to vision APIs, path traversal via vision message file reads, transcription output fed into prompts, and OCR text injected into system instructions
• Flags agentic risks: unbounded agent loops, unvalidated memory writes, plan injection, and tool parameters receiving system-prompt content
• Rewards good security practice: mitigations in your prompts reduce your score

It fits into your existing workflow as a CLI command, an npm script, or a GitHub Action, with zero external dependencies.

---

Features

95 security rules	Across 14 categories: injection, exfiltration, jailbreak, unsafe tool use, command injection, RAG poisoning, encoding, output handling, multimodal, skills marketplace, agentic, MCP, supply chain, DoS
Numeric risk score (0-100)	Normalized repo-level score with low, medium, high and critical thresholds
Mitigation detection	Explicit safety language in your prompts reduces your score
7 output formats	Console, JSON, SARIF, GitHub Annotations, Markdown, JSONL streaming, and interactive HTML
GitHub Action included	Fails CI on high risk and uploads SARIF results automatically
Multi-language scanning	Detects LLM API usage in Python, Go, Rust, Java, C#, PHP, Ruby, Swift, Kotlin, Vue, Bash — not just TypeScript/JavaScript
Rule filtering	excludeRules/includeRules with prefix-glob syntax (CMD-*); minConfidence filter
Incremental cache	.hound-cache.json skips unchanged files on re-runs; --no-cache to disable
Plugin system	Load custom rules from local .js files via "plugins": ["./my-rule.js"] in config
Baseline / diff mode	--baseline results.json — only report and fail on findings not present in a prior scan
Watch mode	--watch re-scans on file changes and shows delta findings
Parallel scanning	Concurrent file processing (--concurrency <n>, default 8)
Fully offline	No API calls, no telemetry, no paid dependencies

---

Installation

Global install — adds the hound command to your PATH:

npm install -g context-hound

Per-project install — scoped to one repo, runs via npx hound or an npm script:

npm install --save-dev context-hound

Zero-install — no install needed, uses the cached npm registry copy:

npx context-hound scan --dir .

---

Quick Start

# 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

Exit codes:

Code	Meaning
0	Passed — score below threshold, no failOn violation
1	Unhandled error or bad arguments
2	Threshold breached — repo score ≥ threshold, or file threshold exceeded
3	--fail-on violation — finding of the specified severity found

---

GitHub Actions

Add to your workflow to block merges when prompt risk is too high:

# .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