contextduty 1.0.0

Policy-driven context firewall for AI workflows — scan and redact sensitive data before prompts, logs, or traces leave your environment.

ContextDuty

The local-first prompt firewall — stop secrets and PII from reaching any AI tool, before the prompt ever leaves your machine.

Try it live: ContextDuty demo on Hugging Face Spaces · Detection brain: Microsoft Presidio

pip install contextduty
contextduty protect          # stop all AI tools from indexing your secrets
contextduty install-hooks    # block commits that contain secrets

---

Why

By 2026, 34.8% of data developers paste into AI tools is sensitive (Cyberhaven). A secret leaks the moment it's typed into a prompt — long before it ever reaches a repo. Traditional DLP can't see that flow, and enterprise AI plans don't stop an engineer pasting a key into Cursor.

ContextDuty closes every door a developer leaks through — the IDE, a git commit, live AI-API traffic, and MCP tool calls — with one install, one policy, zero cloud.

What it is (and what it isn't)

ContextDuty is not a new PII detector. Detection is hard and already solved — so the NLP layer is powered by Microsoft Presidio (with a spaCy fallback), plus 60 deterministic regex detectors for secrets.

ContextDuty is the enforcement fabric around that detection: it wires it into the four places developers actually leak, governs everything with a portable block/warn/redact policy, and runs 100% locally — no data leaves your machine, no SaaS, MIT-licensed.

Presidio is the brain. ContextDuty is the firewall.

	Microsoft Presidio	GitGuardian ggshield	Cloud DLP (Aona/Lasso/Nightfall)	ContextDuty
PII detection	✅ (we use it)	❌	✅	✅ via Presidio
Secret detection	partial	✅ (secrets only)	✅	✅ 60 detectors
Git pre-commit hook	❌	✅	❌	✅
IDE indexing block (.cursorignore…)	❌	❌	❌	✅
Live HTTPS proxy over AI-API traffic	❌	❌	network/browser	✅
MCP server	❌	❌	❌	✅
Portable block/warn/redact policy	operators only	limited	cloud console	✅ one JSON, all surfaces
Local-first — nothing leaves the machine	✅	cloud engine	❌ SaaS	✅
Open-source	✅	❌	❌	✅ MIT

---

The five enforcement surfaces

flowchart LR
    WS["🗂️ Your workspace\n.env · keys/ · config"] --> CD

    subgraph CD["ContextDuty — 60 regex detectors + Presidio NLP"]
        L1["IDE ignore files"]
        L2["git pre-commit hook"]
        L3["HTTPS proxy (21 AI APIs)"]
        L4["MCP server"]
        L5["CI / CD"]
    end

    CD --> AI["✅ AI tools protected\nCursor · Copilot · Claude · Windsurf · Cody · Amazon Q · …"]

Surface	What it does	Command
IDE ignore	Generates ignore files for 6 AI tools so secrets are never indexed	contextduty protect
Git hook	Pre-commit scan blocks secrets from entering history	contextduty install-hooks
HTTPS proxy	Intercepts 21 AI API hosts, redacts secrets from request bodies in-flight	contextduty proxy start
MCP server	Redacts tool-call results before they enter the AI context window	contextduty-mcp
CI/CD	Policy-as-code gate — PRs with secrets exit non-zero	contextduty scan src/

---

Quick start

pip install contextduty          # core (regex detectors, hooks, CLI)
cd your-project/                 # run from your git root

contextduty init                 # create .contextduty.json policy
contextduty protect              # write ignore files for all 6 AI tools
contextduty install-hooks        # block secret-bearing commits

# Optional extras
pip install 'contextduty[presidio]'   # NLP PII detection (recommended)
pip install 'contextduty[proxy]'      # live HTTPS interception

Scan or redact anything:

contextduty scan src/                          # JSON findings report
contextduty scan --nlp src/                    # add Presidio NLP PII detection
contextduty redact --in raw.txt --out clean.txt

---

Detection

60 built-in regex detectors across Cloud/Infra, VCS/CI, Payment, Messaging, AI/ML, Databases, Generic secrets, IaC, PII, Healthcare, and Crypto/Web3 — including aws_key, github_pat, stripe_secret, openai_key, postgres_dsn, ssh/pgp keys, credit_card, ssn, jwt_token, and more. See detectors.py for the full list.

Presidio NLP catches unstructured PII regex can't — person names, organizations, locations, dates — running entirely locally:

pip install 'contextduty[presidio]'
python -m spacy download en_core_web_sm
contextduty scan --nlp src/

Deterministic masks: AKIAIOSFODNN7EXAMPLE always becomes <AWS_KEY_1a5d44a2dc> — same value, same mask, everywhere — so audit logs stay correlatable without storing raw secrets.

Custom detectors (no code, no redeploy):

{ "custom_detectors": { "employee_id": "\\bEMP-[0-9]{6}\\b" } }

📊 Benchmarked: 100k prompts, fully local — p99 latency ~13 ms, precision 1.000, F1 0.94 (0.99 at threshold 0.4). See benchmarks/README.md.

---

Policy

{
  "mode": "redact",                                  // redact | warn | block
  "detectors": ["email", "aws_key", "openai_key", "postgres_dsn"],
  "detector_modes": { "aws_key": "block" },          // per-detector override
  "allow_patterns": { "email": ["@example\\.com$"] },// known-safe values
  "extends": "../../policies/org-baseline.json"      // team baseline + repo override
}

Mode	Behavior
redact	Replace matches with deterministic masks
warn	Log findings, don't modify or block
block	Exit non-zero — for CI and pre-commit hard stops

Compliance baselines included: policies/soc2-baseline.json, policies/hipaa-baseline.json.

---

Notebooks, MCP & dashboard

Jupyter / Colab / Databricks — one import, zero config:

from contextduty.notebook import guard, redact
guard("aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")  # prints a warning
clean = redact("db = postgres://admin:secret@prod:5432/app")               # → <POSTGRES_DSN_…>

MCP server — redacts tool-call results before they enter the model's context:

{ "mcpServers": { "contextduty": { "command": "contextduty-mcp" } } }

Audit dashboard — local web UI, all data stays on your machine:

contextduty dashboard --demo   # synthetic data
contextduty dashboard          # reads ~/.contextduty/audit.jsonl

---

Commands

Command	Description
contextduty protect [watch|status]	Write/auto-update ignore files for all 6 AI tools
contextduty install-hooks / uninstall-hooks	Manage the git pre-commit hook
contextduty proxy [setup|start|stop|status]	Manage the HTTPS interception proxy
contextduty scan <file|dir> [--nlp]	Scan and print JSON findings
contextduty redact --in <f> --out <f>	Write a redacted copy
contextduty dashboard / report	Audit dashboard / log summary
contextduty policy validate	Validate and resolve a layered policy
contextduty init	Create a default .contextduty.json
contextduty demo	20-second interactive walkthrough

---

Local development

git clone https://github.com/SHUBHAGYTA24/contextduty
cd contextduty
pip install -e ".[dev]"
make check    # format + lint + tests

Architecture: engine.py (scan/redact), detectors.py (60 patterns), policy.py (layered policy), nlp/ (Presidio + spaCy), proxy/ (mitmproxy field-walker), adapters/ide.py (AI tool registry), dashboard.py (audit UI). See docs/USER_MANUAL.md.

Roadmap

• 60 detectors · git hook · MCP · HTTPS proxy (21 APIs) · 6 IDE ignore files
• Presidio NLP PII detection · notebook API · audit dashboard · policy layering
• Local 100k-row latency/quality benchmark · hosted demo Space
• VS Code / Cursor extension
• Prometheus metrics endpoint
• International + domain-specific detector packs

License

MIT. Built on Microsoft Presidio. Issues and PRs welcome — open an issue if a detector is missing or misfiring.