Tamper Detection and Enforcement

Control Zero cryptographically signs every policy bundle and verifies it before loading any rules. Tampering is detected before an untrusted policy can be enforced, and the configured response is applied deterministically. The same tamper detection pipeline protects local audit logs and configuration. This page explains the three protection layers, the four enforcement modes, and recovery from a tamper event.

---

How the pipeline works

Tamper detection operates at three layers:

1. Policy bundle signing

Every policy bundle published by the backend is cryptographically signed before it leaves the server. The signing key is generated per-org (lazily on first enrollment) and the corresponding public key is distributed to every enrolled machine during the enrollment handshake.

When the SDK pulls a policy bundle, it verifies the signature against the org's public key before loading any rules. If verification fails, the SDK treats the bundle as tampered and follows the org's configured tamper_behavior.

2. Local audit log hash chain

Each audit entry the SDK records locally includes a hash of the previous entry, forming an append-only chain anchored to a per-machine genesis seed. The SDK verifies chain continuity; a mismatch (entries deleted, reordered, or modified) is treated as a tamper event and handled per the org's configured tamper_behavior. This chain protects the local record on each machine. Server-side chain verification on ingest is planned but not yet implemented -- the hosted audit store today relies on append-only application semantics and application-layer org scoping, not a cryptographic chain. Database row-level security policies exist on these tables as defence in depth, but the runtime connects as a role that bypasses them, so they are not the enforcing layer today.

3. Bundle content verification

Beyond the outer signature, the SDK also checks an embedded content fingerprint inside each policy bundle. This fingerprint covers every rule definition, threshold, and scope in the bundle. Even if the outer signature were somehow replayed from an older bundle, the content fingerprint ensures the rules match what the backend actually published for the current policy_version.

---

The four tamper_behavior modes

The tamper_behavior setting controls what happens when the SDK detects a tamper event. It applies org-wide and is returned to each machine at enrollment time.

Mode	On tamper event
warn	Log a warning locally and report the event to the backend. Continue enforcing the last known good policy.
deny	Reject the tampered bundle and fall back to the last known good policy. Report the event to the backend.
deny-all	Reject all tool calls until a valid policy bundle is pulled. Report the event to the backend.
quarantine	Lock down the machine entirely: deny all tool calls and block further policy pulls until an admin intervenes.

The default mode is warn. Most orgs start here and tighten to deny or deny-all once they have confirmed their signing pipeline is stable.

---

Configuring tamper behavior

In policy YAML

Add a tamper_behavior field under settings in your policy file:

version: '1'
settings:
  tamper_behavior: deny

rules:
  - name: block-secrets
    effect: deny
    action: 'llm:generate'
    resource: '*'
    pattern: "(?i)(api[_-]?key|secret|password)\\s*[:=]"
    scopes: [sdk, gateway]

After editing the YAML, sign and publish the updated policy:

controlzero sign-policy policy.yaml
controlzero policy-pull

In the dashboard

Open Settings -> Security in the dashboard. Under the Tamper Detection card, select one of the four modes from the dropdown and click Save. The change takes effect on the next policy pull for every enrolled machine in the org.

---

Quarantine: what it does and how to recover

Quarantine is the strictest response. When a machine enters quarantine:

1. All tool calls are denied. The SDK returns a hard deny for every guard check, regardless of what the policy rules say.
2. Policy pulls are blocked. The SDK will not attempt to fetch new bundles until quarantine is cleared, preventing a potentially compromised machine from accepting further instructions.
3. A tamper alert is reported to the backend dashboard with the machine ID, timestamp, and the type of verification failure that triggered quarantine.

What triggers quarantine

Quarantine is only triggered when tamper_behavior is set to quarantine and one of the following occurs:

• A pulled policy bundle fails signature verification.
• The embedded content fingerprint does not match the declared policy_version.
• The SDK detects a break in the local audit log hash chain.

Recovery paths

There are three ways to bring a quarantined machine back to normal operation:

1. Re-enroll the machine

controlzero enroll --token FRESH_TOKEN_HERE

Re-enrollment clears quarantine state, fetches the org's current signing public key, pulls a fresh verified policy bundle, and resumes normal enforcement. This is the recommended path for most situations.

2. Force a policy pull

controlzero policy-pull --force

This bypasses the quarantine block on policy pulls, fetches the latest bundle, and re-verifies it. If verification succeeds, quarantine is cleared automatically. If it fails again, the machine remains quarantined.

3. Re-sign the policy

If the tamper event was caused by a legitimate policy update that was not properly signed (for example, a manual edit to the YAML that skipped the signing step), re-sign and re-publish:

controlzero sign-policy policy.yaml

Then have the quarantined machine run controlzero policy-pull --force to pick up the correctly signed bundle.

---

Tamper alerts in the dashboard

Every tamper event -- regardless of the configured mode -- is reported to the backend and visible in the dashboard under Governance -> Alerts.

Each alert includes:

Field	Description
Machine ID	The enrolled machine that detected the event
Hostname	The machine's hostname at enrollment time
Event type	signature_mismatch, content_fingerprint_mismatch, or hash_chain_break
Timestamp	When the SDK detected the event
Action taken	What the SDK did in response (warned, denied, quarantined)
Bundle version	The policy_version of the suspect bundle (if applicable)

Alerts are retained in the append-only audit trail; the application exposes no path to delete or modify them after creation.

---

Recommendations by org size

Org size	Recommended mode	Rationale
Small (1-10)	warn	Low blast radius; visibility without disruption while establishing trust.
Medium (10-50)	deny	Automatic fallback to last known good policy prevents silent degradation.
Large (50+)	deny-all	Full lockdown on tamper; ensures no unverified policy is ever enforced.
Regulated	quarantine	Maximum protection for compliance-sensitive environments.

Start with warn, verify that policy signing and bundle delivery are working correctly across your fleet, then tighten incrementally.