ctxsentry 0.4.0__py3-none-any.whl

ctxsentry/__init__.py

@@ -0,0 +1,13 @@
+"""ctxsentry - inbound prompt-injection scanner for AI coding agents.
+
+ctxsentry inspects the files an AI coding agent ingests the moment it opens a
+repository (READMEs, docs, issue text, agent rule files, ``.mcp.json`` tool
+descriptions, filenames) and reports content that looks engineered to hijack
+the agent: instruction overrides, invisible Unicode, HTML smuggling, and
+data-exfiltration primitives.
+"""
+
+from ctxsentry.finding import Finding, Severity
+
+__version__ = "0.4.0"
+__all__ = ["Finding", "Severity", "__version__"]

ctxsentry/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from ctxsentry.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ctxsentry/benchmark.py

@@ -0,0 +1,121 @@
+"""Score ctxsentry against a labelled corpus.
+
+The corpus lives in ``benchmark/`` at the repo root: ``cases.jsonl`` lists each
+fixture with a label (``malicious`` / ``benign``) and, for malicious cases, the
+rule id that *should* fire. ``run_benchmark`` scans every fixture and returns
+precision / recall / F1 / false-positive-rate plus a list of the individual
+mismatches, so "is it better?" has a number behind it.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+from ctxsentry.scanner import ScanConfig, scan
+
+DEFAULT_BENCH_DIR = Path(__file__).resolve().parents[2] / "benchmark"
+
+
+@dataclass(frozen=True)
+class Case:
+    path: str
+    label: str  # "malicious" | "benign"
+    expect_rule: Optional[str] = None
+    note: str = ""
+
+
+@dataclass
+class BenchResult:
+    tp: int = 0  # malicious, flagged
+    fn: int = 0  # malicious, missed
+    fp: int = 0  # benign, flagged
+    tn: int = 0  # benign, clean
+    rule_expected: int = 0
+    rule_hit: int = 0  # malicious case where the *named* rule fired
+    misses: List[tuple] = field(default_factory=list)  # (case, reason)
+
+    @property
+    def total(self) -> int:
+        return self.tp + self.fn + self.fp + self.tn
+
+    @property
+    def precision(self) -> float:
+        d = self.tp + self.fp
+        return self.tp / d if d else 1.0
+
+    @property
+    def recall(self) -> float:
+        d = self.tp + self.fn
+        return self.tp / d if d else 1.0
+
+    @property
+    def f1(self) -> float:
+        p, r = self.precision, self.recall
+        return 2 * p * r / (p + r) if (p + r) else 0.0
+
+    @property
+    def fp_rate(self) -> float:
+        d = self.fp + self.tn
+        return self.fp / d if d else 0.0
+
+    @property
+    def rule_accuracy(self) -> float:
+        return self.rule_hit / self.rule_expected if self.rule_expected else 1.0
+
+    def to_dict(self) -> dict:
+        return {
+            "counts": {"tp": self.tp, "fn": self.fn, "fp": self.fp, "tn": self.tn},
+            "precision": round(self.precision, 4),
+            "recall": round(self.recall, 4),
+            "f1": round(self.f1, 4),
+            "fp_rate": round(self.fp_rate, 4),
+            "rule_accuracy": round(self.rule_accuracy, 4),
+            "misses": [{"path": c.path, "reason": reason} for c, reason in self.misses],
+        }
+
+
+def load_cases(bench_dir: Path = DEFAULT_BENCH_DIR) -> List[Case]:
+    manifest = bench_dir / "cases.jsonl"
+    cases: List[Case] = []
+    for line in manifest.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        cases.append(Case(**json.loads(line)))
+    return cases
+
+
+def run_benchmark(bench_dir: Path = DEFAULT_BENCH_DIR) -> BenchResult:
+    res = BenchResult()
+    for case in load_cases(bench_dir):
+        target = (bench_dir / case.path).resolve()
+        findings = scan(ScanConfig(root=target)).findings
+        rule_ids = {f.rule_id for f in findings}
+
+        if case.label == "malicious":
+            if findings:
+                res.tp += 1
+            else:
+                res.fn += 1
+                res.misses.append((case, "false negative: no finding"))
+            if case.expect_rule:
+                res.rule_expected += 1
+                if case.expect_rule in rule_ids:
+                    res.rule_hit += 1
+                else:
+                    got = ", ".join(sorted(rule_ids)) or "nothing"
+                    res.misses.append(
+                        (case, f"expected {case.expect_rule}, got {got}")
+                    )
+        else:
+            if findings:
+                res.fp += 1
+                res.misses.append(
+                    (case, "false positive: " + ", ".join(sorted(rule_ids)))
+                )
+            else:
+                res.tn += 1
+    return res

ctxsentry/cli.py

@@ -0,0 +1,249 @@
+"""Command-line entry point for ctxsentry."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from ctxsentry import __version__
+from ctxsentry.finding import Severity
+from ctxsentry.report import render
+from ctxsentry.rules import RULES
+from ctxsentry.scanner import DEFAULT_MAX_BYTES, ScanConfig, scan
+
+_EPILOG = """\
+exit codes:
+  0  scan completed, nothing at or above --fail-on
+  1  findings at or above --fail-on severity
+  2  usage / runtime error
+
+examples:
+  ctxsentry scan .
+  ctxsentry scan ../some-repo --format sarif -o ctxsentry.sarif
+  ctxsentry scan . --fail-on medium --git-history
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ctxsentry",
+        description=(
+            "Scan a repository for prompt-injection payloads before you point "
+            "an AI coding agent at it."
+        ),
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"ctxsentry {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan_p = sub.add_parser("scan", help="scan a path", description="Scan a file or directory.")
+    scan_p.add_argument("path", nargs="?", default=".", help="file or directory (default: .)")
+    scan_p.add_argument(
+        "-f",
+        "--format",
+        default="text",
+        choices=["text", "json", "sarif", "markdown"],
+        help="output format (default: text)",
+    )
+    scan_p.add_argument("-o", "--output", help="write report to this file instead of stdout")
+    scan_p.add_argument(
+        "--fail-on",
+        default="high",
+        choices=[s.label for s in Severity] + ["none"],
+        help="exit 1 if any finding is at least this severe (default: high)",
+    )
+    scan_p.add_argument(
+        "--min-severity",
+        default="low",
+        choices=[s.label for s in Severity],
+        help="hide findings below this severity (default: low)",
+    )
+    scan_p.add_argument(
+        "--min-confidence",
+        default="low",
+        choices=["low", "medium", "high"],
+        help="hide findings below this confidence (default: low)",
+    )
+    scan_p.add_argument(
+        "--all-text",
+        action="store_true",
+        help="scan every UTF-8 text/source file, not just known agent-context files",
+    )
+    scan_p.add_argument(
+        "--git-history",
+        action="store_true",
+        help="also scan recent git commit messages",
+    )
+    scan_p.add_argument(
+        "--changed",
+        nargs="?",
+        const="HEAD",
+        default=None,
+        metavar="REF",
+        help="scan only files changed vs REF (default: HEAD) plus staged/unstaged/"
+        "untracked — fast pre-commit and PR gating",
+    )
+    scan_p.add_argument(
+        "--max-bytes",
+        type=int,
+        default=DEFAULT_MAX_BYTES,
+        help=f"skip files larger than this (default: {DEFAULT_MAX_BYTES})",
+    )
+    scan_p.add_argument("--exclude", action="append", default=[], metavar="DIR", help="extra directory name to skip (repeatable)")
+    scan_p.add_argument("--no-color", action="store_true", help="disable ANSI colour")
+
+    sub.add_parser("rules", help="list detection rules")
+
+    bench_p = sub.add_parser(
+        "bench", help="score the detectors against the labelled corpus in benchmark/"
+    )
+    bench_p.add_argument("--dir", help="benchmark directory (default: ./benchmark)")
+    bench_p.add_argument("--json", action="store_true", help="emit metrics as JSON")
+    bench_p.add_argument(
+        "--min-recall", type=float, default=0.0, help="exit 1 if recall is below this"
+    )
+    bench_p.add_argument(
+        "--max-fp-rate", type=float, default=1.0,
+        help="exit 1 if the false-positive rate exceeds this",
+    )
+    bench_p.add_argument(
+        "--min-rule-accuracy", type=float, default=0.0,
+        help="exit 1 if fewer than this fraction of malicious cases hit their named rule",
+    )
+
+    return parser
+
+
+_CONF_ORDER = {"low": 0, "medium": 1, "high": 2}
+
+
+def _run_scan(args: argparse.Namespace) -> int:
+    target = Path(args.path)
+    if not target.exists():
+        print(f"ctxsentry: path not found: {target}", file=sys.stderr)
+        return 2
+
+    config = ScanConfig(
+        root=target.resolve(),
+        max_bytes=args.max_bytes,
+        scan_all_text=args.all_text,
+        include_git_history=args.git_history,
+        changed_since=args.changed,
+    )
+    if args.exclude:
+        config.exclude_dirs = frozenset(config.exclude_dirs | set(args.exclude))
+
+    result = scan(config)
+
+    min_sev = Severity.parse(args.min_severity)
+    min_conf = _CONF_ORDER[args.min_confidence]
+    result.findings = [
+        f
+        for f in result.findings
+        if f.severity >= min_sev and _CONF_ORDER[f.confidence] >= min_conf
+    ]
+
+    report = render(result, args.format, color=not args.no_color and _stdout_is_tty(args))
+    if args.output:
+        Path(args.output).write_text(report + "\n", encoding="utf-8")
+        print(f"ctxsentry: wrote {len(result.findings)} finding(s) to {args.output}")
+    else:
+        print(report)
+
+    if args.fail_on == "none":
+        return 0
+    threshold = Severity.parse(args.fail_on)
+    worst = result.max_severity()
+    return 1 if worst is not None and worst >= threshold else 0
+
+
+def _stdout_is_tty(args: argparse.Namespace) -> bool:
+    return sys.stdout.isatty() and not args.output
+
+
+_EXTRA_RULES = [
+    ("CG403", "low", "obfuscation", "Long base64 blob that does not decode to readable text."),
+    ("CG404", "high", "obfuscation", "base64 / hex blob decodes to instruction or secret-like text."),
+    ("CG406", "high", "obfuscation", "Payload visible only after stripping invisible / look-alike characters."),
+    ("CG501", "high", "hidden-unicode", "Unicode Tag characters (U+E00xx); decoded and reported."),
+    ("CG502", "high", "hidden-unicode", "Bidirectional control character (Trojan Source)."),
+    ("CG503", "low", "hidden-unicode", "Zero-width / invisible character run."),
+    ("CG504", "medium", "hidden-unicode", "Private Use Area code-point run."),
+    ("CG505", "medium", "hidden-unicode", "Word mixes Latin with Cyrillic/Greek look-alikes."),
+    ("CG601", "medium", "obfuscation", "Instruction-like text pushed off-screen by a whitespace gap."),
+    ("CG602", "low", "obfuscation", "Very long line containing instruction-like text."),
+    ("CG701", "high", "mcp-tool-poisoning", "MCP tool description carries hidden instructions."),
+    ("CG702", "high", "mcp-tool-poisoning", "MCP server launch command pipes a download into a shell."),
+    ("CG801", "high", "filename-injection", "Filename contains control / invisible / bidi characters."),
+    ("CG802", "medium", "filename-injection", "Filename reads like an instruction to an assistant."),
+]
+
+
+def _run_rules() -> int:
+    rows = [(r.id, r.base_severity.label, r.category, r.message) for r in RULES]
+    rows += _EXTRA_RULES
+    for rid, sev, cat, msg in sorted(rows):
+        print(f"{rid}  {sev:<8} {cat}")
+        print(f"      {msg}")
+    print(
+        f"\n{len(RULES)} regex rules + {len(_EXTRA_RULES)} analytic detectors "
+        "(encoded-payload, Unicode, layout, MCP, filename)."
+    )
+    return 0
+
+
+def _run_bench(args: argparse.Namespace) -> int:
+    from ctxsentry.benchmark import DEFAULT_BENCH_DIR, run_benchmark
+
+    bench_dir = Path(args.dir).resolve() if args.dir else DEFAULT_BENCH_DIR
+    if not (bench_dir / "cases.jsonl").is_file():
+        print(f"ctxsentry: no benchmark corpus at {bench_dir}", file=sys.stderr)
+        return 2
+
+    res = run_benchmark(bench_dir)
+    if args.json:
+        import json as _json
+
+        print(_json.dumps(res.to_dict(), indent=2))
+    else:
+        print(
+            f"cases: {res.total}   "
+            f"TP {res.tp}  FN {res.fn}  FP {res.fp}  TN {res.tn}"
+        )
+        print(
+            f"precision {res.precision:.3f}   recall {res.recall:.3f}   "
+            f"F1 {res.f1:.3f}   FP-rate {res.fp_rate:.3f}   "
+            f"rule-accuracy {res.rule_accuracy:.3f}"
+        )
+        for case, reason in res.misses:
+            print(f"  ✗ {case.path}: {reason}")
+
+    ok = (
+        res.recall >= args.min_recall
+        and res.fp_rate <= args.max_fp_rate
+        and res.rule_accuracy >= args.min_rule_accuracy
+    )
+    return 0 if ok else 1
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "scan":
+            return _run_scan(args)
+        if args.command == "rules":
+            return _run_rules()
+        if args.command == "bench":
+            return _run_bench(args)
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ctxsentry/contexts.py

@@ -0,0 +1,164 @@
+"""Classify scanned paths by how an AI coding agent treats them.
+
+The same payload is far more dangerous in a file an agent loads automatically as
+standing instructions (``CLAUDE.md``, ``.cursorrules``, ``.mcp.json``) than in an
+arbitrary source file, so detectors use the context to boost severity.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import posixpath
+from typing import Iterable
+
+# Contexts, most-trusted-by-agents first.
+CTX_MCP_CONFIG = "mcp-config"
+CTX_AGENT_INSTRUCTIONS = "agent-instructions"
+CTX_AGENT_SKILL = "agent-skill"
+CTX_DOCS = "docs"
+CTX_VCS_META = "vcs-metadata"  # commit messages, issue/PR bodies fed in via history
+CTX_GENERIC = "generic"
+
+# Files agents ingest automatically as authoritative instructions.
+_AGENT_INSTRUCTION_GLOBS = (
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    ".claude/*.md",
+    ".claude/**/*.md",
+    "AGENTS.md",
+    "AGENT.md",
+    "GEMINI.md",
+    ".gemini/*.md",
+    ".cursorrules",
+    ".cursor/rules/*",
+    ".cursor/rules/**/*",
+    ".windsurfrules",
+    ".windsurf/rules/*",
+    ".clinerules",
+    ".clinerules/*",
+    ".aider.conf.yml",
+    ".aider/*",
+    ".github/copilot-instructions.md",
+    ".github/instructions/*",
+    ".continue/*",
+)
+
+_MCP_CONFIG_GLOBS = (
+    ".mcp.json",
+    "mcp.json",
+    ".vscode/mcp.json",
+    ".cursor/mcp.json",
+    "**/mcp.json",
+    "**/.mcp.json",
+)
+
+_AGENT_SKILL_GLOBS = (
+    "SKILL.md",
+    "skill.md",
+    "**/SKILL.md",
+    ".claude/skills/**/*",
+    "skills/**/*.md",
+)
+
+_DOCS_GLOBS = (
+    "README*",
+    "readme*",
+    "CONTRIBUTING*",
+    "SECURITY*",
+    "docs/*",
+    "docs/**/*",
+    "*.md",
+    "*.mdx",
+    "*.rst",
+    "*.txt",
+)
+
+# Directories that never carry agent context and bloat scans.
+DEFAULT_EXCLUDE_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "venv",
+        ".venv",
+        "env",
+        ".env.d",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        "dist",
+        "build",
+        ".next",
+        ".nuxt",
+        "target",
+        "vendor",
+        ".gradle",
+        ".idea",
+    }
+)
+
+# Extensions we treat as scannable text regardless of name.
+TEXT_EXTENSIONS = frozenset(
+    {
+        ".md",
+        ".mdx",
+        ".markdown",
+        ".rst",
+        ".txt",
+        ".json",
+        ".jsonc",
+        ".yaml",
+        ".yml",
+        ".toml",
+        ".ini",
+        ".cfg",
+        ".xml",
+        ".html",
+        ".htm",
+        ".csv",
+        ".tsv",
+        ".rules",
+        ".mdc",
+        "",  # dotfiles like .cursorrules
+    }
+)
+
+
+def _match_any(rel_path: str, globs: Iterable[str]) -> bool:
+    name = posixpath.basename(rel_path)
+    for pattern in globs:
+        if "/" in pattern:
+            if fnmatch.fnmatch(rel_path, pattern):
+                return True
+        elif fnmatch.fnmatch(name, pattern):
+            return True
+    return False
+
+
+def classify(rel_path: str) -> str:
+    """Return the context constant for a repo-relative POSIX path."""
+
+    rel_path = rel_path.replace("\\", "/").lstrip("./")
+    if _match_any(rel_path, _MCP_CONFIG_GLOBS):
+        return CTX_MCP_CONFIG
+    if _match_any(rel_path, _AGENT_INSTRUCTION_GLOBS):
+        return CTX_AGENT_INSTRUCTIONS
+    if _match_any(rel_path, _AGENT_SKILL_GLOBS):
+        return CTX_AGENT_SKILL
+    if _match_any(rel_path, _DOCS_GLOBS):
+        return CTX_DOCS
+    return CTX_GENERIC
+
+
+# How much to bump a rule's base severity for a given context (in levels).
+CONTEXT_SEVERITY_BOOST = {
+    CTX_MCP_CONFIG: 2,
+    CTX_AGENT_INSTRUCTIONS: 2,
+    CTX_AGENT_SKILL: 1,
+    CTX_DOCS: 1,
+    CTX_VCS_META: 1,
+    CTX_GENERIC: 0,
+}