phi-boundary-gate 0.5.0__py3-none-any.whl

phi_boundary_gate/__init__.py

@@ -0,0 +1,49 @@
+"""PHI boundary gating, redaction, and audit reporting."""
+
+__version__ = "0.5.0"
+
+from .api import GuardDecision, GuardMode, ScanFinding, guard_text, redact_text, scan_text
+from .compliance import (
+    ComplianceContext,
+    ComplianceDecision,
+    CompliancePolicy,
+    ServiceProfile,
+    guard_compliance,
+    load_compliance_policy,
+)
+from .policy import load_policy
+from .project import ProjectConfig, check_project_config, discover_project_config, init_project, load_project_config
+from .redacted_trace import redacted_trace_events, write_redacted_trace
+from .report import build_report, render_markdown, write_json_report, write_markdown_report
+from .sdk import PhiBoundaryGate
+from .trace import TraceEvent, load_trace
+
+__all__ = [
+    "ComplianceContext",
+    "ComplianceDecision",
+    "CompliancePolicy",
+    "GuardDecision",
+    "GuardMode",
+    "PhiBoundaryGate",
+    "ProjectConfig",
+    "ScanFinding",
+    "ServiceProfile",
+    "TraceEvent",
+    "build_report",
+    "check_project_config",
+    "discover_project_config",
+    "guard_compliance",
+    "guard_text",
+    "init_project",
+    "load_compliance_policy",
+    "load_policy",
+    "load_project_config",
+    "load_trace",
+    "redact_text",
+    "redacted_trace_events",
+    "render_markdown",
+    "scan_text",
+    "write_json_report",
+    "write_markdown_report",
+    "write_redacted_trace",
+]

phi_boundary_gate/actions.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+
+DISPOSITION_RANK = {"allowed": 0, "redact": 1, "violation": 2}
+
+
+def redaction_action(disposition: str) -> str:
+    if disposition == "violation":
+        return "remove_or_redact_before_this_layer"
+    if disposition == "redact":
+        return "redact_before_this_layer"
+    return "review"
+
+
+def recommended_boundary_action(disposition: str, layer: str) -> str:
+    if disposition == "violation":
+        return f"Remove or redact before {layer}."
+    if disposition == "redact":
+        return f"Redact before {layer}."
+    return "Review only; no policy boundary action required."
+
+
+def worst_disposition(dispositions: list[str]) -> str:
+    if not dispositions:
+        return "allowed"
+    return max(dispositions, key=lambda item: DISPOSITION_RANK[item])

phi_boundary_gate/api.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping, Sequence
+
+from .actions import redaction_action, recommended_boundary_action, worst_disposition
+from .detectors import detect_candidates
+from .policy import Policy
+from .trace import SUPPORTED_LAYERS, supported_layers_text
+
+GuardMode = Literal["report_only", "redact", "block_on_violation"]
+
+
+@dataclass(frozen=True)
+class ScanFinding:
+    layer: str
+    category: str
+    value: str
+    start: int
+    end: int
+    confidence: float
+    reason: str
+    disposition: str
+    risk: str
+    rule: str
+    redaction_action: str
+    redaction: str
+
+    @property
+    def span(self) -> dict[str, int]:
+        return {"start": self.start, "end": self.end}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "layer": self.layer,
+            "category": self.category,
+            "value": self.value,
+            "span": self.span,
+            "confidence": self.confidence,
+            "reason": self.reason,
+            "policy": {
+                "disposition": self.disposition,
+                "risk": self.risk,
+                "rule": self.rule,
+            },
+            "redaction": {
+                "action": self.redaction_action,
+                "suggested_value": self.redaction,
+            },
+        }
+
+    def __getitem__(self, key: str) -> Any:
+        return self.to_dict()[key]
+
+
+@dataclass(frozen=True)
+class GuardDecision:
+    text: str
+    layer: str
+    mode: GuardMode
+    findings: list[ScanFinding]
+    redacted_text: str
+    has_phi: bool
+    has_redactions: bool
+    has_violations: bool
+    worst_disposition: str
+    recommended_action: str
+    should_block: bool
+    should_redact: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "text": self.text,
+            "layer": self.layer,
+            "mode": self.mode,
+            "findings": [finding.to_dict() for finding in self.findings],
+            "redacted_text": self.redacted_text,
+            "has_phi": self.has_phi,
+            "has_redactions": self.has_redactions,
+            "has_violations": self.has_violations,
+            "worst_disposition": self.worst_disposition,
+            "recommended_action": self.recommended_action,
+            "should_block": self.should_block,
+            "should_redact": self.should_redact,
+        }
+
+    def to_safe_dict(self) -> dict[str, Any]:
+        return {
+            "layer": self.layer,
+            "mode": self.mode,
+            "finding_count": len(self.findings),
+            "categories": sorted({finding.category for finding in self.findings}),
+            "has_phi": self.has_phi,
+            "has_redactions": self.has_redactions,
+            "has_violations": self.has_violations,
+            "worst_disposition": self.worst_disposition,
+            "recommended_action": self.recommended_action,
+            "should_block": self.should_block,
+            "should_redact": self.should_redact,
+            "redacted_text": self.redacted_text,
+        }
+
+
+def scan_text(text: str, layer: str, policy: Policy, *, enable_presidio: bool = False) -> list[ScanFinding]:
+    if layer not in SUPPORTED_LAYERS:
+        raise ValueError(f"unsupported layer {layer!r}; expected one of: {supported_layers_text()}")
+
+    findings: list[ScanFinding] = []
+    for candidate in detect_candidates(text, enable_presidio=enable_presidio):
+        decision = policy.decide(candidate.category, layer)
+        findings.append(
+            ScanFinding(
+                layer=layer,
+                category=candidate.category,
+                value=candidate.value,
+                start=candidate.start,
+                end=candidate.end,
+                confidence=candidate.confidence,
+                reason=candidate.reason,
+                disposition=decision.disposition,
+                risk=decision.risk,
+                rule=decision.rule,
+                redaction_action=redaction_action(decision.disposition),
+                redaction=decision.redaction,
+            )
+        )
+    return findings
+
+
+def redact_text(text: str, findings: Sequence[ScanFinding | Mapping[str, Any]]) -> str:
+    replacements = _non_overlapping_replacements(findings)
+    redacted = text
+    for start, end, replacement in reversed(replacements):
+        redacted = f"{redacted[:start]}{replacement}{redacted[end:]}"
+    return redacted
+
+
+def guard_text(
+    text: str,
+    layer: str,
+    policy: Policy,
+    mode: GuardMode = "report_only",
+    *,
+    enable_presidio: bool = False,
+) -> GuardDecision:
+    if mode not in ("report_only", "redact", "block_on_violation"):
+        raise ValueError("mode must be one of: report_only, redact, block_on_violation")
+
+    findings = scan_text(text, layer, policy, enable_presidio=enable_presidio)
+    redacted_text = redact_text(text, findings)
+    dispositions = [finding.disposition for finding in findings]
+    worst = worst_disposition(dispositions)
+    worst_layer = layer if findings else ""
+    has_redactions = redacted_text != text
+    has_violations = any(disposition == "violation" for disposition in dispositions)
+    should_block = mode == "block_on_violation" and has_violations
+    should_redact = mode == "redact" and has_redactions
+
+    return GuardDecision(
+        text=text,
+        layer=layer,
+        mode=mode,
+        findings=findings,
+        redacted_text=redacted_text,
+        has_phi=bool(findings),
+        has_redactions=has_redactions,
+        has_violations=has_violations,
+        worst_disposition=worst,
+        recommended_action=recommended_boundary_action(worst, worst_layer) if findings else "No PHI candidates found.",
+        should_block=should_block,
+        should_redact=should_redact,
+    )
+
+
+def _non_overlapping_replacements(findings: Sequence[ScanFinding | Mapping[str, Any]]) -> list[tuple[int, int, str]]:
+    ordered = sorted(
+        findings,
+        key=lambda finding: (
+            _finding_start(finding),
+            -(_finding_end(finding) - _finding_start(finding)),
+        ),
+    )
+    replacements: list[tuple[int, int, str]] = []
+    occupied_until = -1
+    for finding in ordered:
+        start = _finding_start(finding)
+        end = _finding_end(finding)
+        if start < occupied_until:
+            continue
+        replacements.append((start, end, _finding_redaction(finding)))
+        occupied_until = end
+    return replacements
+
+
+def _finding_start(finding: ScanFinding | Mapping[str, Any]) -> int:
+    if isinstance(finding, ScanFinding):
+        return finding.start
+    return int(finding["span"]["start"])
+
+
+def _finding_end(finding: ScanFinding | Mapping[str, Any]) -> int:
+    if isinstance(finding, ScanFinding):
+        return finding.end
+    return int(finding["span"]["end"])
+
+
+def _finding_redaction(finding: ScanFinding | Mapping[str, Any]) -> str:
+    if isinstance(finding, ScanFinding):
+        return finding.redaction
+    return str(finding["redaction"]["suggested_value"])

phi_boundary_gate/cli.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .policy import load_policy
+from .project import check_project_config, init_project
+from .redacted_trace import write_redacted_trace
+from .report import build_report, write_json_report, write_markdown_report
+from .trace import load_trace
+
+COMMANDS = {"init", "check-config", "scan-trace"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_list = list(sys.argv[1:] if argv is None else argv)
+    if args_list and args_list[0] not in COMMANDS and args_list[0] not in ("-h", "--help"):
+        return _scan_trace(args_list)
+
+    parser = argparse.ArgumentParser(description="Gate PHI boundary flows and manage project policy config.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Create project policy config files.")
+    init_parser.add_argument("--root", type=Path, default=Path.cwd(), help="Project root to initialize.")
+    init_parser.add_argument("--policy", type=Path, help="Policy path relative to --root.")
+    init_parser.add_argument("--compliance-policy", type=Path, help="Compliance policy path relative to --root.")
+    init_parser.add_argument("--force", action="store_true", help="Overwrite existing generated config files.")
+
+    check_parser = subparsers.add_parser("check-config", help="Validate discovered project config and policies.")
+    check_parser.add_argument("--root", type=Path, default=Path.cwd(), help="Start directory for config discovery.")
+
+    scan_parser = subparsers.add_parser("scan-trace", help="Scan a JSONL trace and write audit outputs.")
+    _add_scan_trace_args(scan_parser)
+
+    args = parser.parse_args(args_list)
+    if args.command == "init":
+        return _init(args)
+    if args.command == "check-config":
+        return _check_config(args)
+    return _scan_trace_from_args(args)
+
+
+def _add_scan_trace_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--trace", required=True, type=Path, help="Path to a synthetic JSONL trace.")
+    parser.add_argument("--policy", required=True, type=Path, help="Path to a YAML PHI policy.")
+    parser.add_argument("--out", required=True, type=Path, help="Path for the Markdown report.")
+    parser.add_argument("--json", required=True, type=Path, dest="json_out", help="Path for the JSON report.")
+    parser.add_argument("--redacted-trace", type=Path, help="Optional path for a redacted JSONL trace.")
+    parser.add_argument(
+        "--enable-presidio",
+        action="store_true",
+        help="Enable optional local Presidio PII detection in addition to built-in regex rules.",
+    )
+
+
+def _scan_trace(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Gate synthetic PHI boundary flows and write audit reports.")
+    _add_scan_trace_args(parser)
+    args = parser.parse_args(argv)
+    return _scan_trace_from_args(args)
+
+
+def _scan_trace_from_args(args: argparse.Namespace) -> int:
+    try:
+        events = load_trace(args.trace)
+        policy = load_policy(args.policy)
+        report = build_report(events, policy, args.trace, args.policy, enable_presidio=args.enable_presidio)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    write_markdown_report(report, args.out)
+    write_json_report(report, args.json_out)
+    if args.redacted_trace:
+        try:
+            write_redacted_trace(events, policy, args.redacted_trace, enable_presidio=args.enable_presidio)
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+
+    summary = report["summary"]
+    redacted_note = f" and redacted trace {args.redacted_trace}" if args.redacted_trace else ""
+    print(
+        "Wrote {total} PHI candidate finding(s): {markdown} and {json}{redacted}".format(
+            total=summary["total_findings"],
+            markdown=args.out,
+            json=args.json_out,
+            redacted=redacted_note,
+        )
+    )
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    try:
+        config = init_project(
+            args.root,
+            policy_path=args.policy,
+            compliance_policy_path=args.compliance_policy,
+            force=args.force,
+        )
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"Wrote PHI Boundary Gate config: {config.config_path}")
+    print(f"Policy: {config.policy_path}")
+    if config.compliance_policy_path:
+        print(f"Compliance policy: {config.compliance_policy_path}")
+    return 0
+
+
+def _check_config(args: argparse.Namespace) -> int:
+    try:
+        config = check_project_config(args.root)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"Config ok: {config.config_path}")
+    print(f"Policy ok: {config.policy_path}")
+    if config.compliance_policy_path:
+        print(f"Compliance policy ok: {config.compliance_policy_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())