ctxsentry 0.4.0__tar.gz

ctxsentry-0.4.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# ctxsentry output
+ctxsentry.json
+ctxsentry.sarif
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

ctxsentry-0.4.0/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> Releases before 0.4.0 were published under the name **ctxguard**; that name was
+> already taken on PyPI. Everything below is written with the current name.
+
+## [0.4.0] - 2026-09-08
+
+### Changed
+- **Renamed the project `ctxguard` → `ctxsentry`.** The PyPI distribution, the
+  CLI command, the import package, the ignore file (`.ctxsentryignore`) and the
+  inline suppression marker (`ctxsentry: ignore`) all use the new name. The
+  GitHub repository moved to `EivinDDu/ctxsentry` (old links redirect).
+
+### Added
+- **Published to PyPI** — `pip install ctxsentry` / `pipx install ctxsentry`.
+- `.github/workflows/publish.yml` — tagged releases build an sdist + wheel and
+  publish to PyPI via OIDC Trusted Publishing (no stored token).
+- `docs/RELEASING.md` — the release checklist and one-time PyPI setup.
+- Richer package metadata: per-version Python classifiers, `Repository` /
+  `Changelog` project URLs, and an sdist that ships the tests and benchmark.
+
+## [0.3.0] - 2026-09-06
+
+### Added
+- **Benchmark harness** — `ctxsentry bench` scores the detectors against a
+  labelled corpus in `benchmark/` (38 cases) and reports precision, recall, F1,
+  false-positive rate and per-rule accuracy. `--min-recall` / `--max-fp-rate` /
+  `--min-rule-accuracy` make it a CI gate; CI now fails on any detection
+  regression or new false positive.
+- **`CG406` — deobfuscated rescan.** Zero-width / Unicode-Tag characters are
+  stripped and common Cyrillic/Greek homoglyphs folded to ASCII, then the rule
+  table is re-run. Catches `I​g​n​o​r​e all previous instructions` and
+  `іgnоrе …`-style evasions that defeat a raw regex.
+- **`CG107`** — attempts to make the model disclose its own prompt / prior
+  context (`repeat the text above verbatim`, `what is your system prompt`).
+- **`CG203`** — fake context boundaries and `system override` banners used to
+  inject a task into retrieved / tool-result content.
+- **`CG307`** — DNS-based exfiltration (`dig $(cat …).attacker`).
+- **`CG308`** — exfiltration / persistence via `git remote add` + `git push` to
+  a non-GitHub URL, or a `postinstall` hook that shells out.
+
+### Changed
+- `CG302` callback-URL list extended with tunnel / relay services
+  (`trycloudflare.com`, `loca.lt`, `localtunnel.me`, `serveo.net`, `lhr.life`,
+  `smee.io`, `hookb.in`, `webhookrelay.com`, `dnslog.cn`, `ngrok-free.app`).
+- `CG103` no longer fires on ordinary `### System Requirements`-style headings
+  (needs a bare role header, a trailing colon, or `### System prompt`).
+- `CG802` (instruction-like filename) now needs a real imperative phrase, not
+  just a keyword like `curl` — `curl_download.md` is no longer flagged.
+
+### Fixed
+- Two false positives found by the new benchmark corpus (the `CG103` and
+  `CG802` cases above).
+
+## [0.2.0] - 2026-09-07
+
+### Added
+- `--changed [REF]` — scan only files changed vs `REF` (default `HEAD`) plus
+  staged / unstaged / untracked files. Fast pre-commit and PR-diff gating.
+- Encoded-payload detector: base64 and hex blobs are decoded and the plaintext
+  rescanned (`CG404`, with the decoded text in the finding). `CG403` is now the
+  low-severity "long blob that doesn't decode to text" note.
+- `CG106` — jailbreak / guardrail-removal phrasing (`developer mode`,
+  `do anything now`, `ignore your guidelines`, …).
+- `CG306` — reverse-shell command patterns (`bash -i >& /dev/tcp/…`, `nc -e`,
+  `python -c '…socket…'`).
+
+### Changed
+- `ctxsentry rules` now lists the analytic detectors (`CG4xx`–`CG8xx`) alongside
+  the regex rules.
+- `CG403` moved from the regex table into the encoded-payload detector.
+
+## [0.1.0] - 2026-09-05
+
+Initial release.
+
+### Added
+- `ctxsentry scan <path>` — static scan of a repository for inbound
+  prompt-injection payloads aimed at AI coding agents.
+- Context classifier (`mcp-config`, `agent-instructions`, `agent-skill`,
+  `docs`, `generic`) with per-context severity boosting.
+- Detectors: regex rule table (instruction override, agent-directed
+  imperatives, exfiltration, obfuscation), invisible-Unicode scanner with
+  `U+E00xx` tag-run decoding, bidi / zero-width / PUA / homoglyph detection,
+  layout smuggling, MCP `.mcp.json` structure walk, filename checks.
+- Output formats: `text`, `json`, `sarif` (2.1.0), `markdown`.
+- `--fail-on`, `--min-severity`, `--min-confidence`, `--all-text`,
+  `--git-history`, `--exclude`, `-o/--output`.
+- Suppression via `.ctxsentryignore` and inline `ctxsentry: ignore [RULE…]`
+  comments.
+- `ctxsentry rules` — list all detection rules.
+- CI matrix (Python 3.9–3.13, Linux + macOS); dogfood self-scan and SARIF
+  artifact build on every run.
+- `.pre-commit-hooks.yaml` — usable as a hosted pre-commit repo
+  (`repo: https://github.com/EivinDDu/ctxsentry`, `rev: v0.1.0`).
+- `action.yml` — composite GitHub Action (`uses: EivinDDu/ctxsentry@v0.1.0`)
+  with `path`, `fail-on`, `args`, and `version` inputs.

ctxsentry-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EivinDDu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctxsentry-0.4.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: ctxsentry
+Version: 0.4.0
+Summary: Scan a repository for prompt-injection payloads before you point an AI coding agent at it.
+Project-URL: Homepage, https://github.com/EivinDDu/ctxsentry
+Project-URL: Repository, https://github.com/EivinDDu/ctxsentry
+Project-URL: Issues, https://github.com/EivinDDu/ctxsentry/issues
+Project-URL: Changelog, https://github.com/EivinDDu/ctxsentry/blob/main/CHANGELOG.md
+Author: EivinDDu
+License: MIT
+License-File: LICENSE
+Keywords: ai-security,coding-agent,devsecops,llm-security,mcp,prompt-injection,security-scanner,static-analysis,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ctxsentry
+
+**Scan a repository for prompt-injection payloads *before* you point an AI coding agent at it.**
+
+[![PyPI](https://img.shields.io/pypi/v/ctxsentry)](https://pypi.org/project/ctxsentry/)
+[![CI](https://github.com/EivinDDu/ctxsentry/actions/workflows/ci.yml/badge.svg)](https://github.com/EivinDDu/ctxsentry/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+<sub>Formerly published as `ctxguard` (≤ 0.3.0); renamed because that name was taken on PyPI.</sub>
+
+---
+
+## 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`](docs/walkthrough.md) for a worked example: five
+planted attacks in a sample repo, and the scan that catches every one.**
+
+## What it detects
+
+| Family | Examples |
+|---|---|
+| **Instruction override** | `ignore all previous instructions`, `you are now…`, chat-template tokens (`<system>`, `[INST]`, `<\|im_start\|>`), `do not tell the user`, `<IMPORTANT>` priority markers, jailbreak / guardrail-removal phrasing (`developer mode`, `do anything now`, `ignore your guidelines`) |
+| **Agent-directed imperatives** | sentences addressed to "the AI / assistant / agent" that also name an action (`run`, `curl`, `exfiltrate`, `install`, `push`) |
+| **Data exfiltration & RCE** | instructions to send `.env` / tokens / file contents somewhere, callback URLs (`webhook.site`, `ngrok`, `oast`, `requestbin`…), markdown images with query strings, `curl … \| sh`, reverse-shell one-liners (`bash -i >& /dev/tcp/…`) |
+| **Data exfiltration & RCE** *(cont.)* | DNS exfiltration (`dig $(cat …).attacker`), `git remote add` + `git push` to a non-GitHub URL, `postinstall` hooks that shell out |
+| **Context / prompt disclosure** | `repeat the text above verbatim`, `what is your system prompt`, fake `--- END OF DOCUMENT ---` / `system override:` boundaries injected into retrieved content |
+| **Hidden Unicode** | Unicode **Tag** characters `U+E00xx` (decoded and shown), bidirectional overrides (Trojan Source), zero-width runs, Private-Use-Area smuggling, Latin/Cyrillic/Greek homoglyph words |
+| **Deobfuscated rescan** | strips zero-width / tag characters and folds homoglyphs, then re-runs every rule — catches `I​g​n​o​r​e all previous instructions` and `іgnоrе …` evasions |
+| **Encoded payloads** | base64 / hex blobs are decoded and the plaintext rescanned — a hidden `ignore all previous instructions…` inside a base64 string is surfaced with the decoded text |
+| **Layout smuggling** | instruction text pushed off-screen by whitespace, `display:none` / `color:#fff` / `font-size:0` spans, instruction-bearing HTML comments |
+| **MCP config poisoning** | `.mcp.json` `description` / `instructions` fields carrying hidden directives or secret references; server launch commands that pipe a download into a shell |
+| **Filename injection** | control / invisible / bidi characters in filenames, filenames that spell out an imperative |
+
+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
+
+```bash
+pipx install ctxsentry        # recommended
+# or
+pip install ctxsentry
+```
+
+From source:
+
+```bash
+git clone https://github.com/EivinDDu/ctxsentry
+cd ctxsentry
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# 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
+
+| Code | Meaning |
+|---|---|
+| `0` | completed; nothing at or above `--fail-on` |
+| `1` | findings at or above `--fail-on` (default: `high`) |
+| `2` | usage / runtime error |
+
+### Pre-commit hook
+
+```yaml
+# .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
+
+```yaml
+# .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:
+
+  ```markdown
+  <!-- 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/`](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 `README`s, 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`](https://github.com/invariantlabs-ai/mcp-scan)
+  (runtime MCP), secret scanners, or SAST — it covers the one thing they don't.
+
+## Development
+
+```bash
+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`](docs/RELEASING.md) — tag a
+version and publish a GitHub Release; CI builds and uploads to PyPI via Trusted
+Publishing.
+
+## License
+
+MIT

ctxsentry-0.4.0/README.md

@@ -0,0 +1,221 @@
+# ctxsentry
+
+**Scan a repository for prompt-injection payloads *before* you point an AI coding agent at it.**
+
+[![PyPI](https://img.shields.io/pypi/v/ctxsentry)](https://pypi.org/project/ctxsentry/)
+[![CI](https://github.com/EivinDDu/ctxsentry/actions/workflows/ci.yml/badge.svg)](https://github.com/EivinDDu/ctxsentry/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+<sub>Formerly published as `ctxguard` (≤ 0.3.0); renamed because that name was taken on PyPI.</sub>
+
+---
+
+## 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`](docs/walkthrough.md) for a worked example: five
+planted attacks in a sample repo, and the scan that catches every one.**
+
+## What it detects
+
+| Family | Examples |
+|---|---|
+| **Instruction override** | `ignore all previous instructions`, `you are now…`, chat-template tokens (`<system>`, `[INST]`, `<\|im_start\|>`), `do not tell the user`, `<IMPORTANT>` priority markers, jailbreak / guardrail-removal phrasing (`developer mode`, `do anything now`, `ignore your guidelines`) |
+| **Agent-directed imperatives** | sentences addressed to "the AI / assistant / agent" that also name an action (`run`, `curl`, `exfiltrate`, `install`, `push`) |
+| **Data exfiltration & RCE** | instructions to send `.env` / tokens / file contents somewhere, callback URLs (`webhook.site`, `ngrok`, `oast`, `requestbin`…), markdown images with query strings, `curl … \| sh`, reverse-shell one-liners (`bash -i >& /dev/tcp/…`) |
+| **Data exfiltration & RCE** *(cont.)* | DNS exfiltration (`dig $(cat …).attacker`), `git remote add` + `git push` to a non-GitHub URL, `postinstall` hooks that shell out |
+| **Context / prompt disclosure** | `repeat the text above verbatim`, `what is your system prompt`, fake `--- END OF DOCUMENT ---` / `system override:` boundaries injected into retrieved content |
+| **Hidden Unicode** | Unicode **Tag** characters `U+E00xx` (decoded and shown), bidirectional overrides (Trojan Source), zero-width runs, Private-Use-Area smuggling, Latin/Cyrillic/Greek homoglyph words |
+| **Deobfuscated rescan** | strips zero-width / tag characters and folds homoglyphs, then re-runs every rule — catches `I​g​n​o​r​e all previous instructions` and `іgnоrе …` evasions |
+| **Encoded payloads** | base64 / hex blobs are decoded and the plaintext rescanned — a hidden `ignore all previous instructions…` inside a base64 string is surfaced with the decoded text |
+| **Layout smuggling** | instruction text pushed off-screen by whitespace, `display:none` / `color:#fff` / `font-size:0` spans, instruction-bearing HTML comments |
+| **MCP config poisoning** | `.mcp.json` `description` / `instructions` fields carrying hidden directives or secret references; server launch commands that pipe a download into a shell |
+| **Filename injection** | control / invisible / bidi characters in filenames, filenames that spell out an imperative |
+
+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
+
+```bash
+pipx install ctxsentry        # recommended
+# or
+pip install ctxsentry
+```
+
+From source:
+
+```bash
+git clone https://github.com/EivinDDu/ctxsentry
+cd ctxsentry
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# 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
+
+| Code | Meaning |
+|---|---|
+| `0` | completed; nothing at or above `--fail-on` |
+| `1` | findings at or above `--fail-on` (default: `high`) |
+| `2` | usage / runtime error |
+
+### Pre-commit hook
+
+```yaml
+# .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
+
+```yaml
+# .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:
+
+  ```markdown
+  <!-- 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/`](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 `README`s, 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`](https://github.com/invariantlabs-ai/mcp-scan)
+  (runtime MCP), secret scanners, or SAST — it covers the one thing they don't.
+
+## Development
+
+```bash
+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`](docs/RELEASING.md) — tag a
+version and publish a GitHub Release; CI builds and uploads to PyPI via Trusted
+Publishing.
+
+## License
+
+MIT

ctxsentry-0.4.0/benchmark/benign/api_docs.md

@@ -0,0 +1,11 @@
+# API
+
+## Authentication
+
+Set your API key in the `API_KEY` environment variable, or add it to a local `.env` file:
+
+```
+API_KEY=sk-your-key-here
+```
+
+The client reads the token automatically. Never share your key.

ctxsentry-0.4.0/benchmark/benign/architecture.md

@@ -0,0 +1,3 @@
+# Architecture
+
+The service has three layers: an HTTP handler, a domain layer, and a storage adapter. Requests are validated at the edge and passed as typed commands to the domain layer, which is the only place business rules live.

ctxsentry-0.4.0/benchmark/benign/changelog.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 2.1.0
+
+- Added an `--ignore-case` flag to search.
+- Fixed a crash when the input file was empty.
+- The parser now tolerates trailing commas.

ctxsentry-0.4.0/benchmark/benign/clean_mcp/.mcp.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "./data"
+      ],
+      "tools": [
+        {
+          "name": "read_file",
+          "description": "Read a file from the data directory."
+        },
+        {
+          "name": "list_dir",
+          "description": "List the contents of a directory."
+        }
+      ]
+    }
+  }
+}

ctxsentry-0.4.0/benchmark/benign/code_of_conduct.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+We are committed to a harassment-free experience for everyone. Be respectful. Assume good intent. Report unacceptable behavior to conduct@example.com.