contextduty 0.1.0__py3-none-any.whl

contextduty/__init__.py

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

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()

contextduty/detectors.py

@@ -0,0 +1,36 @@
+"""Built-in detectors for secrets and PII."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Detector:
+    name: str
+    pattern: re.Pattern[str]
+
+
+DETECTORS: list[Detector] = [
+    Detector(
+        "email", re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
+    ),
+    Detector(
+        "phone",
+        re.compile(
+            r"\b(?:\+?1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?)\d{3}[-.\s]?\d{4}\b"
+        ),
+    ),
+    Detector("api_key", re.compile(r"\b(?:sk|rk|pk)_[A-Za-z0-9_]{16,}\b")),
+    Detector("aws_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    Detector(
+        "bearer_token", re.compile(r"\bBearer\s+[A-Za-z0-9\-._~+/]+=*\b", re.IGNORECASE)
+    ),
+]
+
+
+def stable_mask(detector_name: str, value: str) -> str:
+    digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:10]
+    return f"<{detector_name.upper()}_{digest}>"

contextduty/engine.py

@@ -0,0 +1,136 @@
+"""Scanning and redaction engine."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from .detectors import DETECTORS, Detector, stable_mask
+from .policy import Policy
+
+
+@dataclass(frozen=True)
+class Finding:
+    detector: str
+    value: str
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    findings_count: int
+    detector_counts: dict[str, int]
+    blocked: bool
+
+
+def _active_detectors(policy: Policy) -> list[Detector]:
+    active = [detector for detector in DETECTORS if detector.name in policy.detectors]
+    for name, pattern in policy.custom_detectors.items():
+        if name in policy.detectors:
+            active.append(Detector(name=name, pattern=re.compile(pattern)))
+    return active
+
+
+def _scan_line(line: str, detectors: Iterable[Detector]) -> list[Finding]:
+    findings: list[Finding] = []
+    for detector in detectors:
+        for match in detector.pattern.finditer(line):
+            findings.append(Finding(detector=detector.name, value=match.group(0)))
+    return findings
+
+
+def scan_file(path: Path, policy: Policy) -> ScanResult:
+    detectors = _active_detectors(policy)
+    detector_counts: dict[str, int] = {}
+    findings_count = 0
+    with path.open("r", encoding="utf-8", errors="replace") as handle:
+        for line in handle:
+            findings = _scan_line(line, detectors)
+            findings_count += len(findings)
+            for finding in findings:
+                detector_counts[finding.detector] = detector_counts.get(finding.detector, 0) + 1
+    blocked = findings_count > 0 and policy.mode == "block"
+    return ScanResult(
+        findings_count=findings_count, detector_counts=detector_counts, blocked=blocked
+    )
+
+
+def redact_file(input_path: Path, output_path: Path, policy: Policy) -> ScanResult:
+    detectors = _active_detectors(policy)
+    detector_counts: dict[str, int] = {}
+    findings_count = 0
+    blocked = False
+
+    with (
+        input_path.open("r", encoding="utf-8", errors="replace") as source,
+        output_path.open("w", encoding="utf-8") as target,
+    ):
+        for line in source:
+            updated = line
+            findings = _scan_line(updated, detectors)
+            findings_count += len(findings)
+            for finding in findings:
+                detector_counts[finding.detector] = detector_counts.get(finding.detector, 0) + 1
+                if policy.mode == "redact":
+                    updated = updated.replace(
+                        finding.value, stable_mask(finding.detector, finding.value)
+                    )
+            target.write(updated)
+
+    if findings_count > 0 and policy.mode == "block":
+        blocked = True
+
+    return ScanResult(
+        findings_count=findings_count, detector_counts=detector_counts, blocked=blocked
+    )
+
+
+@dataclass(frozen=True)
+class ScanTextResult:
+    """Result of scanning and redacting an in-memory text string."""
+
+    scan: ScanResult
+    redacted_text: str
+
+
+def scan_text(text: str, policy: Policy) -> ScanTextResult:
+    """Scan and redact an in-memory string without touching the filesystem.
+
+    This is the primary entry point for MCP tool use — the LLM passes raw
+    text and receives back a findings report plus the redacted version.
+    """
+    detectors = _active_detectors(policy)
+    detector_counts: dict[str, int] = {}
+    findings_count = 0
+    redacted = text
+
+    for line in text.splitlines(keepends=True):
+        findings = _scan_line(line, detectors)
+        findings_count += len(findings)
+        for finding in findings:
+            detector_counts[finding.detector] = detector_counts.get(finding.detector, 0) + 1
+            if policy.mode == "redact":
+                redacted = redacted.replace(
+                    finding.value, stable_mask(finding.detector, finding.value)
+                )
+
+    blocked = findings_count > 0 and policy.mode == "block"
+    scan_result = ScanResult(
+        findings_count=findings_count,
+        detector_counts=detector_counts,
+        blocked=blocked,
+    )
+    return ScanTextResult(
+        scan=scan_result, redacted_text=redacted if policy.mode == "redact" else text
+    )
+
+
+def report_to_json(result: ScanResult) -> str:
+    payload = {
+        "findings_count": result.findings_count,
+        "detector_counts": result.detector_counts,
+        "blocked": result.blocked,
+    }
+    return json.dumps(payload, indent=2)

contextduty/mcp_server.py

@@ -0,0 +1,222 @@
+"""Minimal MCP stdio server exposing ContextDuty as tools.
+
+Implements:
+- initialize
+- tools/list
+- tools/call
+
+Spec: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .engine import redact_file, report_to_json, scan_file, scan_text
+from .policy import load_policy
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+def _send(obj: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(obj, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def _err(_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": _id, "error": {"code": code, "message": message}}
+
+
+def _ok(_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": _id, "result": result}
+
+
+def _tool_result(
+    text: str, is_error: bool = False, structured: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"content": [{"type": "text", "text": text}], "isError": is_error}
+    if structured is not None:
+        payload["structuredContent"] = structured
+    return payload
+
+
+def _tools_list() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": "contextduty_scan_text",
+            "title": "ContextDuty Scan Text",
+            "description": (
+                "Scan a raw text string for sensitive data (emails, API keys, tokens, etc.) "
+                "before it is sent to an LLM. Returns findings and the redacted version of the text."  # noqa: E501
+                "Use this to check prompt content, log snippets, or any in-memory string."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "The text content to scan and redact.",
+                    },
+                    "policyPath": {
+                        "type": "string",
+                        "description": "Optional policy JSON path (.contextduty.json).",
+                    },
+                },
+                "required": ["text"],
+            },
+        },
+        {
+            "name": "contextduty_scan",
+            "title": "ContextDuty Scan",
+            "description": "Scan a file for sensitive data based on ContextDuty policy.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to input file to scan."},
+                    "policyPath": {
+                        "type": "string",
+                        "description": "Optional policy JSON path (.contextduty.json).",
+                    },
+                },
+                "required": ["path"],
+            },
+        },
+        {
+            "name": "contextduty_redact",
+            "title": "ContextDuty Redact",
+            "description": "Redact sensitive data from an input file into an output file based on ContextDuty policy.",  # noqa: E501
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "inputPath": {"type": "string", "description": "Path to input file."},
+                    "outputPath": {"type": "string", "description": "Path to write redacted file."},
+                    "policyPath": {
+                        "type": "string",
+                        "description": "Optional policy JSON path (.contextduty.json).",
+                    },
+                },
+                "required": ["inputPath", "outputPath"],
+            },
+        },
+    ]
+
+
+def _load_policy(policy_path: str | None):
+    if not policy_path:
+        return load_policy(None)
+    p = Path(policy_path)
+    if not p.exists():
+        return load_policy(None)
+    return load_policy(p)
+
+
+def _handle_tools_call(params: dict[str, Any]) -> dict[str, Any]:
+    name = params.get("name")
+    args = params.get("arguments") or {}
+
+    if name == "contextduty_scan_text":
+        text = args.get("text")
+        if not isinstance(text, str):
+            raise ValueError("Missing required argument: text")
+        policy = _load_policy(args.get("policyPath"))
+        result = scan_text(text, policy)
+        structured = {
+            "findings_count": result.scan.findings_count,
+            "detector_counts": result.scan.detector_counts,
+            "blocked": result.scan.blocked,
+            "redacted_text": result.redacted_text,
+        }
+        report = json.dumps(structured, indent=2)
+        return _tool_result(report, is_error=result.scan.blocked, structured=structured)
+
+    if name == "contextduty_scan":
+        path = args.get("path")
+        if not isinstance(path, str) or not path:
+            raise ValueError("Missing required argument: path")
+        policy = _load_policy(args.get("policyPath"))
+        result = scan_file(Path(path), policy)
+        report = report_to_json(result)
+        structured = {
+            "findings_count": result.findings_count,
+            "detector_counts": result.detector_counts,
+            "blocked": result.blocked,
+        }
+        return _tool_result(report, is_error=False, structured=structured)
+
+    if name == "contextduty_redact":
+        input_path = args.get("inputPath")
+        output_path = args.get("outputPath")
+        if not isinstance(input_path, str) or not input_path:
+            raise ValueError("Missing required argument: inputPath")
+        if not isinstance(output_path, str) or not output_path:
+            raise ValueError("Missing required argument: outputPath")
+        policy = _load_policy(args.get("policyPath"))
+        result = redact_file(Path(input_path), Path(output_path), policy)
+        report = report_to_json(result)
+        structured = {
+            "findings_count": result.findings_count,
+            "detector_counts": result.detector_counts,
+            "blocked": result.blocked,
+            "output_path": output_path,
+        }
+        return _tool_result(report, is_error=False, structured=structured)
+
+    raise KeyError(f"Unknown tool: {name}")
+
+
+def run_stdio() -> None:
+    for raw in sys.stdin:
+        raw = raw.strip()
+        if not raw:
+            continue
+
+        try:
+            msg = json.loads(raw)
+        except Exception:
+            continue
+
+        _id = msg.get("id")
+        method = msg.get("method")
+        params = msg.get("params") or {}
+
+        if _id is None:
+            continue
+
+        try:
+            if method == "initialize":
+                result = {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "contextduty", "version": "0.1.0"},
+                }
+                _send(_ok(_id, result))
+                continue
+
+            if method == "tools/list":
+                _send(_ok(_id, {"tools": _tools_list()}))
+                continue
+
+            if method == "tools/call":
+                try:
+                    payload = _handle_tools_call(params)
+                    _send(_ok(_id, payload))
+                except KeyError as e:
+                    _send(_err(_id, -32602, str(e)))
+                except Exception as e:
+                    _send(_ok(_id, _tool_result(f"{type(e).__name__}: {e}", is_error=True)))
+                continue
+
+            _send(_err(_id, -32601, f"Method not found: {method}"))
+        except Exception as e:
+            _send(_err(_id, -32603, f"Server error: {type(e).__name__}: {e}"))
+
+
+def main() -> None:
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()

contextduty/policy.py

@@ -0,0 +1,146 @@
+"""Simple policy loading for ContextDuty."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .detectors import DETECTORS
+
+
+@dataclass(frozen=True)
+class Policy:
+    mode: str
+    detectors: set[str]
+    custom_detectors: dict[str, str]
+
+
+DEFAULT_POLICY = {
+    "mode": "redact",
+    "detectors": ["email", "phone", "api_key", "aws_key", "bearer_token"],
+    "custom_detectors": {},
+}
+
+
+def write_default_policy(path: Path) -> None:
+    path.write_text(json.dumps(DEFAULT_POLICY, indent=2) + "\n", encoding="utf-8")
+
+
+def _read_policy_config(path: Path) -> dict[str, Any]:
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"policy file must contain a JSON object: {path}")
+    return raw
+
+
+def _normalize_extends(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value
+    raise ValueError("policy extends must be a string or list of strings")
+
+
+def _merge_policy_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = dict(base)
+
+    base_detectors = base.get("detectors", [])
+    override_detectors = override.get("detectors", [])
+    if not isinstance(base_detectors, list) or not all(
+        isinstance(name, str) for name in base_detectors
+    ):
+        raise ValueError("policy detectors must be a list of strings")
+    if not isinstance(override_detectors, list) or not all(
+        isinstance(name, str) for name in override_detectors
+    ):
+        raise ValueError("policy detectors must be a list of strings")
+    merged["detectors"] = list(dict.fromkeys(base_detectors + override_detectors))
+
+    base_custom = base.get("custom_detectors", {})
+    override_custom = override.get("custom_detectors", {})
+    if not isinstance(base_custom, dict) or not isinstance(override_custom, dict):
+        raise ValueError("policy custom_detectors must be an object of {name: regex}")
+    merged["custom_detectors"] = {**base_custom, **override_custom}
+
+    if "mode" in override:
+        merged["mode"] = override["mode"]
+
+    return merged
+
+
+def _resolve_policy_config(path: Path, seen: set[Path] | None = None) -> dict[str, Any]:
+    seen = seen or set()
+    resolved_path = path.resolve()
+    if resolved_path in seen:
+        raise ValueError(f"policy extends cycle detected at: {resolved_path}")
+    seen.add(resolved_path)
+
+    config = _read_policy_config(resolved_path)
+    parent_refs = _normalize_extends(config.get("extends"))
+
+    merged: dict[str, Any] = {
+        "mode": DEFAULT_POLICY["mode"],
+        "detectors": list(DEFAULT_POLICY["detectors"]),
+        "custom_detectors": dict(DEFAULT_POLICY["custom_detectors"]),
+    }
+
+    for parent_ref in parent_refs:
+        parent_path = (resolved_path.parent / parent_ref).resolve()
+        parent_config = _resolve_policy_config(parent_path, seen)
+        merged = _merge_policy_configs(merged, parent_config)
+
+    local_config = dict(config)
+    local_config.pop("extends", None)
+    merged = _merge_policy_configs(merged, local_config)
+
+    seen.remove(resolved_path)
+    return merged
+
+
+def load_policy(path: Path | None) -> Policy:
+    if path is None:
+        config = DEFAULT_POLICY
+    else:
+        config = _resolve_policy_config(path)
+    mode = str(config.get("mode", "redact")).lower()
+    if mode not in {"redact", "warn", "block"}:
+        raise ValueError("policy mode must be one of: redact, warn, block")
+    detectors_raw = config.get("detectors", DEFAULT_POLICY["detectors"])
+    if not isinstance(detectors_raw, list) or not all(
+        isinstance(name, str) for name in detectors_raw
+    ):
+        raise ValueError("policy detectors must be a list of strings")
+
+    custom_raw = config.get("custom_detectors", {})
+    if not isinstance(custom_raw, dict):
+        raise ValueError("policy custom_detectors must be an object of {name: regex}")
+
+    built_in_names = {detector.name for detector in DETECTORS}
+    custom_detectors: dict[str, str] = {}
+    for name, pattern in custom_raw.items():
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("custom detector names must be non-empty strings")
+        if name in built_in_names:
+            raise ValueError(f"custom detector name '{name}' conflicts with built-in detector")
+        if not isinstance(pattern, str) or not pattern.strip():
+            raise ValueError(f"custom detector '{name}' must have a non-empty regex string")
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            raise ValueError(f"invalid regex for custom detector '{name}': {exc}") from exc
+        custom_detectors[name] = pattern
+
+    # Automatically activate custom detectors so users only need to define regex once.
+    detectors = set(detectors_raw) | set(custom_detectors.keys())
+    return Policy(mode=mode, detectors=detectors, custom_detectors=custom_detectors)
+
+
+def unknown_detector_names(policy: Policy) -> list[str]:
+    built_in_names = {detector.name for detector in DETECTORS}
+    allowed = built_in_names | set(policy.custom_detectors.keys())
+    return sorted(name for name in policy.detectors if name not in allowed)

contextduty-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+contextduty/__init__.py,sha256=RsYWwXsCEQFdXkuVg6YAvEgMaB2O7Ui-7kaIVx69k1I,94
+contextduty/cli.py,sha256=CGrAXIb4GgwzXgGQFXUhEx5A1z3JzutQ5hGCXbY8UX4,4837
+contextduty/detectors.py,sha256=wGzUtWX5lOaeIPhEtX1ZkvzPSPBh_jUeLbBZUXydbqU,932
+contextduty/engine.py,sha256=KIStKqJgu6AWmjbJfqrYNiaxO_exSOVf7s2736eoutA,4442
+contextduty/mcp_server.py,sha256=T2453N2UzQag1zAtvtwnEUnY9Mw-KJXvKf0TiLEvIPg,7671
+contextduty/policy.py,sha256=Bh_5x0LOtDkSUgaLPROWkSsDYo9YGIWIVee0-waOUHA,5401
+contextduty-0.1.0.dist-info/licenses/LICENSE,sha256=vR5-qkFfm6Jm_XXmjmaXDwpoRVNuf7vVXiCmqwpUWqc,1081
+contextduty-0.1.0.dist-info/METADATA,sha256=gRS2NkYtKMLRaQ9VvlkvahqqZzx972wmEbFo93PLMvo,7341
+contextduty-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+contextduty-0.1.0.dist-info/entry_points.txt,sha256=Pf4EFfq94zaghOkbljA5naebe82r5sIgLuuY1gWlq1s,99
+contextduty-0.1.0.dist-info/top_level.txt,sha256=rNp859RPbeDgQ_q--0-JeSV0uBsfzWNU5-gEdukJ108,12
+contextduty-0.1.0.dist-info/RECORD,,

contextduty-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

contextduty-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+contextduty = contextduty.cli:main
+contextduty-mcp = contextduty.mcp_server:main

contextduty-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+contextduty