controlzero 1.11.6__tar.gz → 1.11.8__tar.gz

{controlzero-1.11.6 → controlzero-1.11.8}/.gitignore

@@ -29,7 +29,15 @@ out/
 apps/control-zero-platform/backend/server
 
 # Test & Coverage
+# NOTE: the bare `coverage/` pattern is unanchored, so git matches a
+# directory named `coverage` at ANY depth -- including the Next.js app
+# route `app/[locale]/governance/coverage/`. That silently kept the
+# Coverage admin page out of every build and 404'd it in prod (#1180).
+# Re-include the application route below so it ships. The brackets in
+# `[locale]` are escaped because git treats an unescaped `[...]` as a
+# character class, which would make the negation silently not match.
 coverage/
+!apps/control-zero-platform/frontend/app/\[locale\]/governance/coverage/
 htmlcov/
 .coverage
 *.lcov

{controlzero-1.11.6 → controlzero-1.11.8}/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 1.11.8 -- 2026-06-22 (DLP mask enforcement + I/O capture: enrolled-machine capture fix + server-side PII redaction)
+
+### Added
+
+- **I/O capture now fires on the enrolled-agent path (#1390 / #1432).** The
+  agent-hook I/O capture producer ships input/output payloads on every tool
+  call (`capture_resolved` defaults true); the server cascade + master gate
+  decide persistence. Pairs with the backend fix that threads the enrolled
+  machine's `project_id` through the capture cascade so a project-scoped
+  install actually captures (previously the machine-auth ingest hardcoded the
+  project override off and captured nothing). The producer performs no
+  client-side redaction by design -- secret + structured-PII redaction happen
+  server-side before persist (#1433), and captured payloads are sealed under a
+  per-record DEK.
+
+- **DLP `mask` action enforced in the SDK (#1278 kakaopay checklist #6).**
+  The `mask` action now redacts matched sensitive spans in the tool arguments
+  (modify-and-proceed) instead of only being recorded as a finding. When a DLP
+  rule matches with `action="mask"` on an `allow` decision, the enforcer
+  rewrites each sensitive span to a value-free `[REDACTED-<RULE_ID-UPPER>]`
+  token, stashes the redacted args on `PolicyDecision.masked_args`, and records
+  the placeholder (never the raw value) in `dlp_findings`. The placeholder
+  matches the gateway `response_dlp.mask_text` path and the Rust core
+  `pii::redact_placeholder` byte-for-byte. `block` still hard-vetoes to deny
+  (and wins over a co-matching mask); `detect`, `allow`, `warn`, and
+  policy-level deny are unchanged. Byte-identical with the Node SDK via the
+  shared `tests/parity/dlp_mask.json` conformance vector. Masking is leak-safe
+  on three edge cases code review flagged: non-string scalar leaves (a JSON
+  number like `{"card": 4111111111111111}` is masked, not passed through raw),
+  overlapping/nested mask spans (coalesced into a single clean placeholder with
+  no stale-offset residue), and cross-argument matches (DLP detects on the
+  flattened arg text but masks per-leaf; a mask match that spans two args has
+  no covering leaf, so the enforcer re-scans the masked args and FAILS CLOSED
+  to a `DLP_BLOCKED` deny rather than forwarding an un-redactable value). On
+  that fail-closed deny path the audit records ONLY the value-free mask
+  placeholder -- a co-matching `detect` rule's raw matched value is excluded so
+  no raw PII lands in the audit even on a block (#202).
+
+## 1.11.7 -- 2026-06-22 (agent tamper-resistance: hook-integrity baseline + detect/audit/alert)
+
+Adds agent tamper-resistance detection for the coding-agent hooks the SDK
+installs. A security evaluator's first move is to install the guard and then
+defeat it by deleting or editing the hook; before this release that removal was
+silent until the next tool call (which, with the hook gone, never ran). Now it
+is detected, audited, and alerted.
+
+### Added
+
+- **Hook-integrity baseline (`controlzero/hook_integrity.py`).** Every
+  `install` / `kiro init` host writer (Claude Code, Gemini CLI, Codex CLI,
+  Cursor, Antigravity, Kiro CLI v2/v3, Kiro IDE) now records a signed baseline
+  (`~/.controlzero/hook_baseline.json`) of the Control Zero hook command(s) and
+  a hash of each host config it wrote. The baseline is HMAC-signed with the same
+  `tamper.key` the policy-bundle signer uses, so a forged baseline that hides a
+  removed hook needs the secret.
+- **Drift detection + audit + alert.** At `hook-check`, `heartbeat`, and a new
+  `controlzero verify` command, the SDK compares live host configs against the
+  baseline and classifies each as `missing` (hook command removed), `modified`
+  (command changed/repointed, OR a load-bearing enablement field flipped to
+  disable the hook while the command stays in place), or `config_missing`
+  (config file deleted). The `modified` check uses a SHA-256 over the canonical
+  Control-Zero region (the hook entries carrying a CZ command WITH their
+  enablement siblings: Cursor `failClosed`, Kiro `enabled`, Codex `config.toml`
+  `codex_hooks`), so disabling the hook without removing the command string is
+  detected -- while an unrelated edit elsewhere in the config does NOT alarm. A
+  finding writes a `hook_tamper_detected` / `enforcement_disabled` event to the
+  local audit log and fires the existing best-effort `/v1/sdk/tamper-alert`
+  backend alert the admin console surfaces. DETECT + AUDIT + ALERT only -- the
+  tool decision is not changed (a benign config edit never bricks the agent).
+- **Bypass env-var detection.** Flags enforcement-downgrade environment
+  variables (`CONTROLZERO_CREDLEAK_OFF`, `CONTROLZERO_DLP_OFF`,
+  `CONTROLZERO_LOCAL_OVERRIDE`, and the general `CONTROLZERO_*_OFF` /
+  `*_DISABLE` pattern) at the same surfaces. Benign operational flags
+  (`CONTROLZERO_SPOOL_KEYCHAIN_DISABLE`, `CONTROLZERO_QUIET`) are allow-listed
+  so legit config never raises a false alert.
+- **`controlzero verify`** command: on-demand / heartbeat integrity check. Exit
+  0 = clean, 3 = tamper detected, 4 = no baseline recorded yet. `--json` for
+  machine output; `--no-report` to inspect without auditing/alerting.
+
+Honest scope (#202): this is DETECT + AUDIT, not prevention. It makes hook
+removal / modification / disable visible in the audit log and admin console; it
+does not, by itself, stop an operator with write access from removing the hook
+(that needs OS-level immutability / MDM, out of SDK scope).
+
 ## 1.11.6 -- 2026-06-21 (cross-surface enforcement hardening: Kiro v3 + Antigravity honesty + warn-mode)
 
 Ships the #1373 / #65 cross-surface enforcement work and follow-ups that landed

{controlzero-1.11.6 → controlzero-1.11.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.11.6
+Version: 1.11.8
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.11.6 → controlzero-1.11.8}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.11.6"
+__version__ = "1.11.8"
 
 __all__ = [
     "Client",

{controlzero-1.11.6 → controlzero-1.11.8}/controlzero/_internal/dlp_scanner.py

@@ -597,6 +597,29 @@ class DLPMatch:
     matched_text: str  # plaintext for pii/financial, SHA-256 hash for secret
     offset: int
     count: int = 1
+    # Length of the matched span in the SOURCE text. Carried so the
+    # masker can splice the exact span out of a string value without
+    # re-running the regex. Defaults to len(matched_text) so DLPMatch
+    # objects built by older callers (and the secret path, where
+    # matched_text is a hash, not the raw value) still report a sensible
+    # length -- but the masker only ever uses the span length recorded at
+    # scan time, never the hash length.
+    length: int = 0
+
+
+def mask_placeholder(rule_id: str) -> str:
+    """Stable, value-free mask placeholder matching gateway ENFORCEMENT exactly.
+
+    Production masking (Rust ``pii::redact_placeholder``, standardized in #961,
+    the gateway ``response_dlp.mask_text`` path, and the DLP test panel
+    ``dlp_test_engine._redact_placeholder``) renders a detector/rule as
+    ``[REDACTED-<ID-UPPER>]`` -- derived ONLY from the rule id, never from the
+    matched value, so it cannot leak any portion of the original sensitive
+    bytes. The SDK mask action MUST emit the identical token or the SDK and
+    gateway surfaces would mask the same value differently (#202 honesty).
+    """
+    base = (rule_id or "PII").upper().replace(" ", "_")
+    return f"[REDACTED-{base}]"
 
 
 class DLPScanner:
@@ -688,6 +711,10 @@ class DLPScanner:
                         action=rule.action,
                         matched_text=display_text,
                         offset=m.start(),
+                        # Span length in the SOURCE text (NOT len(display_text),
+                        # which for secrets is a 64-char hash). The masker splices
+                        # exactly [offset, offset+length) out of the string value.
+                        length=len(raw_text),
                     )
                 )
 
@@ -697,11 +724,125 @@ class DLPScanner:
         """Check if any match has action='block'."""
         return any(m.action == "block" for m in matches)
 
+    def has_masking_match(self, matches: list[DLPMatch]) -> bool:
+        """Check if any match has action='mask'."""
+        return any(m.action == "mask" for m in matches)
+
+    def mask_text(self, text: str, matches: list[DLPMatch]) -> str:
+        """Redact every action='mask' span in ``text`` with a value-free token.
+
+        Matches the gateway ``response_dlp.mask_text`` semantics:
+        each span is replaced by ``[REDACTED-<RULE_ID-UPPER>]`` -- a token
+        derived only from the rule id, never from the matched bytes.
+
+        Overlapping / nested spans are COALESCED before splicing. Two different
+        rules can match overlapping byte ranges (e.g. a broad ``ABCDEF`` rule
+        and a narrow ``CD`` rule, or a card rule whose span contains a digit-run
+        rule). A naive right-to-left splice would apply the inner span, mutate
+        the string, then apply the outer span against STALE offsets -- leaving
+        original tail bytes and a corrupted placeholder (a SILENT LEAK). So we
+        first merge every overlapping/adjacent mask span into one
+        non-overlapping interval, each rendered as a single clean placeholder
+        (the earliest-starting, then widest, rule's id wins for the merged
+        interval). The merged intervals are then spliced right-to-left so each
+        replacement leaves the offsets of the not-yet-applied intervals valid.
+
+        Only mask-action matches are spliced; detect/block matches are left in
+        place (block is handled separately as a deny, detect is observe-only).
+        Returns ``text`` unchanged when no mask span applies.
+        """
+        mask_matches = [m for m in matches if m.action == "mask" and m.length > 0]
+        if not mask_matches:
+            return text
+
+        # Sort by start, then by widest span first, so a covering span is seen
+        # before the spans it contains and its id labels the merged interval.
+        ordered = sorted(
+            mask_matches, key=lambda m: (m.offset, -(m.offset + m.length))
+        )
+        # Coalesce overlapping / nested / adjacent spans into clean intervals.
+        intervals: list[tuple[int, int, str]] = []  # (start, end, rule_id)
+        for m in ordered:
+            start = m.offset
+            end = m.offset + m.length
+            if intervals and start <= intervals[-1][1]:
+                # Overlaps (or is adjacent to) the current interval: extend it.
+                # Keep the FIRST rule_id (the covering / earliest span's label)
+                # so a nested match never produces a second mangled placeholder.
+                prev_start, prev_end, prev_id = intervals[-1]
+                intervals[-1] = (prev_start, max(prev_end, end), prev_id)
+            else:
+                intervals.append((start, end, m.rule_id))
+
+        # Splice right-to-left so earlier intervals' offsets stay valid.
+        out = text
+        for start, end, rule_id in sorted(intervals, key=lambda iv: iv[0], reverse=True):
+            out = out[:start] + mask_placeholder(rule_id) + out[end:]
+        return out
+
+    def mask_args(self, args: Any) -> tuple[Any, list[DLPMatch]]:
+        """Walk ``args`` and mask every action='mask' span in each string leaf.
+
+        Modify-and-proceed: returns a NEW args structure (the original is never
+        mutated) with sensitive spans replaced by value-free
+        ``[REDACTED-<RULE_ID-UPPER>]`` tokens, plus the flat list of every
+        DLPMatch seen across all string leaves (so the caller can build the
+        audit findings and decide whether any block/detect action also fired).
+
+        Each string leaf is scanned INDEPENDENTLY (not the joined-with-newline
+        blob ``extract_text_from_args`` produces) so the per-leaf offsets the
+        masker splices are valid against that exact leaf. This is the key
+        difference from detect/block, which only need the flattened text.
+        """
+        all_matches: list[DLPMatch] = []
+        masked = self._mask_recursive(args, all_matches)
+        return masked, all_matches
+
+    def _mask_recursive(self, obj: Any, all_matches: list[DLPMatch]) -> Any:
+        """Recursively rebuild ``obj`` with mask spans redacted in every leaf."""
+        if isinstance(obj, str):
+            leaf_matches = self.scan(obj)
+            if leaf_matches:
+                all_matches.extend(leaf_matches)
+            return self.mask_text(obj, leaf_matches)
+        if isinstance(obj, dict):
+            return {k: self._mask_recursive(v, all_matches) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            rebuilt = [self._mask_recursive(item, all_matches) for item in obj]
+            return type(obj)(rebuilt) if isinstance(obj, tuple) else rebuilt
+        # Non-string scalar leaves (numbers, bools). The DETECTION path
+        # stringifies these (extract_text_from_args -> str(obj)), so a JSON
+        # NUMBER like {"card": 4111111111111111} matches a mask rule and enters
+        # the mask path. If the masker returned the raw scalar unchanged, the
+        # sensitive value would survive in masked_args AND no audit finding
+        # would be emitted -- a silent leak, and the common case for Korean
+        # card / account / RRN values that arrive as numbers. So we mask
+        # non-string scalars too: stringify, scan, and if any mask span fired
+        # return the MASKED STRING (number -> string in the masked output is
+        # correct; the agent must not receive the raw value). None and other
+        # non-scalars carry no maskable span and pass through unchanged.
+        if obj is None:
+            return obj
+        if isinstance(obj, (int, float, bool)):
+            as_text = str(obj)
+            leaf_matches = self.scan(as_text)
+            mask_leaf = [m for m in leaf_matches if m.action == "mask" and m.length > 0]
+            if mask_leaf:
+                all_matches.extend(leaf_matches)
+                return self.mask_text(as_text, leaf_matches)
+            # No mask span -> preserve the original scalar type unchanged.
+            return obj
+        return obj
+
     def get_findings_for_audit(self, matches: list[DLPMatch]) -> list[dict]:
         """Convert matches to audit-safe findings.
 
         For secret-category matches, only count is included (no text).
-        For other categories, the matched text is included.
+        For mask-action matches, the raw value is REPLACED by the value-free
+        mask placeholder ("audit shows the masked value, never the secret") --
+        consistent with the gateway, which renders a mask as a value-free
+        ``[REDACTED-...]`` token everywhere. For other (detect) categories the
+        matched text is included.
         """
         findings: list[dict] = []
         for m in matches:
@@ -711,8 +852,15 @@ class DLPScanner:
                 "action": m.action,
                 "count": m.count,
             }
-            # Never include matched text for secrets in audit
-            if m.category != "secret":
+            if m.action == "mask":
+                # Mask is enforcement, not observation: the audit row records
+                # WHAT the value was masked TO (the value-free placeholder),
+                # never the raw bytes -- even for pii/financial categories that
+                # would otherwise echo plaintext under "detect".
+                entry["masked"] = True
+                entry["matched_text"] = mask_placeholder(m.rule_id)
+            elif m.category != "secret":
+                # Never include matched text for secrets in audit
                 entry["matched_text"] = m.matched_text
             findings.append(entry)
         return findings

{controlzero-1.11.6 → controlzero-1.11.8}/controlzero/_internal/enforcer.py

@@ -224,6 +224,16 @@ class PolicyDecision:
     reason_code: str = ""
     evaluated_rules: int = 0
     dlp_findings: list[dict] = field(default_factory=list)
+    # DLP MASK action (#1278 kakaopay checklist #6, parity with the gateway
+    # ``response_dlp.mask_text`` path). When a DLP rule matches with
+    # action="mask" on an ALLOW decision, the enforcer redacts the sensitive
+    # spans in the tool arguments (modify-and-proceed) and stashes the
+    # redacted args here. None when no mask rule fired -- the caller then
+    # forwards the ORIGINAL args unchanged. When set, the host/caller MUST
+    # forward THESE args instead so the sensitive value never reaches the
+    # tool. The redaction uses the value-free ``[REDACTED-<RULE_ID-UPPER>]``
+    # token; the original plaintext is never carried on the decision.
+    masked_args: Optional[dict] = None
     # Phase 1B (#451): version of the policy engine that produced this
     # decision. Sourced from crates/controlzero-core's Cargo workspace
     # version today (constant POLICY_ENGINE_VERSION in this module).
@@ -631,9 +641,18 @@ class PolicyEvaluator:
     ) -> PolicyDecision:
         """Run DLP scanner on tool arguments and update decision if needed.
 
-        If any DLP rule has action="block", the decision is overridden to DENY.
-        If rules have action="detect" or "mask", findings are attached to the
-        decision for audit but the call is still allowed.
+        Action precedence (highest first):
+
+        * ``block`` -- the decision is overridden to DENY. block is a
+          hard veto: even if other rules want to mask, a single block hit
+          fails the call closed.
+        * ``mask``  -- the call is ALLOWED but the sensitive spans in the
+          tool arguments are redacted in place (modify-and-proceed). The
+          redacted args are stashed on ``decision.masked_args`` and the
+          audit findings record the value-free ``[REDACTED-...]`` token,
+          matching the gateway ``response_dlp.mask_text`` semantics.
+        * ``detect`` -- findings are attached for audit; the call is allowed
+          and the arguments are forwarded unchanged.
         """
         if self._dlp_scanner is None:
             return decision
@@ -646,10 +665,11 @@ class PolicyEvaluator:
         if not matches:
             return decision
 
-        findings = self._dlp_scanner.get_findings_for_audit(matches)
-        decision.dlp_findings = findings
-
         if self._dlp_scanner.has_blocking_match(matches):
+            # Block wins over mask/detect. Build the audit findings from the
+            # FLAT scan (block is a deny -- no arg rewrite happens).
+            findings = self._dlp_scanner.get_findings_for_audit(matches)
+            decision.dlp_findings = findings
             # Find the first blocking rule for the reason message
             blocking = next(m for m in matches if m.action == "block")
             return PolicyDecision(
@@ -674,6 +694,74 @@ class PolicyEvaluator:
                 gate_matched=decision.gate_matched,
             )
 
+        if self._dlp_scanner.has_masking_match(matches):
+            # MASK: modify-and-proceed. Re-scan each string leaf
+            # INDEPENDENTLY so the per-leaf offsets the masker splices are
+            # valid against that exact leaf (the flat blob's offsets are
+            # not). ``mask_args`` returns the redacted args + the per-leaf
+            # matches; audit findings come from those so a mask never echoes
+            # the raw value.
+            masked_args, leaf_matches = self._dlp_scanner.mask_args(args)
+
+            # FAIL-CLOSED leak guard (codex deep review of #1427). DLP DETECTS
+            # on the FLATTENED arg text (extract_text_from_args concatenates
+            # every leaf value with "\n") but MASKS per-leaf. A flat mask match
+            # that does NOT map to any single leaf -- a pattern spanning the
+            # boundary between two concatenated args, or any flat match with no
+            # covering leaf -- would NOT be redacted by the per-leaf masker,
+            # yet has_masking_match(flat) already routed us here. Returning an
+            # allow-with-masked_args in that case leaks the raw value with a
+            # "masked" verdict. So we VERIFY the post-condition: re-scan the
+            # MASKED args' flattened text and confirm no mask-action match
+            # survives. If any does, the secret was not fully redacted -- fail
+            # CLOSED to a DLP_BLOCKED deny (better to block the call than ship
+            # an un-maskable secret).
+            masked_text = extract_text_from_args(masked_args)
+            residual = self._dlp_scanner.scan(masked_text) if masked_text else []
+            if self._dlp_scanner.has_masking_match(residual):
+                # Build the deny's audit findings from ONLY the residual
+                # MASK-action matches. A co-matching DETECT-action rule (e.g. a
+                # detect rule on "SECRET" that also fires on the un-maskable
+                # value) would otherwise have get_findings_for_audit echo its
+                # RAW matched_text into the audit row -- raw PII in the audit
+                # even on a block is a #202 leak (codex re-review of #1427).
+                # Mask findings render as the value-free [REDACTED-...]
+                # placeholder, so this records THAT a mask rule fired and was
+                # blocked, never the matched bytes. (Block-action matches can't
+                # appear here: a block hit is handled earlier and short-circuits
+                # to deny before the mask branch.)
+                residual_mask_only = [m for m in residual if m.action == "mask"]
+                offending = residual_mask_only[0]
+                return PolicyDecision(
+                    effect="deny",
+                    policy_id=decision.policy_id,
+                    reason=(
+                        f"DLP rule '{offending.rule_name}' matched "
+                        f"{offending.category} content that spans argument "
+                        "boundaries and could not be safely masked; blocking "
+                        "(fail-closed) rather than forwarding an un-redacted value"
+                    ),
+                    reason_code=REASON_CODE_DLP_BLOCKED,
+                    evaluated_rules=decision.evaluated_rules,
+                    # Audit the firing MASK rule(s) WITHOUT echoing the raw
+                    # value: get_findings_for_audit renders mask findings as the
+                    # value-free placeholder, so the deny row records that a
+                    # mask rule fired, never the secret. Detect findings (which
+                    # carry raw text) are deliberately excluded from this path.
+                    dlp_findings=self._dlp_scanner.get_findings_for_audit(
+                        residual_mask_only
+                    ),
+                    gate_matched=decision.gate_matched,
+                )
+
+            decision.masked_args = masked_args
+            decision.dlp_findings = self._dlp_scanner.get_findings_for_audit(
+                leaf_matches
+            )
+            return decision
+
+        # detect-only: attach findings, forward args unchanged.
+        decision.dlp_findings = self._dlp_scanner.get_findings_for_audit(matches)
         return decision