Publishing a policy
Scope: current hosted production uses organization workspaces. Personal workspaces and owner self-review require a later control-plane upgrade; self-hosted installations depend on their actual version and identity configuration.
A policy never changes on its own. The normal route: a candidate policy is drafted, previewed against what the agents really did, reviewed by a second person, and published as a new version. Any published version can be rolled back to, which also makes a new version. Two things skip the review: a rollback, which records its reason, and the direct publish endpoints kept for emergencies (see With the API).
| Step | Who (console role) | Where |
|---|---|---|
| Draft a candidate | Owner, admin | "Policy" (edit the DSL) or "Policy workflow" (generate from observed behaviour) |
| Preview | Owner, admin in the editor; anyone for a saved candidate | "Policy", "Policy workflow" |
| Submit for review | Owner, admin | "Policy workflow" |
| Approve or reject | Reviewer | "Policy workflow" |
| Publish | Owner, admin | "Policy workflow" |
| Roll back | Owner, admin | "Policy workflow" → published versions |
A candidate goes through Draft, In review, Approved or Rejected, then Published, or Expired when its time runs out. An expired candidate can't be reviewed or published.
Draft a candidate
Generate from observed behaviour
On "Policy workflow", "Generate from observed behaviour" builds a least-privilege allow list from the project's events. You choose:
- The minimum number of times an action must have been seen (1–100).
- The observation window (1–90 days).
- The candidate's mode (Observe, Suggest or Enforce).
- How long the candidate stays valid (1–720 hours).
Only redacted events of actions that ran successfully count. The candidate allows what was seen often enough and nothing else. Actions that never happened in the window are not in it. If nothing reaches the threshold, you get "No successful action in the observation window reached the threshold".
Write it in the editor
On "Policy", edit the current policy as YAML. Here you can also write deny, approval and degrade rules. "Preview" checks it, and "Save as a candidate" stores it with an optional note and a validity of 1 to 720 hours (168 by default). Your unsaved edits stay in the browser tab, so a reload or an expired session doesn't lose them.
From an evaluation finding
A test system can send a finding to Guard as a guard.eval.finding.v1 bundle (POST /v1/eval/findings/import) and turn it into a candidate (POST /v1/eval/findings/{finding_id}/candidate-policy). Importing the same finding twice does nothing new. evidence_ref should point into your own evidence store. Don't put raw data in the bundle.
Preview
A preview replays recent events under the candidate and shows how each decision would change. It never runs a tool.
- Replay basis: all attempted actions, or completed actions only. Window: 1 to 90 days. Up to 500 sampled actions.
- What you see: the current version and the candidate's, the candidate's format, mode, default and rule count, whether every executor supports the format, the warnings, the rule changes, and the decisions before and after with examples of actions whose decision changes.
- Not enough information. The control plane only has redacted events: argument names, not values. A rule on argument values (
argument_equals,argument_in,argument_regex,argument_path_under) can't be judged from them. Those actions show as "Not enough information", with the fields that were missing, instead of a guess.
Replay on your side
To judge rules on argument values, replay the candidate where the values are. "Download the policy to replay on your side" saves candidate-policy.json. Then:
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.jsonactions.json is a list of 1 to 1,000 complete actions (with arguments), at most 2 MiB. The replay runs no tool and makes no network call, and the report holds decisions only, not the values.
Review
"Submit for review" sends the candidate to an independent reviewer, with an optional note. The reviewer approves or rejects it, with an optional comment.
- The author and the person who submitted it can't review it.
- The reviewer must be a different trusted subject from the author.
- An admin can't approve a policy review. That needs the reviewer role. A later control-plane release with personal workspaces permits its owner to review their candidates. Current hosted production still uses the organization separation rules above; the personal-workspace exception does not apply to it.
Current hosted organization projects therefore need at least two people.
Publish
An approved candidate is published by an owner or admin. "Prepare to publish" shows what will change: the mode (for example "Enforce → Observe"), the version, whether the executors support the format, the warnings and the rule changes. Then "Publish v6" (the button names the next version).
- What is published must match the hash that was reviewed.
- If someone published another version while the candidate was in review, the publish is refused. Draft again from the current version.
- A format v2 policy needs every active executor to support format v2.
Executors load the new version on their next heartbeat, so it takes effect within about 15 seconds. "Executors" shows which version each one has loaded: "Current policy loaded", "Not confirmed" or "Running an older version".
Roll back
Under published versions, pick an earlier version and give a reason (1 to 500 characters), then "Publish rollback version". Guard publishes that version's content as a new version, and the control audit log keeps the reason. History is never rewritten.
With the API
Self-hosted deployments without console sign-in can run the same flow with project tokens. Generate a candidate from observed behaviour with the admin token:
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"min_occurrences":3,"window_days":7,"mode":"suggest"}'Preview it with POST /v1/policy/candidates/{candidate_id}/preview, then ask for a review, approve it with the reviewer token, and publish it with the review ID and the current policy version:
candidate_id='cand_...'
review_id=$(curl -s -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/reviews" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"comment":"Checked the least-privilege scope against the observation window."}' | jq -r .review_id)
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/reviews/$review_id/approve" \
-H "Authorization: Bearer $GUARD_REVIEWER_TOKEN" -H 'Content-Type: application/json' \
-d '{"comment":"Approved: publish in Suggest mode."}'
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/publish" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d "{\"expected_version\":1,\"review_id\":\"$review_id\"}"Other endpoints:
| Endpoint | What it does |
|---|---|
GET /v1/policy/versions | Published versions |
GET /v1/policy/diff?from_version=1&to_version=2 | What changed between two versions |
POST /v1/policy/rollback | Publish an earlier version as a new one |
POST /v1/policy/dsl/preview | Preview a YAML document you checked with policy-validate |
POST /v1/policy/publish and POST /v1/policy/dsl/publish publish directly, without a candidate or review. Keep them for emergencies: they are in the control audit log, but no second person checked them.