Repository navigation
Guardana Control 0.6.0-alpha
Pre-releaseA plane now takes its policy as current only on a signed freshness
statement, which policy renew writes, and keeps on disk the serial floor
that refuses an older bundle, so a restart cannot roll the policy back;
/healthz, /metrics and doctor say how fresh the policy is. An upgrade
needs five more configuration keys, a freshness key apart from the bundle's,
a floor directory that policy state init makes, and a statement renewed
within the budget: the first entry under Changed says how. A zero
upstream.call_timeout is now refused. examples/evidence-report, a Go
module of its own, follows the evidence export, reports what was decided and
why, and raises local alerts. An audit before the release fixed defects,
among them: a clock reading before 1970 let an expired delegation pass, and a
clock set back after a decision let an expired run or approval through; the
release gate counted a pull request run and could be passed by a tag named
main; the hold journal and the trail file accepted a directory or a file
another account owned; and a stateful listener kept any number of sessions
open. docs/status.md says what is implemented and what is
experimental. Nothing here is a security boundary yet.
Added
examples/evidence-report -state <dir>follows a trail one export after
another and raises local alerts: a JSON line each, appended to
<dir>/alerts.jsonland repeated on standard error, for a gap, a
conflicting event, a lifecycle it cannot finish, an undetermined verdict, a
block of the plane's own, an expired approval and its own bound. A repeated
delivery, a crash and an outage neither lose nor repeat an alert, and it
prints no field outside an allowlist
(guide).guardana-control policy renewverifies a bundle under its public key,
raises a signer's serial floor and writes a signed freshness statement for
the bundle; it refuses a bundle below that floor
(ADR-0038).guardana-control policy state initmakes a floor directory and a bundle
id's floor, never replacing one, andpolicy state resetlowers a floor,
recording the reason and the value it replaced./healthzcarries apolicyobject:freshness, one ofconfirmed,
unconfirmedandexpired, the confirmation and its expiry, the seconds
left and what the plane's polls of its policy found. A plane whose policy is
not confirmed answers"status":"degraded"with200; a halted plane still
answershaltedwith503./metricscarriesguardana_control_policy_freshness,
guardana_control_policy_confirmation_seconds_left,
guardana_control_policy_seconds_since_poll, and counters of the
policy's refusals by cause, bundles awaiting a statement, statements
awaiting a bundle and withdrawals by a clock set back
(metrics).guardana-gateway doctor'spolicyline judges the floor, the bundle and
the statement as a start would, without raising the floor, and fails for a
statement missing, expired, dated ahead or naming another bundle, and for a
bundle below its floor or at its serial with another digest.listener.session_idlesets how long astateful_httpsession may sit idle
before it ends, from one minute to a day; the default stays 30 minutes. A
client that only listens on its GET stream is idle. Another listener kind
refuses the key.listener.max_sessionscaps astateful_httplistener's live sessions,
from 1 to 16384, 1024 by default; an open past it is answered503, and a
request whose body is still arriving holds no place. Another listener kind
refuses the key./metricscarries
guardana_control_adapter_sessions_liveand
guardana_control_adapter_sessions_refused_total.guardana-control policy explainprints aclockline:usable, or why
the clock stopped the decision.
Changed
-
Breaking: a plane's configuration needs five more keys:
policy.statement_file,policy.state_dir,policy.freshness_key_id,
policy.freshness_public_keyandpolicy.poll_interval. A configuration
without them is refused at start, naming the first key it lacks. The
freshness key may not be the bundle's key;state_dirmust be a directory
policy state init --kind planemade;poll_intervalis at least1sand
shorter thanpolicy.max_stale. No setting keeps the old behaviour. To
migrate, run the first three commands where the keys live and the last on
the plane's host, then set the five keys and keep renewing the statement
within the budget (run the gateway,
ADR-0038):guardana-control policy keygen --out freshness guardana-control policy state init --kind signer --bundle-id <id> signer-floors guardana-control policy renew --key freshness/signing.key --bundle <bundle> \ --bundle-public-key <bundle key dir>/signing.pub --floor signer-floors --out <statement> guardana-control policy state init --kind plane --bundle-id <id> <state_dir> -
A plane's policy is confirmed only by a freshness statement bound to its
bundle, never by installing the bundle again. The plane reads the bundle and
the statement everypolicy.poll_interval, installs a newer bundle only with
its statement, and refuses every bad replacement without moving the
confirmation. Without a statement in its budget it decides every call
POLICY_STALE, from the start or once the budget runs out, until a renewal
arrives; a restart no longer resets the budget. A wall clock set back more
than a second withdraws the confirmation until it is back and a statement
issued after the withdrawal arrives. -
A plane's serial floor is kept on disk: a start onto a bundle below it, at
its serial with another digest, or above it without a statement is refused,
naming both serials. -
/healthzleaves outbundle.confirmed_atwhile no statement confirms the
bundle. -
devmakes the plane's floor directory, writes the bundle's freshness
statement under a second key held only in memory and renews it every third
of the budget, sooner when the poll interval asks for it, so a session or a
scenario past the budget stays fresh. It printsstatement,state_dir,
freshness_key_id,freshness_keyandrenewal, and no longerstale_at. -
scenario runrefuses a plane whose policy is not confirmed. -
POLICY_STALE's summary names an unconfirmed policy and a clock the plane
cannot judge by too; its identifier and number are unchanged. -
examples/evidence-reportprints ablockcolumn afterreasons: the
decision on the request'sACTION_BLOCKED,=when it is the kernel's, so a
call the plane blocked itself, paused or unclassified, shows why. Every later
column moves one to the right. -
examples/evidence-reportis a Go module of its own,example.com/evidence-report,
which reaches this repository's generated wire contract and nothing else of it;
build it withgo -C examples/evidence-report build -o "$PWD/bin/" .
(ADR-0037). Every
Go target of the gate runs once per module. -
The release workflow refuses a tag whose commit is not main's head or an
ancestor of it, or has no successful CI and Security run started by a push
tomainof exactly that commit: a pull request run never counts, a commit
that is not on main never passes, a tag namedmainincluded, and a listing
longer than one page is refused. Its dry
run takes the version the tag will carry, makes the same check and prints
that version's release notes. -
The configuration refuses a negative
upstream.call_timeout,
upstream.list_timeout,pdp.timeoutorexport.timeout, naming the key,
and a zeroupstream.call_timeout,pdp.timeoutorexport.timeout. A
negativeupstream.call_timeoutleft upstream calls without a bound and
dropped an obligation's shorter timeout too; the other three were refused
only later, at start, without the key. A configuration that set
upstream.call_timeout: 0for no bound sets a positive one,30sby
default.upstream.list_timeout: 0still means the adapter's own 30
seconds, whichdoctornow prints. -
guardana-gateway doctor'spolicyline andrun's first line say whether
policy.fail_open_readlets a read run while the policy is unavailable.
Fixed
runs listandruns closeno longer make an empty directory a runs
directory; they refuse it, and onlyruns openmakes one. A temporary file
left by a crash whileruns openmade the directory no longer makes every
later command and plane refuse it.- The evidence spool now refuses a segment or its quarantine log that is a
link, has a second name or was replaced since the spool listed or created
it, for appends, reads and truncation alike. A named pipe at a segment's
name is refused rather than waited on. - The evidence spool reaches every file through the directory it checked and
locked at start, so a directory renamed or replaced underevidence.dir
receives no segment. Refusing a segment with a second name, it gives the
device and inode, sofind -inumfinds the other name. A quarantine log
whose directory entry could not be synced is synced by the next append to it. - An upstream's JSON-RPC error to a
resources/readorprompts/getkeeps
every number in its data exactly as sent when the plane strips a key under its
namespace; an integer past 2^53 or a long decimal was rounded. - An HTTP listener refuses a request whose body has not arrived within 30
seconds and, for any request that carries a body, cuts the answer when
64 KiB of it cannot reach the client within 30 seconds, so neither a client
trickling its body nor one that stops reading holds a connection and a
handler; a slow client that keeps reading gets the whole answer. A session's GET stream is not bounded. - The plane's listener and health address close a kept-alive connection that
sends no next request within two minutes. - The plane strips a key under its namespace from an upstream's
_metaand
error data in any letter case, since a client may match keys to its own
fields without regard to case. guardana_control_policy_refresh_refused_totalcounts a refusal the build
cannot name undercause="unknown"and a bundle the plane's holder fails to
load underbundle_invalid; both were counted underfloor, which now means
only a floor that could not be read or raised, a raise that timed out
included.- A freshness statement that expires while the plane reads it is refused
understatement_expired, and nothing is raised or published; it was
published already expired, raised the floor and counted as a confirmation. - A shaped
tools/listanswer is cached under the policy bundle it was shaped
under, so a list shaped under one bundle is no longer served once another
is in force. - The health listener bounds a whole request at 30 seconds, so a trickled
body no longer holds a connection. - An answer write that moves no bytes fails instead of being retried without
end. - The hold journal and the trail file refuse a directory or a file another
account owns, and a platform that names no owner; the hold journal reaches
its entries only through the directory it opened and refuses one swapped in
at its name later. A plane no longer starts over a journal directory another
account owns, andcollect --outrefuses a path that names no file, such as
one ending in a separator. - A clock reading before 1970, the zero time among them, after 9999, or
earlier than the verified time, the latestissuedAtof a
statement it confirmed or of its floor, no longer lets the kernel decide:
the call isINDETERMINATEwithPOLICY_STALEand blocks on every effect
class, fail-open reads included, and/healthzreports a confirmed policy
expired. Such a reading let an expired delegation pass and could make a
bundle confirmed at the zero time read as fresh. Before it hands out an
approved or run-bound call, the plane treats as expired a reading outside
1970 to 9999 or earlier than one the call already relied on or than the
approval'srequested_at, so a clock set back after the decision no longer
runs an expired call, and a resume refused this way no longer spends its
approval.
Image: ghcr.io/guardana/control-gateway@sha256:4dd3c36b26e05246b74b1c11867171c7de7bc8426f891141e980b45b71b88e2a