Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-19262-sentinel-current-head.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The sentinel now judges a PR's current head (#19262). A PR that already carried `sentinel-alert` was never evaluated again, so a finding on an early head (a `Makefile` edit, say) kept the label, the dashboard's "Needs human · sentinel" state and the status section's `Head <old sha> matched` line on every later head, even a docs-only one. Every new head is now evaluated. When the current head matches no rule, the hive removes the label only if it added it itself for an earlier head's finding, rewrites its sentinel comment and the quiet-mode status section to say the current head is clean, and records `sentinel-alert-cleared` in the audit log; the earlier finding stays in `/api/sentinel` and its head's evidence bundle. A finding on the new head keeps the label and rewrites the alert for that head. A label a person added is never removed.
16 changes: 14 additions & 2 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -1352,6 +1352,15 @@ func sentinelSweepOptions(cfg *config.Config, ghClient *github.Client, dashSrv *
if dashSrv == nil {
return
}
if event.Cleared {
// The current head is clean and the hive removed its own
// label. The ring keeps the earlier head's finding for
// audit; only the clearance is logged (#19262).
detail := fmt.Sprintf("repo=%s, pr=%d, author=%s, head=%s, cleared_head=%s",
event.Repo, event.Number, event.Author, event.HeadSHA, event.ClearedHead)
dashSrv.AuditLogRecord("system", github.SentinelAlertClearedAuditAction, detail, "", event.Repo, event.Number)
return
}
// Findings the write-back gate refused still reach the Security
// tab and /api/sentinel: the scan happened, only the GitHub
// write did not (#writeback containment).
Expand Down Expand Up @@ -1407,8 +1416,8 @@ func runSentinelSweepIfDue(ctx context.Context, ghClient *github.Client, cfg *co
if dashSrv != nil && cfg.Dashboard.Matrix.Active() {
dashSrv.RecordMatrixIngest(time.Now(), matrixIngestInterval)
}
if len(result.Flagged) > 0 || len(result.Notified) > 0 || len(result.Remediated) > 0 || result.Seen > 0 {
logger.Info("sentinel sweep complete", "seen", result.Seen, "flagged", len(result.Flagged), "notified", len(result.Notified), "suppressed", len(result.Suppressed), "remediated", len(result.Remediated), "skipped", result.Skipped, "errors", len(result.Errors), "cached_repos", result.CachedRepos, "listed_repos", result.ListedRepos)
if len(result.Flagged) > 0 || len(result.Notified) > 0 || len(result.Remediated) > 0 || len(result.Cleared) > 0 || result.Seen > 0 {
logger.Info("sentinel sweep complete", "seen", result.Seen, "flagged", len(result.Flagged), "notified", len(result.Notified), "suppressed", len(result.Suppressed), "remediated", len(result.Remediated), "cleared", len(result.Cleared), "skipped", result.Skipped, "errors", len(result.Errors), "cached_repos", result.CachedRepos, "listed_repos", result.ListedRepos)
}
hookDispatcher().Fire(context.Background(), hooks.Payload{
Transition: hooks.TransitionSweepCompleted,
Expand Down Expand Up @@ -1436,6 +1445,9 @@ func logSentinelResult(result *github.SentinelSweepResult, logger *slog.Logger)
for _, ev := range result.Remediated {
logger.Info("sentinel unflagged trusted author PR", "repo", ev.Repo, "pr", ev.Number, "author", ev.Author, "trusted_reason", ev.TrustedReason, "head", ev.HeadSHA)
}
for _, ev := range result.Cleared {
logger.Info("sentinel cleared alert on clean head", "repo", ev.Repo, "pr", ev.Number, "author", ev.Author, "head", ev.HeadSHA, "cleared_head", ev.ClearedHead)
}
}

// issueUnparkSweepInterval is the minimum spacing between un-park sweeps. A
Expand Down
10 changes: 10 additions & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -715,6 +715,16 @@ In `normal` mode the informational notice is still its own comment, as
before. Either way the finding is recorded for audit, the dashboard
Security tab and `/api/sentinel`.

Both kinds are judged per head (hivecommons/hive#19262,
`pkg/github/sentinel_head_scope.go`). Every new head is evaluated, including
on a PR that already carries the label. When the current head matches no
rule, a card section naming an earlier head is rewritten to say the current
head is clean (no card is ever created for that), and a `sentinel-alert`
label the hive added for an earlier head's finding is removed, with the
hive's sentinel comment rewritten as a clean record that keeps the earlier
alert in a collapsed block. A finding on the new head keeps the label and
rewrites the alert for that head.

### Hive-maintained Actions workflows that defer to the card

Some comments come from GitHub Actions workflows in this repository rather
Expand Down
21 changes: 21 additions & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -757,6 +757,27 @@ Every alert is also written to the dashboard audit log as `sentinel-alert`,
and, when `evidence.enabled` is on, recorded under `sentinel` in the flagged
head's [review evidence bundle](../review-evidence.md).

The sentinel judges the PR's **current head** (hivecommons/hive#19262,
`pkg/github/sentinel_head_scope.go`). Each new head is evaluated on its own
files, even on a PR that already carries the label:

- **Finding on the new head:** the label stays and the hive's sentinel
comment is rewritten as the alert for that head.
- **Clean new head:** if the hive added the label for an earlier head's
finding (its own alert comment names an earlier head and the newest label
event is the hive's own, made no later than that comment), the label is
removed, the comment is rewritten to say the current head is clean with
the earlier alert kept in a collapsed block, a quiet-mode `sentinel` card
section is rewritten for the current head, and the audit log records
`sentinel-alert-cleared`. A label a person added, directly or through the
dashboard after the alert, is never removed, and neither is any label when
the hive cannot name its own accounts.
- **Unchanged head:** skipped, as before.

The dashboard's sentinel state follows the live label plus the findings
recorded for the current head, so it clears with the label. Earlier heads'
findings stay in `/api/sentinel` for audit.

On the dashboard's Projects cards, every open PR that carries the configured
sentinel label is drawn as a red pill (status chip and main pill), taking
precedence over the held, needs-human and merge colours, and the pill legend
Expand Down
9 changes: 8 additions & 1 deletion src/docs/security-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -564,7 +564,14 @@ sensitive paths, owner self-nomination, permission escalation in workflows,
secret exposure, CI gate weakening, test removal, security policy edits, and
remote code execution patterns. A match applies `sentinel-alert`, posts one
comment and writes an audit entry. The label blocks Hive approval and every
automerge lane until a maintainer removes it.
automerge lane until a maintainer removes it, or until a later head matches
no rule. Findings are head-scoped: every new head is evaluated again, and
when the current head is clean Hive removes the label only if Hive itself
added it for an earlier head's finding (its own alert comment names that
head, and the newest label event is Hive's own, made no later than that
comment). A label a person added stays. The earlier finding is kept in the
audit log (`sentinel-alert-cleared` records the removal), `/api/sentinel`
and that head's review evidence bundle.
Whether that label and comment reach GitHub is decided by the **write-back
containment gate** (`pkg/writeback`): on a PR Hive did not open, sentinel
writes need ACMM L5 plus the review opt-in label (L6 without it), the repo
Expand Down
73 changes: 73 additions & 0 deletions src/pkg/dashboard/stage_tracker_sentinel_head_scope_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
package dashboard

import (
"slices"
"testing"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/sentinel"
)

// TestStageTrackerSentinelJudgesCurrentHead (hivecommons/hive#19262): the
// tracker's sentinel state belongs to the PR's current head. A finding the
// sweep recorded for an earlier head stays in the /api/sentinel ring for
// audit, but once the sweep has removed its own label for a clean new head
// the row no longer reads "Needs human · sentinel" and names no findings; a
// finding on the new head, or a label a person put on, still flags it.
func TestStageTrackerSentinelJudgesCurrentHead(t *testing.T) {
const (
repo = "acme/console"
number = 19192
oldHead = "0bee4e4aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
newHead = "f718e15bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
)
s := newTestServer()
s.RecordSentinelFinding(github.SentinelSweepEvent{Repo: repo, Number: number, HeadSHA: oldHead, Blocked: true, Findings: []sentinel.Finding{
{Rule: sentinel.RuleSensitivePath, Summary: "changes 1 sensitive path(s)", Paths: []string{"Makefile"}},
}})

// Old head, label on: flagged, with the old head's details.
alert, _, _, details := s.stageTrackerSentinel(nil, repo, number, oldHead, []string{config.DefaultSentinelLabel})
if !alert || len(details) != 1 {
t.Fatalf("old head: alert=%v details=%+v", alert, details)
}

// Clean new head after the sweep removed its label: not flagged, and the
// old head's finding is not shown as this head's.
alert, n, reason, details := s.stageTrackerSentinel(nil, repo, number, newHead, []string{"lgtm"})
if alert || n != 0 || reason != "" || details != nil {
t.Fatalf("clean new head must not flag: alert=%v n=%d reason=%q details=%+v", alert, n, reason, details)
}
if slices.Contains(stageTrackerHumanGateReasons(StageTrackerItem{Kind: "pr", Head: newHead, SentinelAlert: alert}), gateReasonSentinel) {
t.Fatal("clean new head must not carry the sentinel human gate")
}
if !slices.Contains(stageTrackerHumanGateReasons(StageTrackerItem{Kind: "pr", Head: oldHead, SentinelAlert: true}), gateReasonSentinel) {
t.Fatal("positive control: a flagged head carries the sentinel human gate")
}

// A label still on the new head (a person's, which the sweep leaves
// alone) keeps the gate.
if alert, _, _, _ := s.stageTrackerSentinel(nil, repo, number, newHead, []string{config.DefaultSentinelLabel}); !alert {
t.Fatal("a sentinel label on the current head must still flag")
}

// A finding recorded for the new head is the new head's.
s.RecordSentinelFinding(github.SentinelSweepEvent{Repo: repo, Number: number, HeadSHA: newHead, Blocked: true, Findings: []sentinel.Finding{
{Rule: sentinel.RuleSensitivePath, Summary: "changes 1 sensitive path(s)", Paths: []string{"Makefile"}},
}})
if _, _, _, details := s.stageTrackerSentinel(nil, repo, number, newHead, []string{config.DefaultSentinelLabel}); len(details) != 1 {
t.Fatalf("new head finding details=%+v", details)
}

// History is kept: both heads stay in the ring.
heads := map[string]bool{}
for _, f := range s.sentinelFindings.list() {
if f.Number == number {
heads[f.HeadSHA] = true
}
}
if !heads[oldHead] || !heads[newHead] {
t.Fatalf("ring must keep every head's finding for audit: %v", heads)
}
}
Loading
Loading