Policy, audit and web UI¶
12. Policy (overview)¶
Roles, bindings, protected records and limits are declared in YAML, versioned in git (a permission change is a pull request). A second, managed layer can be edited from the UI within bounds set in the file (section 15). The full reference is in CONFIG.md.
roles:
app-cname-writer:
rules:
- zones: ["example.com"]
actions: [dns.read, dns.record.write]
records: { hosts: ["*.staging", "_*.staging"], types: [CNAME, TXT] }
acme-solver:
rebase_on_save: true
ephemeral_ttl: 24h
rules:
- zones: ["*"]
actions: [dns.read, dns.record.write]
records: { hosts: ["_acme-challenge", "_acme-challenge.**"], types: [TXT] }
protected:
- { zones: ["*"], hosts: ["@"], types: [NS, MX, SOA, CAA] }
bindings:
- role: app-cname-writer
team: app-team
subjects:
- issuer: aws
claims: { sub: ["arn:aws:iam::111111111111:role/ci-app"] }
Host patterns are relative to the zone: * matches exactly one label, ** one or
more labels (glob.MatchHost).
A rule applies to the zones matching its zones globs, and to the zones whose
provider folder matches its folders globs (EuroDNS folders, section 15.9).
13. Audit¶
One event per request (audit.Event): time, request id, subject (issuer:id),
teams, action, zone, provider id, decision (allow/deny/error), reason, RRset
changes (old and new TTL, values or alias), id (a string) of the latest provider
snapshot taken before the write (EuroDNS; events recorded with a numeric id still
decode).
Events go to two places:
- stdout as JSON lines, for collection in an external, append-only sink;
- the store (DynamoDB with a TTL attribute for retention), so the web UI can query
them by zone, RRset, subject and time. Reconcile also records events
(
taint,expire, pending resolution), so drift shows up in the same history.
14. Web UI¶
A web interface for operators and teams. It answers "what is in this zone, who owns it, who changed it and when", lets people with write rights stage RRset changes and apply them through a reviewed plan, and lets designated people edit the managed policy layer (section 15).
14.1 Views¶
- Zones: managed zones with their provider folder (EuroDNS, with a folder filter) and counters (RRsets, managed, tainted, pending, foreign), last upstream sync, last gate write (latest successful write found in the journal, so it survives restarts and is the same on every replica); with zone discovery (15.7), the zones of the provider accounts that are not managed, flagged unmanaged, with a "Manage this zone" action for policy proposers.
- Inventory of a zone: every RRset with its status, owner team, protected flag,
created by / updated by (actor and category:
human,pipelineorkey), timestamps, adoption flag, expiry for ephemeral RRsets, last request id.
| Status | UI label | Meaning |
|---|---|---|
managed |
Managed | owned by the gate, upstream content matches |
pending |
Pending | write in flight or interrupted, resolved by reconcile |
tainted |
Drifted | owned, changed outside the gate; writes blocked |
missing |
Missing | owned, deleted outside the gate |
foreign |
Not managed | exists upstream, not owned; read-only for the gate |
The UI groups tainted, missing and pending as Needs attention, and calls
zones found by discovery but not managed Not managed (read-only).
- Audit log: filterable by zone, host, type, subject, actor category, decision, time range; each entry shows the RRset diff (old → new TTL and values), the reason of a denial and the snapshot id taken before the write.
- DNS writes: in a zone, the record sets the user may change (computed from
/api/v1/me) offer edit and delete, and a form adds new ones. Changes are staged in the browser, then sent as onePOST /api/v1/zones/{zone}/planwhose result (diff, refusal reasons) is shown for review; Apply sendsPOST /api/v1/zones/{zone}/applywith theplan_id. Each staged change carries the hash of the RRset as displayed (expected_hash, ormust_not_existfor a new one), so a record changed since is refused instead of overwritten. - Connect: ready-to-paste setups for Claude Code, Claude Desktop, Terraform
(
dnsgateprovider) and the API, and Get an API token (section 9.4).
14.2 API¶
The UI is a static single-page application served by the gate, backed by the JSON
API under /api/v1 (contract in internal/uiapi, reference in
api/dns-gate.openapi.yaml, guide in
API.md):
| Route | Returns |
|---|---|
GET /api/v1/me |
logged-in subject, category, roles, teams, permissions |
GET /api/v1/zones |
zone summaries |
GET /api/v1/zones/{zone}/rrsets |
zone inventory |
GET /api/v1/audit?zone=&host=&type=&subject=&category=&decision=&since=&until=&limit=&cursor= |
audit page, newest first, cursor pagination |
POST /api/v1/zones/{zone}/plan, /apply |
RRset plan, then its application |
POST /api/v1/tokens |
gate-issued token of the session (9.4) |
/api/v1/api-keys |
API key management (9.5) |
POST /api/v1/token-exchange |
gate token for an OIDC token (9.6) |
The same API accepts bearer tokens, for scripts and the Terraform provider, with
GET/PUT/DELETE /api/v1/zones/{zone}/rrsets/{host}/{type} for single RRsets.
Read routes require ui.read (or dns.read) on the zone; writes go through the
engine like any other write (RBAC, ownership, lock, audit).
14.3 Data path¶
The inventory is a cache in the store, filled by reconcile (one GET per zone per
interval) and refreshed by every gate write. When a zone's cache is empty (first
start), the inventory performs one provider read for that zone to fill it; after
that, UI requests never call the provider. Single-RRset reads (Engine.RRset, the
RRset API read by a Terraform plan) use the same cache and one ownership lookup:
writes do not rely on it, they check ExpectedHash under the lock against a fresh
read. This keeps the UI out of the upstream rate
budget: browsing cannot get the gate banned. last_synced_at tells how fresh the
view is.
14.4 Login and session¶
- OIDC authorization code flow with PKCE against a configured issuer (e.g. Entra ID, any OIDC provider), or SAML 2.0 (9.4); the same bindings map the user to roles and teams.
- Session in an encrypted,
HttpOnly,Secure,SameSite=Strictcookie, short lifetime, no token stored in the browser's JavaScript-accessible storage. - Strict Content Security Policy (no inline script,
default-src 'self',frame-ancestors 'none'). - The mutations reachable from the browser are DNS writes through plan/apply, gate
tokens, API keys and policy revisions (section 15). Every one requires the CSRF
token and a same-origin
Origin; DNS applies, single-RRset writes, API key creations, changes and rotations, and policy changes also require step-up authentication (a login more recent thanpolicy.edit_max_age, and thepolicy.require_amrmethods), otherwise403 reauth_requiredand the UI sends the user through/auth/login?reauth=1. The plan itself is a dry run and needs no step-up.
15. Editable policy¶
The policy can be edited from the UI by designated people, without giving up GitOps for what matters most.
15.1 Two layers¶
| Layer | Where | Content | Who changes it |
|---|---|---|---|
| base | YAML config file (git, deployed by CD) | issuers, UI and store settings, managed zones, protected records, bounds, every policy.* grant, plus base groups, roles, bindings and keys |
pull request on the config repository |
| managed | store, as immutable revisions | zones, groups, roles, bindings, virtual keys (PolicyDocument) |
proposed and approved in the UI |
At evaluation the active managed revision is merged with base. Constraints on the managed layer, checked at proposal and again at activation:
- it cannot reuse a base group or role name;
- it cannot grant any
policy.*action:policy.read,policy.proposeandpolicy.approveare granted only by base bindings, so the editor can never extend who controls the editor; - every managed rule must stay within the bounds declared in base
(
bounds.zonesglobs,bounds.actionslist); - protected records (base) win over any managed grant;
- zones it brings under management must match
bounds.zonesand exist in a provider account (15.7).
Validation errors come back as 400 {"reason":"invalid_policy","errors":[{"path","message"}]}.
15.2 Lifecycle of a revision¶
propose (policy.propose)
(none) ───────────────────────────► proposed ──reject──► rejected
│
approve (another policy.approve holder)
▼
approved
│ activate
▼
previous active ◄─superseded─ active
- Approval by someone else: with
policy.require_approval: true(default), a revision must be approved by apolicy.approveholder other than its author. Without required approval, the proposer may activate directly. - Stale revisions: each proposal records its
parent_id(the active revision it was based on). If another revision was activated since, the proposal is markedstaleand cannot be activated; it must be re-proposed on the current active one. - Atomic activation: activation is one conditional write in the store (expected active revision → new revision). All replicas pick up the new revision; a request is evaluated against exactly one revision.
- Rollback:
rollbackon an old revision creates a new proposal copying it, which goes through the same approval. History is never rewritten. - Export: any revision's managed document can be exported as YAML, to keep a copy in git or to move it into the base layer.
- Every proposal, decision, activation and rollback is an audit event.
15.3 Review aids¶
- Diff: unified YAML diff of the proposed document against its parent.
- Impact analysis: permissions gained or lost per group, team, matcher or virtual key (e.g. "team web loses write on owned RRsets (12)"), with warnings (empty groups, rules shadowed by protected records, keys without expiry).
- Explain: simulate a decision for a concrete subject (issuer + claim values), action, zone, host and type, against the active policy or a proposed revision; returns the groups, bindings, matching rule, denying rule and layer.
- Who can: list the roles, teams, groups, subjects and virtual keys allowed to perform an action on an RRset.
15.4 Groups and matchers¶
A group is a named set of subject matchers. A matcher is an issuer plus claims that must all match (glob; an array claim matches when one element matches). Groups make bindings readable: an Entra app role, a GitHub repository, a list of users. Bindings grant a role, acting for a team, to groups and/or individual matchers.
groups:
dns-operators:
members:
- issuer: entra
claims: { roles: ["Gate.Operator"] }
web-ci:
members:
- issuer: aws
claims: { sub: ["arn:aws:iam::111111111111:role/ci-web-*"] }
bindings:
- role: web-writer
team: web
groups: [web-ci]
15.5 Humans with Entra ID SSO¶
For the UI, define app roles on the gate's app registration and assign them to
Entra groups (assignment to groups needs Entra ID P1 or higher), then match them
in base groups through the roles claim:
| App role | Typical base grant |
|---|---|
Gate.Reader |
ui.read, policy.read |
Gate.Operator |
ui.read, policy.read, policy.propose |
Gate.PolicyAdmin |
ui.read, policy.read, policy.propose, policy.approve |
Alternative: groupMembershipClaims: ApplicationGroup in the app manifest, which
emits in groups only the groups assigned to the application (avoids overage), and
match on group object ids. App roles are preferred: names are readable and stable
across tenants.
15.6 Protection of policy mutations¶
- Session login with OIDC code + PKCE (14.4).
- Step-up: mutations by humans require a recent authentication
(
policy.edit_max_age, checked onauth_time) and, if configured, an MFA method inamr(policy.require_amr). Otherwise403 {"reason":"reauth_required"}and the UI sends the user through/auth/login?reauth=1. - CSRF: every POST requires the
X-Gate-CSRFheader equal to thegate_csrfcookie and a same-originOriginheader. - Virtual keys are generated server-side and shown once; only their hash goes into a proposal.
15.7 Managed zones and zone discovery¶
The managed zones are the union of the base zones and the zones of the active
managed revision. Every component reads them from the current policy snapshot: the
route table of the EuroDNS-compatible API, the write engine, reconcile (at each
round), the UI and MCP. Activating a revision that adds a zone is therefore enough
to manage it, on every replica within the reload interval.
internal/discovery lists the zones of every provider account (ListZones: EuroDNS
searchDomains through the shared rate-limited transport, Route 53
ListHostedZones, both paginated) at start and
every providers[].zones.refresh, filtered by the include/exclude globs of the
provider, and keeps the lists in memory. Discovered zones that are not managed are unmanaged:
| Managed | Unmanaged | |
|---|---|---|
| RBAC actions that can match | all | dns.read, ui.read only |
| EuroDNS-compatible API, plans, writes, adoption, Terraform export | yes | refused |
| Reconcile | every reconcile_interval |
never |
| Inventory | cache filled by reconcile and writes | read on demand, reused for reconcile_interval; never read by the zone list |
A revision may add a zone only if it is discovered (one extra listing, at most once a minute, when a proposal names a zone not seen yet). Removing a zone from the managed layer is allowed; the impact analysis warns when the gate owns RRsets there. Their ownership entries stay in the store, so managing the zone again restores them.
15.8 Policy delegations¶
Some policy changes are mechanical: the Terraform stack that creates CI pipelines
creates, for each one, a cloud role scoped to that pipeline, and should create in the
same apply the gate role and binding that let the pipeline's identity write only its
own DNS names. Routing each of them through a human approval defeats the automation,
and granting the stack policy.propose with require_approval: false would let it
change anything within the bounds.
A delegation (policy.delegations, base file) is a narrower grant: its subjects
may create, change and delete roles and bindings they own, within allow limits
(zones, actions, record scope, the subjects a binding may target, the teams it may
use, a maximum number of objects), through a dedicated API
(/api/v1/policy/delegated, CRUD by stable name, ETag preconditions). The review
happens once, when the delegation is merged in the configuration; each delegated
change is then activated without approval.
- Storage: delegated objects live in the
delegatedsection of the managed document, each with its owner (delegation,managed_by, created/updated by and at). A delegated change is an ordinary revision (author = the pipeline), created on the active one and activated at once, so history, diff, export, rollback, explain and who-can see it like any other. - Validation: the managed-layer rules (15.1) plus the owner delegation's limits, checked at every write and on every later revision; delegated rules are re-checked against their delegation at evaluation (defense in depth).
- Isolation from human edits: proposals keep the delegated section of the
active revision (the UI never sends it) and cannot change it; a policy
administrator takes objects over explicitly (
take_over), which goes through the normal review. Rollbacks keep the delegated objects. Managed bindings cannot use delegated roles, so a delegated delete never breaks a human object. - Concurrency: delegated writes are serialized per replica; the activation is the
conditional write of 15.2, and a lost race re-applies the change (and its
preconditions) on the new active revision, a bounded number of times, before
409 policy_busy. ETags are per object, so parallel Terraform resources do not invalidate each other. - Teams: with
allow.teams.from_subject, a delegated binding's team is the one derived from its own subject, so a pipeline created by the stack owns its records and cannot touch those of another pipeline, even though the stack wrote both bindings.
15.9 EuroDNS folders¶
Teams often map to EuroDNS folders (one per country or business unit), so rights can
follow a folder instead of a zone list to maintain. Discovery keeps the folder of
each EuroDNS zone (4.1); Snapshot.Folder reads it from the live discovery lists, so
the authorizer uses the folder known at decision time, without recompiling the
policy.
- Selection: a role rule applies to a zone listed in
zonesor whose folder matchesfolders(glob.MatchFolder: segments as host patterns,/ESexact,/ES/**below,/the root, case-sensitive). The decision records the folder when the rule applied through it (Decision.Folder), shown byexplain(folder) andwho-can(by_folder), and in the audit of the writes, adoptions and transfer requests and decisions it granted (policy.FolderGrants.AllowRRsetFolder: the folder of the authorization itself, recorded for the request,extra.folder). Zones without a known folder never match a folder selector, so folder rules fail closed: Route53 zones, zones not listed yet, afolderFullPathabsent from the listing (anullone is the root), a zone listed by two providers, and the zones of a provider whose last successful listing is older thanzones.folder_expiryrefresh periods (at least 2, counted from the end of that listing). - Management: a folder selector never makes a zone managed. Managed zones stay
the base and managed
zones; a discovered zone in a selected folder is only readable, as any unmanaged zone.zones.foldersof a provider narrows what the provider serves and what discovery shows. - Bounds:
policy.bounds.foldersand delegationallow.foldersbound thefoldersof managed and delegated rules by static coverage (glob.FolderCovered), as zone globs; a zone glob of a managed rule is never covered by a folder bound, nor the reverse. At decision time, a managed rule that applies through a folder also needs the zone to matchpolicy.bounds.zones, and a delegated one theallow.zonesof its delegation (Snapshot.ruleApplies): folders narrow the bounds, never widen them, so moving a base zone kept out of the bounds into a selected folder grants the managed layer nothing.Permissions(/me) carries those zones asfolder_zones. API keys and their recorded grants compare folders statically; a rule on every zone (*) covers any folder, and a managed or delegated rule of the issuer covers a folder pattern only when its bounds (and allow.zones) cover every zone (Snapshot.roleRuleCovers). - Changes: each listing calls
discovery.Config.OnFolderChange, with a context detached from the listing and one request id per listing: once with a summary for the first listing of a provider by the process (count andFolderDigest), then for each zone a later listing finds, finds in another folder, or no longer lists; the app recordsgate.zone.folders_listed,gate.zone.folder_seen,gate.zone.folder_changedandgate.zone.folder_gone. The previous folders are only in memory: instances do not compare their views, a new one records the folders it starts from. Folder-based rights are therefore delegated to whoever can move domains in the EuroDNS account (THREAT-MODEL.md). - Review: the impact analysis lists every new or changed folder rule as a
dynamic rule with the zones it reaches currently, and warns while discovery has
not listed the accounts. Loading the configuration warns about folder selectors
without a EuroDNS provider or outside every provider's
zones.folders.