Organization policy

The organization policy is a list of rules about secrets: where they may be sent and how they are injected. Owners and admins edit it in Policies and publish a new version; every zn-gate in the organization picks it up.

Rules

Each rule applies to one secret (by name, never by value; PREFIX* and * are allowed):

How rules combine:

• All matching rules apply, top to bottom; each can only restrict further.
• deny blocks. warn lets the use through, warns the developer and records it in the audit log. A deny also applies to secrets_render_file, so a secret the policy blocks cannot be written to a file through that tool.
• Fields a rule sets only narrow the machine's local settings; fields it leaves out keep the local value. A new host needs the member's approval and is only offered while the policy is current (not once it has expired on a machine in strict mode); a host with a port is never offered; commands, modes and injectAt are never opened.

There is one policy for the whole organization, not one per agent. A deny or a warn applies to every agent on the machine, whatever agents says: the agents list only decides which agents are offered a new host.

Three states

Each rule is in one of three states, chosen in the rule editor:

A warning is shown on the developer's machine; it does not stop the use. Every warned and blocked use appears in Team → Audit log, with metadata only (no values).

Warn rules apply wherever a block applies: zn run, secrets_http_request, secrets_render_file, and the restores of markers and tokens in the agent hooks. When a warned use goes ahead, the developer and the agent see this notice: zn: your team policy would block STRIPE_API_KEY here (policy note: "..."). It was allowed and recorded for your organization. An audit record with the decision warn is uploaded to your organization. A marker restored by the hooks follows the same rules: a secret that the policy blocks stays a marker and the hook says why, and a secret under a Warn rule is restored and recorded.

Warn rules need zn-gate 1.8.0 or later. On machines with an older zn-gate, a Warn rule acts as Not blocked: the use goes through within the rule's other limits, but no warning is shown and nothing is recorded as Warned. Ask members to update zn-gate.

In an organization with Warn rules, do not go back to zn-gate 1.7.1. It refuses a policy that contains Warn rules and applies only the local settings until the next policy sync downloads a copy it can read. Stay on 1.8.0 or later.

Publishing

Publishing creates a new version. The dashboard validates it first. A blocked use is reported with reason: policy:org_deny, and a warned use is reported with reason: policy:warn and recorded in the audit log as Warned. The dashboard also refuses a rule that sets both warn and deny.

Publishing asks owners and admins for two-factor authentication. Changes proposed from a coding agent with an org admin token always wait for a person to approve them; see Manage your team from your agent.

Signature and versions

• zn serves each policy signed with your organization's Ed25519 key. Every machine verifies it against the public key it pinned when it joined.
• A served policy is valid for 7 days. Machines check for a new version regularly and when you run zn team sync.
• A machine never accepts a version lower than the last one it accepted, a policy signed with an unknown key or one whose signature does not verify. It keeps the last valid policy and logs policy:rejected.

What happens without network, or when a policy expires, is in Offline mode.

What the organization cannot do

zn-gate is a local guardrail, not an MDM. The organization policy works on top of zn-gate's built-in protections and cannot switch them off: credential files, ~/.zn and the agents' own configuration stay protected whatever the policy says.