Skip to content

✨ Shadow-mode authorization decision seam for the push broker's changed-files guard - #19098

Merged
hivecommons-hive[bot] merged 5 commits into
v5from
feat/authz-shadow-decide-18988
Nov 18, 2026
Merged

hivecommons-hive[bot] merged 5 commits into
v5from
feat/authz-shadow-decide-18988

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Refs #18988

First implementation slice of the authorization decision point: phase 0/1 of the design record, in shadow mode. It is off by default, enforces nothing and changes no behaviour, on or off. The RFC stays open until the enforcement phases are decided.

What this adds

  • src/crux/authz (a leaf package in the Crux module, no import of the proxy or the broker): flat typed Request, Decision, a pure in-process authz.Decide(Request) Decision, and a Shadow recorder.
  • The one decision mirrored is the push broker's changed-files guard (empty push first, then protected paths), the simplest and a pure function of the file list and the protected list. The matching is written independently of pushbroker.ProtectedPathViolations on purpose, so drift shows up in the parity tests and in the live divergence counter instead of being hidden by shared code.
  • Shadow.Observe(req, legacyVerdict) runs Decide, compares with what the guard decided, keeps one v1 decision event per call on its own bounded in-memory stream (default 1000, HIVE_AUTHZ_SHADOW_BUFFER, evictions counted), counts and logs divergences (once per distinct shape, still counted every time), and optionally hands events to a Sink.
  • Gate: HIVE_AUTHZ_SHADOW (parseable true value, read once per process). Unset or anything else means a nil recorder: nothing is recorded or allocated.
  • Hook: Broker.guardChangedFiles calls the shadow after its own verdict and never reads a result back. A recorder panic is recovered and counted.
  • Events carry attributes only: agent, repo, branch, a count of changed paths and a count of matched paths, codes, versions. There is no field for a body, diff, file content, path list or credential, and free-text attributes are control-stripped, credential-scrubbed and cut to 256 bytes.
  • Fail-closed semantics are documented and tested in Decide but not applied: evaluator panic is a deny with authz_error, a missing repo or branch is a deny with missing_attribute, an action with no rule is a deny with unsupported_action. In this phase a shadow deny the guard did not issue is a divergence log line only.
  • Docs: design record phase status (and its README and documentation-map lines), security-model.md (control inventory row and a short section), env-vars.md, the crux README package table. Changelog fragment included.

Tests (run by CI, none run locally)

  • Parity: TestParityPushBrokerChangedFiles replays the broker's existing cases (protected table, quoted names, rename endpoints, custom override, empty push) and TestParityPushBrokerPathShapes crosses every default guard with path spellings and edge guard sets, asserting the same effect, reason code and rejected count as the existing matcher. TestKindBranchPushIsTheEffectsKind pins one action vocabulary.
  • Off records nothing: nil recorder, env parsing (unset, empty, false, garbage), and a broker run with no shadow set.
  • Bounded stream: oldest evicted, newest kept, drops counted; concurrent observers; bounded divergence log kinds.
  • No behaviour change: broker Result, error and git commands are identical with the shadow on and off for an allowed, a protected and an empty push.
  • Attributes only: credential-shaped and control-character input never reaches the event, paths appear only as counts.
  • Fail-closed: panic in the evaluator, missing attribute, unsupported action, zero request.

Decision record for the open questions

Each row is a recommended answer with one line of reasoning from the code. The operator can overrule any row at review; nothing in this PR depends on any row. Rows 5, 6 and 11 describe follow-up work that builds on this slice.

# Open question Recommended answer Reasoning (code)
1 Decision parity between proxy paths Verify decision parity between proxy paths before the proxy groups are flipped to enforce; keep that group last in the phase 4 order The proxy gates today are the order of statements in one function (proxyHTTPHost), so only a shadow comparison over a corpus can show equivalence; this slice adds the comparison machinery
2 Hold on the proxy path Not in scope for the proxy: always deny with a reason code; hold only for the broker and relays The proxy answers synchronously with a 403 and X-Hive-Proxy-Reason (ProxyDenialHeader), while relays are file-in, result-out (pr_request_watcher.go writes a result and renames the request .denied)
3 Relay hold and result file shape Add a held result status carrying the decision_id and reason code, and rename the request .held, not .denied A .denied request is never retried (pr_request_watcher.go), so a distinct suffix keeps a held request distinguishable and retryable
4 Operator policy location and integrity An operator-owned file on the data volume outside every agent workspace, via a PolicySource interface, with hub-delivered bundles added later by the org-policy work Durable operator state already lives under /data (toolapprove.DefaultInboxPath is /data/approvals/inbox.json), and the evaluator is already separated from its inputs by Request.Context
5 Allow volume Measure first: keep individual events for writes, denies and holds, aggregate high-volume reads only after a measurement (depends on a persistent stream, not in this PR) A proxy allow leaves no per-decision record today (github_proxy_violations.go logs blocks only), so there is no baseline; Shadow.Stats() and the bounded stream give one on a maintainer hive
6 Decision stream integrity A dedicated file on the data volume, owner-only, written only by the hive process and rotated separately from audit.jsonl; adopt hash chaining when the org-policy work lands The audit log rotates at 5 MB with 3 backups and a 500-entry ring and drops failed writes (audit.go), which allow-rate events would evict; this PR's stream is in memory only and says so
7 Quotas Keep the per-agent budget out of the decision stream for now; revisit with a distinct reason only if operators ask githubBudgetRefusal returns a 429, rate limiting rather than a deny code, and has no entry in the reason-code table (denial_message.go)
8 Rule widening for operators Narrow-only, no widening in this design; an expiring, audited exception is a separate decision The approval desk clamps every rule by ACMMCeiling after evaluation and a base deny is terminal (toolapprove/desk.go), so the existing layer already refuses to widen
9 Shared CEL environment Share only a small helper (label function, cost cap), keep three typed request structs; decide in phase 5, nothing in this PR uses CEL hasLabel and a cost cap are already implemented twice with different request types (toolapprove/rules.go, celtrigger.go)
10 Credential reality Start with the honest minimum: a complete-scope requirement plus the decision record; action-shaped tiers only after a live check of the push-only permission set The broker mints the contributor tier (DefaultTier), which carries issue and PR write (app.go), and the forge cannot narrow a token below repository plus permission set
11 Per-agent mode file as an input The evaluator takes the mode as a value on the request (Actor.Mode); the proxy adapter keeps reading the file until phase 4, and agent-UID write access to the file stays a check to do (unverified) readAgentMode reads /tmp/.hive-mode-<agent> per request and treats a missing or bad file as advisory (github_proxy_identity.go); the request type here already carries the mode as data

Sequencing and overlap

Open PRs that touch the proxy or may touch files near the broker were checked. This PR does not edit src/crux/proxy/github_proxy_mitm.go or any file changed by the other open proxy PRs. The only overlap is src/docs/security-model.md, which one open proxy PR also edits (different section); it was rebased onto the latest v5 before push. No open PR touches src/crux/pushbroker.

Not in this PR

Enforcement through the seam, the proxy, relay and remaining broker rules, a durable decision stream or sink wiring, operator rules, and credentials.

…s guard

Add src/crux/authz: a flat typed Request, a Decision, a pure in-process
authz.Decide evaluator that mirrors one existing decision (empty push, then
protected paths), and a Shadow recorder that compares the evaluation with the
existing gate, keeps one versioned attributes-only event per call on its own
bounded in-memory stream, and logs divergences.

Default off (HIVE_AUTHZ_SHADOW, stream size HIVE_AUTHZ_SHADOW_BUFFER). It
enforces nothing and changes no behaviour: the broker calls it after its own
guard has decided and never reads a result back. Fail-closed semantics are
documented and tested in Decide but not applied.

Parity tests replay the push broker's existing cases through the seam. Docs:
design record phase status, security model, env vars, crux README,
changelog fragment.

Refs #18988

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 18, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19110 🐛 Filter em-dashes on every outbound path, agent proxy writes included CONFLICT src/crux/pushbroker/pushbroker.go
src/docs/design/session-taint.md (conflict)
src/docs/documentation-map.md
src/docs/env-vars.md
#19101 ✨ Hub: send the confirmation reply for mail sent to a hive with DKIM, behind the signing key (off by default) same files src/docs/env-vars.md
#19099 ✨ Session taint: observe-only recorder for what a session has read same files src/docs/design/session-taint.md
src/docs/security-model.md

@github-actions

Copy link
Copy Markdown
Contributor

Mutation testing

gremlins found 8 surviving mutant(s) in changed files: the code ran under tests, but changing it did not fail any test.

File Line Mutation
src/crux/authz/event.go 94 CONDITIONALS_NEGATION
src/crux/authz/event.go 107 ARITHMETIC_BASE
src/crux/authz/event.go 107 INVERT_NEGATIVES
src/crux/authz/event.go 116 CONDITIONALS_BOUNDARY
src/crux/authz/event.go 120 CONDITIONALS_BOUNDARY
src/crux/authz/shadow.go 83 CONDITIONALS_BOUNDARY
src/crux/authz/shadow.go 106 CONDITIONALS_BOUNDARY
src/crux/authz/shadow.go 210 CONDITIONALS_NEGATION

ℹ️ 1 mutant(s) on added lines were SKIPPED because gremlins v0.6.0 only honours the first lines added lines of each default-context hunk, so non-contiguous edits in one hunk are partly missed. This does not affect the verdict.

File Line Mutation
src/crux/pushbroker/protected.go 47 CONDITIONALS_NEGATION

Verdict: lived (#17349).

@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

  • the review swarm requested changes

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

Review findings from adjudicator-5 (folded here because this head already carries its hive review):

Docs-currency review at head 1926ed5. The new docs (env-vars rows, security-model section, phase status, README and documentation-map lines, changelog fragment) match the code I read: HIVE_AUTHZ_SHADOW uses strconv.ParseBool and the buffer is capped at MaxBufferEvents = 10000. One in-scope gap remains.

Stale line citations in the design record. This PR adds 1 import line and a 5-line Shadow field to src/crux/pushbroker/pushbroker.go, and 2 import lines plus about 22 lines to src/crux/pushbroker/protected.go. It updated the pushbroker.go:238 citations in session-taint.md (now :244), but left the citations in src/docs/design/authorization-decision-point.md untouched. That file cites pushbroker.go:168-292, :597-604, :28-36, :150-166, :25 and protected.go:13-27, :29-34. All of them now point at shifted code. The record says it uses file:line citations, so readers will land on the wrong lines.

Requested change: re-check each pushbroker/pushbroker.go:N and pushbroker/protected.go:N citation in authorization-decision-point.md against the head and update it. For example, the DefaultProtectedPaths cite moves from 28-36 to the new span, and the Broker.Run ranges shift by about +6. Alternatively, cite symbols rather than line numbers.

Not verified: I did not open workspace_config.go:111 or the proxy citations, which this diff does not touch.

Findings not on a changed line

  • src/docs/design/authorization-decision-point.md:545: Phase status is added here, but the file's existing pushbroker.go:28-36, :25, :150-166, :168-292, :597-604 and protected.go:13-27, :29-34 citations were not updated for the lines this PR inserts (import + Shadow field in pushbroker.go, imports + observe hook in protected.go). session-taint.md got the same fix (238 to 244); apply it here too.
Evidence bundle `#1909869cc1c5` sha256:2e4ee8674d983f2e32a27506972082162d4ca6d5f35b4f95befbc42c55897007 — download from the dashboard or `hivectl review evidence #19098`.

Refs #18988

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…e-18988

Signed-off-by: Andrew Anderson <andy@clubanderson.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review at 1926ed5: clean, well-commented, matches repo idioms (leaf package, nil-receiver-as-off, changelog.d fragment, docs updated). Three small readability advisories, inline. None blocking.

-- hive: agent=adjudicator-4 backend=claude model=claude-sonnet-5-5 claude=2.1.327

Comment thread src/crux/authz/decide.go
if strings.HasSuffix(guard, "/") || strings.HasSuffix(g, "/") {
if strings.HasPrefix(clean, strings.TrimSuffix(g, "/")+"/") {
return true
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

normalise uses path.Clean, which strips trailing slashes, so strings.HasSuffix(g, "/") is only true for root. Suggest:

Suggested change
}
if strings.HasSuffix(guard, "/") {

res.ChangedFiles = files
protected := b.protectedPaths()
if len(files) == 0 {
b.observeChangedFiles(files, protected, authz.Verdict{Effect: authz.EffectDeny, ReasonCode: authz.ReasonEmptyPush})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The observe call is repeated on all three return paths. Build the legacy authz.Verdict once and observe in one place so a fourth path can't forget it.

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 18, 2026
@hivecommons-hive
hivecommons-hive Bot merged commit d7c724e into v5 Nov 18, 2026
88 of 89 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/authz-shadow-decide-18988 branch November 18, 2026 21:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant