Policy¶
Policy decides what may execute. It is evaluated before every operation, before authentication, and it is never optional and never skippable.
Location: wherever you keep it — point $ENGRT_POLICY_FILE at it.
Ownership: yours. Runtime never creates it, and never overwrites it.
Policy has no environment-variable overrides. An env var must never be able
to widen governance — point ENGRT_POLICY_FILE at a different file instead.
A Runtime denial and a platform denial are different outcomes. A command Runtime
refuses is reported as not_dispatched; an allowed Kubernetes read that RBAC
denies, or a GCP REST read that receives HTTP 403, did reach the provider.
Credential readiness never satisfies a verified-identity allow-list.
Schema version¶
Policy written by this release is schema v3 (v3 adds
command_policy.admitted_helpers). An absent schema_version means legacy v1,
and unknown keys fail with the key and line. A supported older document is
migrated in memory without changing its bytes. The running binary publishes the
migration window in <Runtime Home>/specs/schema-contract.json and the strict
shape in <Runtime Home>/specs/policy-schema.json.
The command is a dry run by default. --write is the guarded rewrite, and it
refuses a path inside the Runtime Home. See
Upgrading.
Three layers, and only one of them is yours¶
| Layer | What it is | Can you change it? |
|---|---|---|
| Compiled safety profile | Invariants built into the binary: an operation no provider claims, a path that skips the audit write, a context-aware operation with no resolved target, credential export, tool reconfiguration, and (v0.13.0) destructive effects — repository deletion, ref deletion, history rewriting and removal of branch protection or rulesets on every transport | No. Not by any file, flag or Control Plane value — not even an explicit allow |
| Enterprise policy | A signed generation your Control Plane delivered | Only from the Control Plane. Runtime verifies it on every read |
| Your declarative policy | The document below | Yes — this page is about it |
The profile is a floor, not a stricter default. If it denies, the operation
is denied, and nothing above it can override that. engrt config validate
prints which version of it is in force:
Enterprise policy outranks your document rather than merging with it, and invalid enterprise state stops execution rather than falling back to yours — otherwise corrupting the bundle would be a way onto more permissive rules.
There is no off switch¶
Policy schema v2 and later have no top-level enabled key; a document that
contains one is invalid. A legacy v1 document with enabled absent or true
migrates safely in memory. A legacy enabled: false document is blocked with a
message: remove the key deliberately (or delete the document), then validate
again.
Three governance surfaces¶
| Surface | Governs | Block |
|---|---|---|
| Provider Governance | engrt <provider> <operation> |
providers: |
| Binary Governance | engrt command run <binary> |
allowed_binaries: + command_policy: |
| File Governance | engrt files <operation> <path> |
file_policy: |
When a provider chooses the CLI transport for an operation, both of the
first two apply — the provider rule first, then allowed_binaries and
command_policy on top.
File Governance¶
File access is default-deny: a policy document with no file_policy block
permits no read, list, write, append or delete at all. With no policy document
at all, the compiled default applies, and it grants "." (the working
directory) for both read and write — see the warning below.
file_policy:
read_roots:
- "." # the working directory, resolved per request
write_roots:
- "."
# Optional. These may only narrow the compiled budgets, never raise them.
max_read_bytes: 1048576
max_list_entries: 1000
max_depth: 32
max_edit_files: 1000
max_edit_batch_bytes: 33554432
max_edit_matches: 10000
max_edit_diff_bytes: 1048576
max_edit_seconds: 30
Read and write are separate authorities: read_roots permits read and
list, write_roots permits write, append and delete, and neither
implies the other. A path must resolve inside a granted root, so .. and an
absolute path elsewhere reach nothing.
A root that does not exist on a given machine is skipped rather than failing the document — one policy can name the trees several installs use.
Choosing roots¶
"." is resolved per request, not once
"." is resolved against the working directory of each command, so the
grant moves with wherever you happen to be standing: the same files read
succeeds in one directory and is refused in another. Convenient for a first
run; a source of confusing denials once capabilities run from CI, a
scheduler, or an agent.
Write absolute paths in a policy you intend to keep.
Grant read widely, write narrowly. A wrong read exposes a file; a wrong write destroys one.
file_policy:
read_roots:
- "/Users/you/projects"
write_roots:
- "/Users/you/projects/scratch"
- "/Users/you/projects/reports"
Do not grant write to a home directory or a tree of git checkouts. A root
covers everything beneath it, so /Users/you includes ~/.ssh, ~/.aws, and
the shell profile holding your tokens. Runtime refuses its own governance
documents and the native credential stores inside any grant, but it cannot know
which of your files matter. If a capability needs to write into a repository,
name that repository — not the tree containing it.
Budgets¶
The three read/list fields and the five max_edit_* fields bound what a single
operation may discover, read, transform and return. A document may only
narrow them — a larger value is ignored.
Read/list limits can return a stated truncation. Edit limits instead refuse the
batch before writing, because a partially selected set of files is not the
operation the caller requested. Exact defaults and output behavior are on the
files provider page.
Provider Governance¶
How rules match¶
- A provider with no entry is fully allowed. Operations are discovered from the provider that owns them, so a new operation in a later release does not require a policy edit.
deniedprefixes match against"<operation> <args...>". A rule can deny a whole operation (delete) or one narrow case (workflow run deploy-prod.yml,api DELETE).allowed, when non-empty, restricts the provider to those prefixes.enabled: falsedisables the provider entirely.- Denials win over allows.
- From v0.11.0, empty entries refuse the policy. An
empty or whitespace-only entry makes the policy refuse to load, and
engrt config validatenames the list. This applies to provider or commandallowed/deniedlists and toallowed_binaries/denied_binaries. In v0.10.0,allowed: [""]silently matched every operation. - Rules are evaluated on the operation, never the transport. A denial cannot be sidestepped by a provider moving an operation from REST to the CLI.
- Rules match the canonical form. If a provider normalizes an argument (for
example upper-casing an
apimethod), policy matches the normalized value, soapi deleteis caught by anapi DELETEdenial.
A rule must name an operation that exists¶
The compiled default policy denies api DELETE rather than repo delete,
because there is no repo delete operation — the destructive path is the
api escape hatch. From v0.13.0 repository deletion (and the other destructive
GitHub forms listed on the GitHub provider page) is also
refused by the compiled floor, so removing that line cannot re-open it; it still
governs other DELETE calls such as deleting an issue comment.
The report ends with policy warnings for any rule that can never match: a
providers.<name> rule naming an operation the provider doesn't expose, a
block for an unregistered provider, or a command_policy.rules.<binary> entry
for a binary absent from allowed_binaries. A denial that matches nothing gives
false confidence — check the warnings after every policy edit.
Locking a provider down to an allow-list¶
Anything not prefixed by one of those is refused. The older global
allowed_commands list no longer exists; see
Migration Guides.
Restricting a provider to named identities¶
Checked after authentication, because ordinary rules are evaluated before any
credential is touched. An unresolved identity, or a readiness-only proof such as
credential_ready, never satisfies the list.
Binary Governance¶
allowed_binaries:
- gh
- git
- terraform
- gcloud
- kubectl
- oc
- aws
- az
- vault
- helm
- flux
- gsutil
- bq
- docker
- podman
- kustomize
- argocd
- istioctl
- pulumi
- packer
- sops
Only these binaries may execute at all through engrt command run. A
binary absent from this list is refused, whatever the subcommand rules say.
An allow-list entry is necessary but not sufficient: the invocation must also have a supported context/semantic mode in the running release. See Command Engine Binaries for what v0.9.9 actually admits.
Subcommand rules¶
command_policy:
# Refused outright even if they were ever added to allowed_binaries
denied_binaries:
- rm
- sudo
- chmod
- curl
- wget
- ssh
rules:
git:
denied:
- push --force
- push -f
- reset --hard
- clean -fd
- filter-branch
- update-ref -d
terraform:
denied:
- destroy
kubectl:
denied:
- delete namespace
helm:
denied:
- uninstall
Matching semantics, which differ between the two lists:
| List | Matching |
|---|---|
denied |
A contiguous run of argument tokens anywhere in the command |
allowed |
Prefix match; when present, only matching prefixes may run |
Denials always win. denied_binaries is refused independently of
allowed_binaries — adding one to the allow-list does not un-deny it.
Because denied matches anywhere, a leading global flag cannot bypass a rule:
git -C /some/dir push --force is caught exactly like a bare
git push --force. Selectors Runtime resolves (--project=, -n <namespace>)
cannot be used to slip past a denial either.
Environment delivery¶
A variable reaches a tool only when the tool's built-in contract declares it and your policy permits it for that exact binary:
Omit environment and the tool's own contract decides. An empty list is
different from an absent one and means no variable at all. A name in this list
can only narrow the tool's contract, never add a variable the contract does not
declare. Loader variables such as LD_PRELOAD, NODE_OPTIONS and
GIT_SSH_COMMAND are refused for everyone, including enterprise policy.
admitted_helpers — letting a tool reach its credential helper¶
Some tools delegate authentication to a separate executable. docker finds its
registry credentials by launching docker-credential-gcloud; a local GKE
kubeconfig launches gke-gcloud-auth-plugin, which launches gcloud.
Runtime runs the pinned binary with a fixed minimal PATH — the caller's PATH
is deliberately not forwarded — so a helper in /opt/homebrew/bin is
unreachable and the command fails inside Runtime while it succeeds outside it.
admitted_helpers opens exactly that door and no wider:
- Absolute paths only. A non-absolute entry is rejected when the policy loads.
- Scoped to one parent binary. A helper admitted for
dockeris not reachable byterraform. - Only the named files are exposed. The helper's own directory is never
added to
PATH. - Empty by default. Widening this is always a deliberate act.
Requires schema_version: 3 (Runtime 0.9.1 or later). For the kubectl/GKE
helper chain, see
Kubeconfig resolution.
What the compiled default rules protect¶
The shipped defaults target one thing consistently: irreversible actions.
| Binary | Denied | Why |
|---|---|---|
git |
force-push, hard reset, clean, filter-branch, ref deletion | Rewrites or discards history |
terraform, pulumi |
destroy |
Tears down real infrastructure |
helm, istioctl |
uninstall |
Removes a release or the mesh control plane |
flux |
delete, uninstall |
Removes GitOps-managed resources or Flux itself |
kubectl / oc |
delete namespace / delete project |
Bulk resource destruction |
gcloud |
project and service-account deletion | Identity and account loss |
aws |
s3 rb --force, ec2 terminate-instances, iam delete-user, rds delete-db-instance |
Bulk data and identity deletion |
az |
vm delete, group delete, ad user delete, keyvault delete |
Same profile as aws |
vault |
kv delete, kv metadata delete, secrets disable |
Permanent secret removal |
gsutil |
rm -r, rb |
Recursive object and bucket deletion |
bq |
rm -f, rm -r -f, rm -f -r |
-f skips the confirmation prompt |
docker, podman |
system prune -a, volume rm, run --privileged |
Bulk pruning; privileged run is a container-escape risk |
argocd |
app delete, cluster rm, repo rm |
Detaches or deletes GitOps state |
kustomize, packer and sops carry no denial rules.
Two denials that are not in your document¶
The compiled floor refuses two families of command regardless of what any policy — local or enterprise — says about them.
Credential export (secret-export-operation): the operation's output is
a secret. gcloud auth print-access-token, kubectl get secret, vault kv
get, aws secretsmanager get-secret-value, sops -d, git credential fill.
A tool using a credential is untouched — that is the whole native-credential
model.
For Terraform, v0.9.9 refuses JSON, raw and named output, state pull,
state show, and show rendering (human or JSON, including show -json=false),
with or without a path. Flag reordering cannot bypass it, and unknown output
options fail closed. Unnamed non-JSON output, state list, plan, apply,
init, validate, fmt and providers still face the normal gates. This is
not universal secret detection. See
Terraform output safety.
Tool reconfiguration (tool-lifecycle-mutation): the operation changes the
tool rather than the system you are operating on. gcloud config set, gcloud
components install, kubectl config use-context, oc login, git config
--global, helm plugin install, docker login, gh extension install.
Reading the same configuration is fine (kubectl config view, gcloud config
get-value project, git config --get).
These are a floor rather than a rule because Runtime decides whether an operation is allowed by pinning the exact binary and reading where your tool is pointed; an operation that rewrites either changes what every later governed operation does. Do those in your own shell, deliberately.
See command run for the full
lists and the exact refusal text.
Git safety corrections in v0.10.0¶
v0.10.0 also refuses global/system Git configuration when flags
are reordered, when the git config set subcommand is used, or when Git accepts
an abbreviated scope flag such as --glob. Direct git credential-<helper> get
is refused because it can export a stored credential, including store, cache and keychain helpers. Ordinary Git remote operations
may still use the operator's native credential helper internally. Global options
such as --attr-source <value> and --shallow-file <path> retain these denials;
their values cannot hide the later configuration or credential-export operation.
These are corrections to the existing compiled invariants. The profile remains v3; upgrading the Runtime binary delivers the corrected coverage. A permissive policy or a capability step cannot override these denials. This is a finite catalog, not a sandbox for arbitrary Git aliases, helpers or future native syntax. The published archives passed native qualification on all six supported platforms.
Denials are audited¶
A denial is recorded exactly like a success or a failure: the audit log answers "was this attempted and refused", not just "what happened".
The runtime tells you when it is the one refusing:
Planning, validation and authorization¶
engrt config validate checks structure, compatibility and whether rules can
match. engrt resolve / capability planning shows the operation Runtime
understands, without authentication or execution. Neither is authorization from
the target platform: the final operation is still subject to the compiled floor,
active policy, authentication and GitHub/cloud/Kubernetes permissions.
Runtime policy is not a replacement for GitHub permissions, cloud IAM, Kubernetes RBAC or network controls. Use those native controls together with it.
Common tasks¶
allowed_binaries:
- gh
- git
- my-internal-cli
command_policy:
rules:
my-internal-cli:
denied:
- teardown
An unregistered binary still has no context mode and is refused as unsupported; see Adding a binary.
After any edit:
New policy defaults never reach an existing install
An env-selected community policy is yours, so a release adding
allowed_binaries entries changes nothing for a machine that already
selected a file. engrt config validate summarises the difference;
engrt config diff policy lists every binary. See
the upgrade trap.
Version authority¶
The schema and behavior shipped with the installed Runtime are authoritative.
The compiled profile version names the invariant contract; it changes when an
invariant is added, removed or changes meaning. Use the installed
<Runtime Home>/specs/ contracts and engrt config validate when a copied
example disagrees.
The v0.10.0 existing secret-export-operation floor also refuses
direct git credential-<helper> get, including store, cache and macOS keychain
helpers. Declarative permission cannot override that refusal. Native helper use
by ordinary Git remote operations retains its existing contract; this does not
claim a general sandbox for arbitrary helpers or aliases.
v0.12.0 installation scope¶
providers.github.installation_repositories accepts explicit owner/repo names.
It requires complete verified installation scope within that exact, case-insensitive
set. providers.github.identities remains a verified-user policy; an installation
or readiness-only credential cannot satisfy it. Scope policy never creates a
principal or grants provider permissions.
See Governed authority for the contract and qualification limits.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.