Skip to content

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 ​

FieldTypeDefaultNotes
schema_versionguard.policy.v1 or guard.policy.v2guard.policy.v1v2 is needed for require_approval and degrade
policy_idstring, 1–120 charactersruntime-default
versioninteger ≥ 11The control plane assigns versions when it publishes
namestring最小权限 · 运行时防护The SDK's default name, in Chinese ("least privilege · runtime protection")
modeobserve, suggest or enforceobserveSee Modes
default_effectallow or denyallowWhat happens when no rule matches
sourcestringmanualWhere the policy came from
finding_idslist of strings[]Evaluation findings the policy answers
expires_atISO 8601 time, or nullnullAfter this time every action is denied. A value that can't be read counts as expired
ruleslist of rules[]Rule IDs must be unique

A rule ​

FieldTypeDefaultNotes
rule_idstring, 1–120 charactersUnique within the policy
effectallow, deny, require_approval or degradeThe last two need format v2
fallback_resourcestringRequired for degrade, refused for any other effect
riskhigh or normalhighIn Suggest mode only high-risk deny rules deny
matchobjectmatches everythingSee match
messagestring动作符合当前运行时策略。Shown with the decision. The default is in Chinese ("the action fits the current runtime policy")

match ​

FieldTypeMatches when
action_typestringEqual, or * (default)
resourceglobGlob match, or * (default)
agent_idstringEqual
destinationglobThe action's destination matches; no destination never matches
argument_keyslist of stringsAll these argument names are present
argument_equalsmap: name → valueEach argument equals its value; session.subject_id stands for the trusted subject
argument_inmap: name → list of stringsEach argument is one of the values
argument_regexmap: name → regular expressionEach argument is a string (≤ 4,096 characters) the expression matches in full
argument_path_undermap: name → folderEach argument is a path that resolves to somewhere under the folder
data_labelslist of stringsThe 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 ​

LimitValue
One regular expression1,024 characters
All regular expressions in a policy4,096 characters
Policy source in the console editor64 KiB, 16 levels, 5,000 nodes
A request that carries a whole policy256 KiB

The console editor also refuses YAML anchors, aliases, tags, merge keys, duplicate keys and multiple documents.

Examples ​