Policy schema
A policy is a YAML or JSON object. Unknown fields are refused at every level. preworld-guard policy-schema prints the JSON Schema, and preworld-guard policy-validate <file> compiles a file and prints its hash. How rules are evaluated is in Policies.
The document
| Field | Type | Default | Notes |
|---|---|---|---|
schema_version | guard.policy.v1 or guard.policy.v2 | guard.policy.v1 | v2 is needed for require_approval and degrade |
policy_id | string, 1–120 characters | runtime-default | |
version | integer ≥ 1 | 1 | The control plane assigns versions when it publishes |
name | string | 最小权限 · 运行时防护 | The SDK's default name, in Chinese ("least privilege · runtime protection") |
mode | observe, suggest or enforce | observe | See Modes |
default_effect | allow or deny | allow | What happens when no rule matches |
source | string | manual | Where the policy came from |
finding_ids | list of strings | [] | Evaluation findings the policy answers |
expires_at | ISO 8601 time, or null | null | After this time every action is denied. A value that can't be read counts as expired |
rules | list of rules | [] | Rule IDs must be unique |
A rule
| Field | Type | Default | Notes |
|---|---|---|---|
rule_id | string, 1–120 characters | Unique within the policy | |
effect | allow, deny, require_approval or degrade | The last two need format v2 | |
fallback_resource | string | Required for degrade, refused for any other effect | |
risk | high or normal | high | In Suggest mode only high-risk deny rules deny |
match | object | matches everything | See match |
message | string | 动作符合当前运行时策略。 | Shown with the decision. The default is in Chinese ("the action fits the current runtime policy") |
match
| Field | Type | Matches when |
|---|---|---|
action_type | string | Equal, or * (default) |
resource | glob | Glob match, or * (default) |
agent_id | string | Equal |
destination | glob | The action's destination matches; no destination never matches |
argument_keys | list of strings | All these argument names are present |
argument_equals | map: name → value | Each argument equals its value; session.subject_id stands for the trusted subject |
argument_in | map: name → list of strings | Each argument is one of the values |
argument_regex | map: name → regular expression | Each argument is a string (≤ 4,096 characters) the expression matches in full |
argument_path_under | map: name → folder | Each argument is a path that resolves to somewhere under the folder |
data_labels | list of strings | The action carries all these labels |
The more of these a rule sets, the more specific it is. Specificity decides between non-deny rules in format v2.
Limits
| Limit | Value |
|---|---|
| One regular expression | 1,024 characters |
| All regular expressions in a policy | 4,096 characters |
| Policy source in the console editor | 64 KiB, 16 levels, 5,000 nodes |
| A request that carries a whole policy | 256 KiB |
The console editor also refuses YAML anchors, aliases, tags, merge keys, duplicate keys and multiple documents.
Examples
- Format v1 with Suggest mode: Policies.
- Format v2 with approval and degrade rules: Approvals and degrade.