contextduty 0.1.0__tar.gz

contextduty-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContextDuty Contributors
+
+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.

contextduty-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: contextduty
+Version: 0.1.0
+Summary: Policy-driven context firewall for AI workflows — scan and redact sensitive data before prompts, logs, or traces leave your environment.
+Author: ContextDuty Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/SHUBHAGYTA24/contextduty
+Project-URL: Repository, https://github.com/SHUBHAGYTA24/contextduty
+Project-URL: Bug Tracker, https://github.com/SHUBHAGYTA24/contextduty/issues
+Project-URL: Changelog, https://github.com/SHUBHAGYTA24/contextduty/blob/main/CHANGELOG.md
+Keywords: security,pii,redaction,ai,llm,mcp,prompt,privacy,devsecops,secrets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# ContextDuty
+
+> A policy-driven context firewall for AI workflows. Scan and redact sensitive data before prompts, logs, or traces leave your environment — locally, with no cloud calls.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
+
+---
+
+## Why ContextDuty
+
+AI coding assistants and agent workflows are spreading fast. So is accidental data leakage — API keys, emails, and PII flowing into prompts, logs, and traces that may be stored or sent to third-party services.
+
+ContextDuty is a **local-first, policy-layered primitive** that fits into any workflow:
+- **CLI** — pipe files through it in CI or pre-commit hooks
+- **MCP server** — Cursor, VS Code, and any MCP client get automatic redaction
+- **Policy inheritance** — teams extend org-wide baselines without copying rules
+
+---
+
+## Why not Presidio?
+
+[Microsoft Presidio](https://github.com/microsoft/presidio) is great for NER-based PII detection in data pipelines. ContextDuty solves a different problem:
+
+| | ContextDuty | Presidio |
+|---|---|---|
+| Target use case | AI prompts, logs, agent traces | Data pipelines, analytics |
+| MCP-native | ✅ | ❌ |
+| Policy layering (`extends`) | ✅ | ❌ |
+| `block` mode for CI | ✅ | ❌ |
+| Zero dependencies | ✅ | ❌ (heavy NLP stack) |
+| Custom detectors (no code) | ✅ (regex in JSON) | Partial |
+| Deployment | Local CLI / subprocess | Service / SDK |
+
+Use Presidio when you need ML-based entity recognition at scale. Use ContextDuty when you need a lightweight, policy-enforceable firewall close to your AI toolchain.
+
+---
+
+## Detection coverage
+
+| Detector | Example input | Masked as |
+|---|---|---|
+| `email` | `jane@corp.com` | `<EMAIL_a1b2c3d4e5>` |
+| `phone` | `+1 415-555-1212` | `<PHONE_f6g7h8i9j0>` |
+| `api_key` | `sk_live_ABC123...` | `<API_KEY_k1l2m3n4o5>` |
+| `aws_key` | `AKIA1234567890ABCDEF` | `<AWS_KEY_p6q7r8s9t0>` |
+| `bearer_token` | `Bearer eyJhbGci...` | `<BEARER_TOKEN_u1v2w3x4y5>` |
+
+Masks are **deterministic** — the same value always produces the same mask, so you can correlate across log lines without exposing the raw value.
+
+---
+
+## Quickstart
+
+```bash
+pip install contextduty
+contextduty init
+```
+
+Then scan and redact:
+
+```bash
+contextduty scan sample.txt --report report.json
+contextduty redact --in sample.txt --out clean.txt --report report.json
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `contextduty init` | Create `.contextduty.json` in the current directory |
+| `contextduty scan <file>` | Scan file, print JSON findings report |
+| `contextduty redact --in <f> --out <f>` | Redact matches, write clean file |
+| `contextduty policy validate --policy <f> [--strict]` | Validate and resolve a layered policy |
+
+---
+
+## MCP server (Cursor / VS Code / any MCP client)
+
+ContextDuty runs as an MCP stdio server — drop it into your editor config and every file your agent touches is scanned automatically.
+
+```bash
+contextduty-mcp
+```
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "contextduty": {
+      "command": "contextduty-mcp"
+    }
+  }
+}
+```
+
+Exposed tools:
+- `contextduty_scan` (`path`, optional `policyPath`)
+- `contextduty_redact` (`inputPath`, `outputPath`, optional `policyPath`)
+
+---
+
+## Policy file
+
+Default `.contextduty.json`:
+
+```json
+{
+  "mode": "redact",
+  "detectors": ["email", "phone", "api_key", "aws_key", "bearer_token"],
+  "custom_detectors": {}
+}
+```
+
+**Add a custom detector without touching code:**
+
+```json
+{
+  "mode": "redact",
+  "detectors": ["email"],
+  "custom_detectors": {
+    "employee_id": "\\bEMP-[0-9]{6}\\b",
+    "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b"
+  }
+}
+```
+
+`custom_detectors` are auto-enabled — just add the regex entry.
+
+**Policy layering for teams and enterprises:**
+
+```json
+{
+  "extends": "../../policies/org-baseline.json",
+  "mode": "block",
+  "detectors": ["internal_ticket"],
+  "custom_detectors": {
+    "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b"
+  }
+}
+```
+
+Rules:
+- `extends` can be a string or list (relative file paths)
+- `detectors` are merged (parent + child)
+- `custom_detectors` are merged (child overrides same key)
+- `mode` is overridden by the child policy
+- Cycles in `extends` are rejected with a clear error
+
+**Modes:**
+
+| Mode | Behaviour |
+|---|---|
+| `redact` | Replace matched values with deterministic masks |
+| `warn` | Report findings, do not change content |
+| `block` | Exit non-zero if findings exist (CI enforcement) |
+
+---
+
+## Compliance policy packs
+
+Ready-made baselines for common frameworks — extend them in your own policy file:
+
+| Pack | Path | Detectors included |
+|---|---|---|
+| SOC 2 | `policies/soc2-baseline.json` | email, phone, api_key, aws_key, bearer_token |
+| HIPAA | `policies/hipaa-baseline.json` | email, phone + PHI custom patterns |
+
+Usage:
+```json
+{
+  "extends": "./node_modules/contextduty/policies/soc2-baseline.json",
+  "mode": "block"
+}
+```
+
+---
+
+## CI integration
+
+Add a pre-push check to block accidental secret commits:
+
+```yaml
+# .github/workflows/contextduty.yml
+- name: Scan for secrets
+  run: |
+    pip install contextduty
+    contextduty scan . --policy .contextduty.json
+```
+
+Or use `mode: block` in your policy to make `contextduty scan` exit non-zero on any finding.
+
+---
+
+## Roadmap
+
+- [ ] PyPI publish (`pip install contextduty`)
+- [ ] Streaming JSONL mode for multi-GB datasets
+- [ ] VS Code extension
+- [ ] Policy packs for PCI-DSS
+- [ ] GitHub Action (`uses: contextduty/action@v1`)
+
+---
+
+## Open source
+
+| File | Purpose |
+|---|---|
+| `LICENSE` | MIT |
+| `SECURITY.md` | Vulnerability reporting |
+| `CONTRIBUTING.md` | How to contribute |
+| `CODE_OF_CONDUCT.md` | Community standards |
+| `CHANGELOG.md` | Version history |
+
+---
+
+## Contributing
+
+Issues, PRs, and policy pack contributions are very welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

contextduty-0.1.0/README.md

@@ -0,0 +1,222 @@
+# ContextDuty
+
+> A policy-driven context firewall for AI workflows. Scan and redact sensitive data before prompts, logs, or traces leave your environment — locally, with no cloud calls.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
+
+---
+
+## Why ContextDuty
+
+AI coding assistants and agent workflows are spreading fast. So is accidental data leakage — API keys, emails, and PII flowing into prompts, logs, and traces that may be stored or sent to third-party services.
+
+ContextDuty is a **local-first, policy-layered primitive** that fits into any workflow:
+- **CLI** — pipe files through it in CI or pre-commit hooks
+- **MCP server** — Cursor, VS Code, and any MCP client get automatic redaction
+- **Policy inheritance** — teams extend org-wide baselines without copying rules
+
+---
+
+## Why not Presidio?
+
+[Microsoft Presidio](https://github.com/microsoft/presidio) is great for NER-based PII detection in data pipelines. ContextDuty solves a different problem:
+
+| | ContextDuty | Presidio |
+|---|---|---|
+| Target use case | AI prompts, logs, agent traces | Data pipelines, analytics |
+| MCP-native | ✅ | ❌ |
+| Policy layering (`extends`) | ✅ | ❌ |
+| `block` mode for CI | ✅ | ❌ |
+| Zero dependencies | ✅ | ❌ (heavy NLP stack) |
+| Custom detectors (no code) | ✅ (regex in JSON) | Partial |
+| Deployment | Local CLI / subprocess | Service / SDK |
+
+Use Presidio when you need ML-based entity recognition at scale. Use ContextDuty when you need a lightweight, policy-enforceable firewall close to your AI toolchain.
+
+---
+
+## Detection coverage
+
+| Detector | Example input | Masked as |
+|---|---|---|
+| `email` | `jane@corp.com` | `<EMAIL_a1b2c3d4e5>` |
+| `phone` | `+1 415-555-1212` | `<PHONE_f6g7h8i9j0>` |
+| `api_key` | `sk_live_ABC123...` | `<API_KEY_k1l2m3n4o5>` |
+| `aws_key` | `AKIA1234567890ABCDEF` | `<AWS_KEY_p6q7r8s9t0>` |
+| `bearer_token` | `Bearer eyJhbGci...` | `<BEARER_TOKEN_u1v2w3x4y5>` |
+
+Masks are **deterministic** — the same value always produces the same mask, so you can correlate across log lines without exposing the raw value.
+
+---
+
+## Quickstart
+
+```bash
+pip install contextduty
+contextduty init
+```
+
+Then scan and redact:
+
+```bash
+contextduty scan sample.txt --report report.json
+contextduty redact --in sample.txt --out clean.txt --report report.json
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `contextduty init` | Create `.contextduty.json` in the current directory |
+| `contextduty scan <file>` | Scan file, print JSON findings report |
+| `contextduty redact --in <f> --out <f>` | Redact matches, write clean file |
+| `contextduty policy validate --policy <f> [--strict]` | Validate and resolve a layered policy |
+
+---
+
+## MCP server (Cursor / VS Code / any MCP client)
+
+ContextDuty runs as an MCP stdio server — drop it into your editor config and every file your agent touches is scanned automatically.
+
+```bash
+contextduty-mcp
+```
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "contextduty": {
+      "command": "contextduty-mcp"
+    }
+  }
+}
+```
+
+Exposed tools:
+- `contextduty_scan` (`path`, optional `policyPath`)
+- `contextduty_redact` (`inputPath`, `outputPath`, optional `policyPath`)
+
+---
+
+## Policy file
+
+Default `.contextduty.json`:
+
+```json
+{
+  "mode": "redact",
+  "detectors": ["email", "phone", "api_key", "aws_key", "bearer_token"],
+  "custom_detectors": {}
+}
+```
+
+**Add a custom detector without touching code:**
+
+```json
+{
+  "mode": "redact",
+  "detectors": ["email"],
+  "custom_detectors": {
+    "employee_id": "\\bEMP-[0-9]{6}\\b",
+    "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b"
+  }
+}
+```
+
+`custom_detectors` are auto-enabled — just add the regex entry.
+
+**Policy layering for teams and enterprises:**
+
+```json
+{
+  "extends": "../../policies/org-baseline.json",
+  "mode": "block",
+  "detectors": ["internal_ticket"],
+  "custom_detectors": {
+    "internal_ticket": "\\bTICKET-[A-Z]{3}-[0-9]{4}\\b"
+  }
+}
+```
+
+Rules:
+- `extends` can be a string or list (relative file paths)
+- `detectors` are merged (parent + child)
+- `custom_detectors` are merged (child overrides same key)
+- `mode` is overridden by the child policy
+- Cycles in `extends` are rejected with a clear error
+
+**Modes:**
+
+| Mode | Behaviour |
+|---|---|
+| `redact` | Replace matched values with deterministic masks |
+| `warn` | Report findings, do not change content |
+| `block` | Exit non-zero if findings exist (CI enforcement) |
+
+---
+
+## Compliance policy packs
+
+Ready-made baselines for common frameworks — extend them in your own policy file:
+
+| Pack | Path | Detectors included |
+|---|---|---|
+| SOC 2 | `policies/soc2-baseline.json` | email, phone, api_key, aws_key, bearer_token |
+| HIPAA | `policies/hipaa-baseline.json` | email, phone + PHI custom patterns |
+
+Usage:
+```json
+{
+  "extends": "./node_modules/contextduty/policies/soc2-baseline.json",
+  "mode": "block"
+}
+```
+
+---
+
+## CI integration
+
+Add a pre-push check to block accidental secret commits:
+
+```yaml
+# .github/workflows/contextduty.yml
+- name: Scan for secrets
+  run: |
+    pip install contextduty
+    contextduty scan . --policy .contextduty.json
+```
+
+Or use `mode: block` in your policy to make `contextduty scan` exit non-zero on any finding.
+
+---
+
+## Roadmap
+
+- [ ] PyPI publish (`pip install contextduty`)
+- [ ] Streaming JSONL mode for multi-GB datasets
+- [ ] VS Code extension
+- [ ] Policy packs for PCI-DSS
+- [ ] GitHub Action (`uses: contextduty/action@v1`)
+
+---
+
+## Open source
+
+| File | Purpose |
+|---|---|
+| `LICENSE` | MIT |
+| `SECURITY.md` | Vulnerability reporting |
+| `CONTRIBUTING.md` | How to contribute |
+| `CODE_OF_CONDUCT.md` | Community standards |
+| `CHANGELOG.md` | Version history |
+
+---
+
+## Contributing
+
+Issues, PRs, and policy pack contributions are very welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

contextduty-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contextduty"
+version = "0.1.0"
+description = "Policy-driven context firewall for AI workflows — scan and redact sensitive data before prompts, logs, or traces leave your environment."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "ContextDuty Contributors" }
+]
+keywords = [
+  "security", "pii", "redaction", "ai", "llm", "mcp",
+  "prompt", "privacy", "devsecops", "secrets"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Logging",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/SHUBHAGYTA24/contextduty"
+Repository = "https://github.com/SHUBHAGYTA24/contextduty"
+"Bug Tracker" = "https://github.com/SHUBHAGYTA24/contextduty/issues"
+Changelog = "https://github.com/SHUBHAGYTA24/contextduty/blob/main/CHANGELOG.md"
+
+[project.scripts]
+contextduty = "contextduty.cli:main"
+contextduty-mcp = "contextduty.mcp_server:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]   # pycodestyle errors, pyflakes, isort

contextduty-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contextduty-0.1.0/src/contextduty/__init__.py

@@ -0,0 +1,3 @@
+"""ContextDuty — policy-driven context firewall for AI workflows."""
+
+__version__ = "0.1.0"

contextduty-0.1.0/src/contextduty/cli.py

@@ -0,0 +1,127 @@
+"""CLI entrypoint for ContextDuty."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .engine import redact_file, report_to_json, scan_file
+from .policy import load_policy, unknown_detector_names, write_default_policy
+
+
+def _parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="contextduty", description="Protect AI context with policy checks."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Create default policy file.")
+    init_parser.add_argument("--path", default=".contextduty.json", help="Policy output path.")
+
+    scan_parser = subparsers.add_parser("scan", help="Scan a text file for risky data.")
+    scan_parser.add_argument("target", help="Input file path.")
+    scan_parser.add_argument("--policy", default=".contextduty.json", help="Policy path.")
+    scan_parser.add_argument("--report", help="Optional report output JSON path.")
+
+    redact_parser = subparsers.add_parser("redact", help="Redact risky data from an input file.")
+    redact_parser.add_argument("--in", dest="input_path", required=True, help="Input file path.")
+    redact_parser.add_argument("--out", dest="output_path", required=True, help="Output file path.")
+    redact_parser.add_argument("--policy", default=".contextduty.json", help="Policy path.")
+    redact_parser.add_argument("--report", help="Optional report output JSON path.")
+
+    policy_parser = subparsers.add_parser("policy", help="Policy operations.")
+    policy_subparsers = policy_parser.add_subparsers(dest="policy_command", required=True)
+    validate_parser = policy_subparsers.add_parser(
+        "validate", help="Validate and resolve a policy file."
+    )
+    validate_parser.add_argument("--policy", default=".contextduty.json", help="Policy path.")
+    validate_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Fail validation when unknown detector names are present.",
+    )
+
+    return parser
+
+
+def _load_policy_with_fallback(policy_path: str) -> tuple[Path | None, object]:
+    path = Path(policy_path)
+    if path.exists():
+        return path, load_policy(path)
+    return None, load_policy(None)
+
+
+def main() -> None:
+    parser = _parser()
+    args = parser.parse_args()
+
+    if args.command == "init":
+        out_path = Path(args.path)
+        write_default_policy(out_path)
+        print(f"Created policy at {out_path}")
+        return
+
+    if args.command == "scan":
+        policy_ref, policy = _load_policy_with_fallback(args.policy)
+        result = scan_file(Path(args.target), policy)
+        report = report_to_json(result)
+        print(report)
+        if args.report:
+            Path(args.report).write_text(report + "\n", encoding="utf-8")
+            print(f"Saved report to {args.report}")
+        if result.blocked:
+            print(f"BLOCKED by policy ({policy_ref or 'default'})", file=sys.stderr)
+            raise SystemExit(2)
+        return
+
+    if args.command == "redact":
+        policy_ref, policy = _load_policy_with_fallback(args.policy)
+        result = redact_file(Path(args.input_path), Path(args.output_path), policy)
+        report = report_to_json(result)
+        print(report)
+        if args.report:
+            Path(args.report).write_text(report + "\n", encoding="utf-8")
+            print(f"Saved report to {args.report}")
+        if result.blocked:
+            print(f"BLOCKED by policy ({policy_ref or 'default'})", file=sys.stderr)
+            raise SystemExit(2)
+        return
+
+    if args.command == "policy":
+        if args.policy_command == "validate":
+            policy_path = Path(args.policy)
+            if policy_path.exists():
+                policy = load_policy(policy_path)
+                source = str(policy_path)
+            else:
+                policy = load_policy(None)
+                source = "default"
+            payload = {
+                "valid": True,
+                "source": source,
+                "mode": policy.mode,
+                "detectors": sorted(policy.detectors),
+                "custom_detectors": sorted(policy.custom_detectors.keys()),
+            }
+            if args.strict:
+                unknown = unknown_detector_names(policy)
+                if unknown:
+                    print(
+                        f"Unknown detector names in strict mode: {', '.join(unknown)}",
+                        file=sys.stderr,
+                    )
+                    raise SystemExit(2)
+            print(json.dumps(payload, indent=2))
+            return
+        raise SystemExit(1)
+
+    raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()