Workflow
The audit alert is the scheduled GitHub Actions workflowauth-audit-alert.yaml. It shares no code, credential or runtime with the
observer and runs outside Cloudflare, so an identity that can redeploy or
silence the observer cannot silence it from inside the account.
-
Source. Every 5 minutes it reads the platform account’s Cloudflare
Audit Logs v2, and no other audit log API, with
TTR_AUTH_AUDIT_READ_TOKEN, a token for its own service user whose only permission is Account Settings Read on the platform account, which Audit Logs v2 requires. That permission also reads account settings and members; it writes nothing. Each query is filtered to the resource ids of the watched scripts and the operator Access application, excludesviewactions, and pages in ascending event time, so a run reads only watched changes and stays within 10 API calls. -
Cursor. The audit cursor store is a durable record outside the
platform Cloudflare account with versioned conditional writes, written
through
TTR_AUTH_AUDIT_CURSOR_TOKEN. Its value is{ at, idsAt, runId, runAttempt, mac }:atis an event time,idsAtthe ids of the events at exactlyatalready consumed, andmacan HMAC-SHA-256 over the canonical JSON of the other members withTTR_AUTH_AUDIT_CURSOR_MAC_KEY. That key is a secret of theauth-auditGitHub environment, which allows themainbranch only and which no other workflow names, so only this workflow holds it.- Validation. A value is accepted only when its
macverifies and itsrunIdandrunAttemptname a run ofauth-audit-alert.yamlonmainin the GitHub Actions run API. A missing value, a missing or bad MAC, or a value this workflow did not write alerts and is ignored, and that run reads only the 45-minute lookback. - Window. Each run reads from the earlier of
at, inclusive, and 45 minutes before its start, and skips events whose id is inidsAt. That lookback exceeds the 30-minute missing-run threshold and re-reads events the audit log delivers late. - Advance. The run moves
atonly to the greatest event time T for which it consumed every event at or before T, and stores the ids of the events at T inidsAt. A run that reaches its cap with a page unread alerts as a capped run, and the next run continues from thatat. - Compare-and-swap. The write is conditional on the version the run just read, never a blind overwrite. A failed condition leaves the stored value, alerts as a cursor conflict, and is not retried; the next run starts from whichever value is stored.
- Lag. A run alerts as lagging when
atis more than 20 minutes behind its start, whatever the cause.
- Validation. A value is accepted only when its
-
Watched scripts.
tuturuuu-auth,tuturuuu-gateway,tuturuuu-auth-keyguard,tuturuuu-auth-keyguard-operatorandtuturuuu-auth-observer, with their staging scripts. -
Watched changes. A script or version upload, a deployment or rollback,
a secret put or delete, a change to settings, bindings, variables, cron
triggers, routes, custom domains,
workers.devor preview URLs, a script deletion, and a change to the Access application or policy in front of the operator Worker. -
Expected actors. Each event is matched on
actor.type,actor.contextandactor.token_id.apps/auth-keyguard/deploy-identities.json, reviewed onmain, lists each watched script’s CI deploy token ids and workflow job, and the keyguard deployer App’s ids. An event is expected only when itsactor.typeisuseroraccount, its context isapi_token, and either:- its token id is that script’s CI token and its time falls between the
start and end of that script’s job in a run of its workflow on
main, read from the GitHub Actions run and jobs APIs with the workflow’s own read-onlyGITHUB_TOKEN. For a key-plane script that run attempt must also be a qualifying run:eventpush,head_branchmain,run_attempt1, the attempt that uploaded the version, the job’s deploy step completed, and a keyguard deployer App deployment for that script’s environment with asuccessstatus whoselog_urlnames that run and attempt and whose commit equalshead_sha. That deployment must also name the version id the event carries. The job only uploads and deploys versions, so a key-plane CI-token event with no version id, or one naming any other version, such as an earlier attested version deployed again during a later honest job, alerts; or - for a script other than
tuturuuu-authand the key-plane scripts, its token id has a ledger entry naming that script withrecordedAtbefore the event and the event before the entry’s expiry, which posts a notice.
successApp status naming the event’s version id 15 minutes after the event. Every other event is a positive alert: any other actor ontuturuuu-author a key-plane script; a CI token outside any run of its job; a key-plane CI token in aworkflow_dispatchrun, including one with refmain, a re-run, a run on another branch, or a run that never reached its deploy step; a token not in the ledger; a ledgered token outside its scripts, before itsrecordedAtor past its expiry; anactor.typeofdelegated_service,cloudflare_adminorsystem, even with contextapi_token, and an unknown or missing type; and any context other thanapi_token. The known contexts areapi,api_key(a Global API key),api_token,dash(a dashboard session),oauthandorigin_ca_key; an unknown or missing context alerts too. The workflow reads the ledger withTTR_CREDENTIAL_LEDGER_READ_TOKEN, a read-only credential. - its token id is that script’s CI token and its time falls between the
start and end of that script’s job in a run of its workflow on
-
Destination. Alerts and notices go to the security on-call channel
through
TTR_SECURITY_ONCALL_WEBHOOK, keyed by audit event id, so overlapping windows post each event once. A run that cannot read the audit log, the ledger, the identity file, or the GitHub runs, jobs or deployments, or cannot write the cursor, alerts as a failed run, and the channel alerts when no run has reported for 30 minutes. The workflow’sGITHUB_TOKENhas onlyactions: read,deployments: readandcontents: read. - Detection only. The alert changes nothing in Cloudflare and is no input to the observer, so an observer outage does not stop it and an alert outage does not change minting. The response is the containment under the key guard’s accepted residual.
-
Its own residual. A GitHub repository administrator, or anyone who can
change the workflow on
main, could stop it, change its secrets, or rewrite it to report nothing or to report falsely; the same access reaches theauth-auditenvironment and so the cursor MAC key. The missing-run alert covers only a stopped workflow. A rewritten workflow is a commit inmain’s history and GitHub’s audit log records secret and settings changes, but both are found after the fact. The observer’s provenance checks do not depend on this workflow, so a lying workflow alone does not hide a key-plane or auth version that lacks its deployment record. The same access could rewritekeyguard-cloudflare.yaml, which is the workflow-compromise residual under the key guard.
Tests
Against a fake Audit Logs v2, ledger, identity file, GitHub runs, jobs and deployments, and cursor store:- CI tokens. A watched change by the script’s own CI token inside a
run of its job on
main, and for a key-plane script inside a qualifying run, raises nothing, and the same token outside any run alerts. On a key-plane script the same token alerts in a re-run (run_attempt2), in aworkflow_dispatchofmain, in aworkflow_dispatchof another branch, in a run that never reached its deploy step, and in a run whose only deployment record was created bygithub-actions[bot]with a payload namingkeyguard-cloudflare.yaml. - Version match. Inside a qualifying run whose App deployment names
version V3, a deploy event by the script’s CI token carrying V3 raises
nothing. One carrying V1, an earlier version with its own App
successdeployment from an earlier qualifying run, alerts, as does a CI-token event carrying no version id. - Ledgered tokens. A change by a ledgered user token naming that
script, after its
recordedAtand before its expiry, posts a notice, except ontuturuuu-authand each key-plane script, where it alerts. A token absent from the ledger, a ledgered token outside its scripts, before itsrecordedAtor past its expiry, and an entry whose expiry is more than 24 hours after itsrecordedAteach alert. - Actor type and context. Contexts
api,api_key,dash,oauth,origin_ca_key, an unknown context and a missing context each alert. Anactor.typeofdelegated_service,cloudflare_adminorsystem, with contextapi_tokenand the CI token id inside a qualifying run, each alerts, as do an unknown and a missingactor.type. - Query. The query carries the watched resource filter and excludes
view, and the same event seen by two overlapping runs posts once. - Held events. An upload event inside a key-plane job that is still
running is not consumed and does not advance the cursor, raises nothing
once the job’s App deployment for that version reaches
success, and alerts when it has not 15 minutes after the event. - Cursor. A cursor with a bad MAC, one with no MAC, and one with a
valid MAC whose
runIdis not a run ofauth-audit-alert.yamleach alert, and that run reads only the 45-minute lookback. A write whose stored version changed since the read fails its compare-and-swap, keeps the stored value and alerts. Three events at one timestamp split by the cap are each consumed once across two runs, and the cursor never passes a timestamp with an unconsumed event. A capped run moves the cursor only to its last complete event time and the next run reads on from it inclusively. A cursor 21 minutes behind alerts as lagging, and an event delivered 40 minutes late is still read. - Failed runs. An unreadable audit log, ledger, identity file, run, job or deployment list, or cursor, and a failed cursor write, each alert as a failed run.