Skip to content

Guardana Control 0.6.0-alpha

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 03 Oct 19:17
· 270 commits to main since this release
Immutable release. Only release title and notes can be modified.

A 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.jsonl and 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 renew verifies 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 init makes a floor directory and a bundle
    id's floor, never replacing one, and policy state reset lowers a floor,
    recording the reason and the value it replaced.
  • /healthz carries a policy object: freshness, one of confirmed,
    unconfirmed and expired, 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" with 200; a halted plane still
    answers halted with 503.
  • /metrics carries guardana_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's policy line 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_idle sets how long a stateful_http session 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_sessions caps a stateful_http listener's live sessions,
    from 1 to 16384, 1024 by default; an open past it is answered 503, and a
    request whose body is still arriving holds no place. Another listener kind
    refuses the key. /metrics carries
    guardana_control_adapter_sessions_live and
    guardana_control_adapter_sessions_refused_total.
  • guardana-control policy explain prints a clock line: 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_key and policy.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_dir must be a directory
    policy state init --kind plane made; poll_interval is at least 1s and
    shorter than policy.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 every policy.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.

  • /healthz leaves out bundle.confirmed_at while no statement confirms the
    bundle.

  • dev makes 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 prints statement, state_dir,
    freshness_key_id, freshness_key and renewal, and no longer stale_at.

  • scenario run refuses 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-report prints a block column after reasons: the
    decision on the request's ACTION_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-report is 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 with go -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
    to main of exactly that commit: a pull request run never counts, a commit
    that is not on main never passes, a tag named main included, 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.timeout or export.timeout, naming the key,
    and a zero upstream.call_timeout, pdp.timeout or export.timeout. A
    negative upstream.call_timeout left 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: 0 for no bound sets a positive one, 30s by
    default. upstream.list_timeout: 0 still means the adapter's own 30
    seconds, which doctor now prints.

  • guardana-gateway doctor's policy line and run's first line say whether
    policy.fail_open_read lets a read run while the policy is unavailable.

Fixed

  • runs list and runs close no longer make an empty directory a runs
    directory; they refuse it, and only runs open makes one. A temporary file
    left by a crash while runs open made 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 under evidence.dir
    receives no segment. Refusing a segment with a second name, it gives the
    device and inode, so find -inum finds 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/read or prompts/get keeps
    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 _meta and
    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_total counts a refusal the build
    cannot name under cause="unknown" and a bundle the plane's holder fails to
    load under bundle_invalid; both were counted under floor, 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
    under statement_expired, and nothing is raised or published; it was
    published already expired, raised the floor and counted as a confirmation.
  • A shaped tools/list answer 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, and collect --out refuses 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 latest issuedAt of a
    statement it confirmed or of its floor, no longer lets the kernel decide:
    the call is INDETERMINATE with POLICY_STALE and blocks on every effect
    class, fail-open reads included, and /healthz reports 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's requested_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