ctxsentry

Scan a repository for prompt-injection payloads before you point an AI coding agent at it.

_{Formerly published as ctxguard (≤ 0.3.0); renamed because that name was taken on PyPI.}

The gap this fills

Every current MCP / AI-agent security scanner points outward — it probes a remote MCP server, or audits the agent framework you are building. Almost nothing points inward at the untrusted repository you are about to open in Cursor, Claude Code, Copilot, or Windsurf.

That repo is attacker-influenced text. The moment your agent reads its README.md, CLAUDE.md, .cursorrules, .mcp.json, issue templates, or even a filename, any instructions hidden in that content enter the model's context. Cloud Security Alliance research in 2026 documented "README instruction injection" against coding agents with attack success rates of 41–84%, and MCP tool-description poisoning (CVE-2025-54136) works the same way.

ctxsentry is a fast, dependency-free static scanner that flags that content so a human reviews it first.

→ See docs/walkthrough.md for a worked example: five planted attacks in a sample repo, and the scan that catches every one.

What it detects

Severity is boosted by context: the same string is medium in a source comment but critical in .mcp.json or CLAUDE.md, because agents load those files as authoritative instructions.

Install

pipx install ctxsentry        # recommended
# or
pip install ctxsentry

From source:

git clone https://github.com/EivinDDu/ctxsentry
cd ctxsentry
pip install -e ".[dev]"

Usage

# scan the current repo
ctxsentry scan .

# scan a repo you just cloned, before opening it in your editor
ctxsentry scan ../suspicious-repo

# scan only what changed — fast pre-commit / PR gating
ctxsentry scan . --changed              # vs HEAD (+ staged/unstaged/untracked)
ctxsentry scan . --changed origin/main  # vs a base branch

# machine-readable output
ctxsentry scan . --format json  -o ctxsentry.json
ctxsentry scan . --format sarif -o ctxsentry.sarif   # upload to GitHub code scanning

# gate a pipeline
ctxsentry scan . --fail-on medium --git-history

# tune the noise
ctxsentry scan . --min-severity medium --min-confidence medium

# list every rule
ctxsentry rules

# score the detectors against the labelled corpus
ctxsentry bench

By default ctxsentry only reads files an agent treats as context (docs, rule files, MCP config, *.md, *.txt, config formats). Add --all-text to sweep source files too.

Exit codes

Pre-commit hook

# .pre-commit-config.yaml
- repo: https://github.com/EivinDDu/ctxsentry
  rev: v0.3.0
  hooks:
    - id: ctxsentry             # add: args: ["--changed"] for staged-only scans

GitHub Action

# .github/workflows/ctxsentry.yml
name: ctxsentry
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: EivinDDu/ctxsentry@v0.3.0
        with:
          fail-on: high        # optional (default: high)
          # path: .
          # args: --changed origin/main   # PR-diff-only scan

Suppressing findings

Known-good matches (your own security docs, test fixtures) can be silenced two ways:

• .ctxsentryignore at the scan root — one glob per line, optionally scoped to specific rule ids:

  docs/threat-model.md            # ignore every rule for this file
  examples/**                     # ignore a whole tree
  SECURITY.md:CG101,CG401         # ignore only these rules here
  

• Inline comment on the flagged line or the line above it:

  <!-- ctxsentry: ignore CG401 -- example payload documented on purpose -->
  

How it works

path ─▶ file walk (skips vendored dirs, binaries, >1 MB)
     ─▶ decode (utf-8 / utf-16 / latin-1), keep invisible chars intact
     ─▶ classify context (mcp-config │ agent-instructions │ agent-skill │ docs │ generic)
     ─▶ run detectors:
          • regex rule table           (ctxsentry/rules.py)
          • invisible-Unicode scanner   (decodes U+E00xx tag runs)
          • deobfuscated rescan         (strip zero-width, fold homoglyphs, re-run rules)
          • encoded-payload scanner     (decodes base64 / hex, rescans plaintext)
          • layout / smuggling scanner
          • MCP JSON structure walk
          • filename scanner
     ─▶ context-adjust severity ─▶ sort ─▶ render (text │ json │ sarif │ markdown)

No network calls. No LLM. Deterministic.

Benchmark

ctxsentry bench runs the detectors over a labelled corpus in benchmark/ (20 malicious fixtures across every family, 18 realistic benign ones) and reports precision / recall / F1 / false-positive rate. CI fails the build on any regression:

cases: 38   TP 20  FN 0  FP 0  TN 18
precision 1.000   recall 1.000   F1 1.000   FP-rate 0.000   rule-accuracy 1.000

The benign fixtures are the point — normal READMEs, a SECURITY.md, setup docs that mention API keys, ### System Requirements headings — content that looks adjacent to an attack but must not trip the scanner.

Limitations

• Static pattern matching: a novel paraphrase with no known markers can slip through, and benign security documentation about prompt injection will produce findings (tune with --min-confidence).
• Not a replacement for mcp-scan (runtime MCP), secret scanners, or SAST — it covers the one thing they don't.

Development

pip install -e ".[dev]"
pytest
ctxsentry bench          # detection score against benchmark/

Adding a detector? Add a fixture to benchmark/malicious/ (and a benign counterpart if it could misfire), list it in benchmark/cases.jsonl, and keep ctxsentry bench at 100% recall / 0 false positives.

Releasing is documented in docs/RELEASING.md — tag a version and publish a GitHub Release; CI builds and uploads to PyPI via Trusted Publishing.

License

MIT