Skip to content

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.

engrt config migrate --surface policy --file ~/.config/engineering-runtime/policy.yaml

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:

Safety:   compiled-safety-profile/v4 (e6784e4c72bc) — invariants no document can disable

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

providers:
  github:
    enabled: true
    denied:
      - api DELETE
  files:
    enabled: true
    denied:
      - delete

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.
  • denied prefixes 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: false disables 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 validate names the list. This applies to provider or command allowed/denied lists and to allowed_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 api method), policy matches the normalized value, so api delete is caught by an api DELETE denial.

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.

engrt config validate

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

providers:
  github:
    enabled: true
    allowed:
      - repo list
      - repo view
      - user get

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

providers:
  github:
    enabled: true
    identities:
      - release-bot

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:

command_policy:
  rules:
    vault:
      environment:
        - VAULT_ADDR
        - VAULT_TOKEN

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:

command_policy:
  admitted_helpers:
    docker:
      - /opt/homebrew/bin/docker-credential-gcloud
  • Absolute paths only. A non-absolute entry is rejected when the policy loads.
  • Scoped to one parent binary. A helper admitted for docker is not reachable by terraform.
  • 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".

engrt command run git push --force
engrt audit tail -n 1 --output json

The runtime tells you when it is the one refusing:

policy denied github <operation>: ...

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

providers:
  files:
    enabled: true
    denied: []          # remove the `delete` rule
providers:
  github:
    enabled: true
    denied:
      - api DELETE
      - workflow run deploy-prod.yml
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.

providers:
  github:
    enabled: false
file_policy:
  read_roots:
    - /srv/checkouts
  write_roots:
    - /srv/checkouts/scratch   # read the tree, write only one part of it

After any edit:

engrt config validate     # confirms the rule can actually match something

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.