Policy tools

Overview

A StackGuardian policy is a named set of rules that are checked against workflow runs within the policy's scope. These tools create and change policies. To find existing ones, see search_policies. For policy concepts, see Create Policy and Policy types.

Both tools are write tools, see Availability.

Rules

A policy has 1 to 25 rules. Each rule has a name, a source, and a verdict for each outcome.

Sources. Each rule gets its policy code from one of these:

Source	Description
Inline Tirith document	A StackGuardian policy framework (Tirith) JSON document, written directly into the rule.
Git repository	OPA/Rego policies, or a tirith.json file, in a repository. Private repositories need a VCS connector or a vault secret for authentication. Other git hosts accept a vault secret only.
Policy template	A marketplace policy template at a pinned revision, with its input values.

Verdicts. Each rule says what happens when its evaluation fails, and what happens when it passes:

Verdict	Effect on the run
FAIL	Block the run.
WARN	Record a warning and continue.
APPROVAL_REQUIRED	Pause the run until the policy's approvers approve it.
PASS	Continue.

The usual rule blocks, warns or asks for approval on failure, and passes on success. A rule can also be switched off without removing it.

An APPROVAL_REQUIRED verdict only pauses workflows that have a step after the plan. The tools warn you when a rule won't be able to pause.

Scope

The scope decides which runs the policy is checked against. It can include any mix of:

• the whole organization (*)
• a workflow group, which includes everything inside it
• a single workflow, a stack, or a workflow inside a stack
• a cloud connector, meaning every workflow that deploys through it
• a connector group

create_policy

Creates a new policy.

Input	Description
Name (required)	1–100 characters: letters, digits, _ and -. It becomes the policy's permanent id and can't be changed later. You can still change the display name.
Rules (required)	1–25 rules, see Rules.
Scope (required)	Where the policy applies, see Scope. It must be set explicitly. If you choose the whole organization, the response tells you so.
Approvers	User emails asked to approve when a rule returns APPROVAL_REQUIRED. Required if any rule uses that verdict.
Approvals required	How many of the approvers must approve. Required whenever approvers are set. 0 means all of them.
Description, tags, context tags	Description up to 512 characters, up to 10 tags.

Checks before the policy is created

The platform accepts some mistakes that only show up later as a policy that never runs, or that blocks nothing. The tool catches these first:

• Tirith documents are validated, including providers, conditions and the evaluation expression.
• OPA rules must name a boolean deciding rule, for example main.allow.
• Private git repositories must reference a real connector or secret.
• Policy templates must exist, at a pinned revision.
• Every scope entry must exist. Workflow group names are translated to their ids, and the response reports the translation.

Your assistant should confirm the scope and the verdicts with you before creating the policy.

Example prompts

"Create a policy that blocks any run creating an S3 bucket without encryption, applied to the production workflow group."

"Add our cost-guardrail policy template as a policy that requires approval from finops@acme.com for the data-platform stack."

update_policy

Changes an existing policy. The tool reads the stored policy first and sends only the settings you name. You can combine several changes in one request.

Change	How it works
Settings	Display name, description, tags, context tags, approvers and approvals required. Each one you send replaces the stored value, including tags and context tags, so send the complete set.
Scope	Add entries, remove entries, or replace the whole scope. Replacing it with an empty list detaches the policy from everything.
Rules	Add new rules, replace existing rules by name, or remove rules by name. At least one rule must remain. Rules you don't mention are kept exactly as they are. A replaced rule is swapped in whole: send its full source and verdicts, and set it to switched off again if it was, since an omitted setting falls back to its default.

Good to know

• You can refer to the policy by its id or its display name.
• Renaming a policy changes its display name only. Its id stays the same.
• Changes apply to runs created afterwards. Runs already in progress aren't affected.
• The same checks as create_policy apply to new and replaced rules and to added scope entries.

Example prompts

"Also apply the s3-encryption policy to the staging workflow group."

"Change the no-public-ips rule in network-guardrails to warn instead of fail."

"Remove the legacy-tagging rule from our tagging-standards policy."