diff --git a/changelog.d/changed-18453-sentinel-notice-status-card.md b/changelog.d/changed-18453-sentinel-notice-status-card.md new file mode 100644 index 0000000000..197998fcf5 --- /dev/null +++ b/changelog.d/changed-18453-sentinel-notice-status-card.md @@ -0,0 +1 @@ +- Sentinel: in `github.notifications.mode: quiet` (the default) the informational notice on a trusted author's PR (no label, merge not blocked) is now a `sentinel` section of the PR's `hive:status` card, edited in place, instead of a new comment per PR. A sentinel hold (`sentinel-alert` label, maintainer review required), including one from `sentinel.trusted_authors_block`, still posts its own comment, and `normal` mode is unchanged (#18453). diff --git a/src/docs/notifications.md b/src/docs/notifications.md index 9000f51b06..b8eef9e64f 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -491,6 +491,7 @@ without a class. Review submissions and review requests are always counted as | `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | | | `github.(*Client).closeSupersededPRDecision` | `status` | | | `github.(*Client).fileReviewBacklog` | `status` | | +| `github.(*Client).foldSentinelNotice` | `status` | informational sentinel notice folded into the PR status card (quiet mode); a blocking alert is never folded | | `github.(*Client).joinFleetReportIssue` | `status` | | | `github.(*Client).markInProgressStarted` | `status` | | | `github.(*Client).postUnblockedNote` | `status` | | @@ -668,6 +669,35 @@ github: reminder_interval: 24h # default 24h ``` +### Sentinel notices in the PR status card + +The sentinel (`pkg/github/sentinel_sweep.go`) has two kinds of result, and +only one of them asks a person to do anything +(hivecommons/hive#18453): + +- **Actionable: a hold.** The author is untrusted, or + `sentinel.trusted_authors_block` is `true`. The hive adds the + `sentinel-alert` label and posts its ` ` + "Sentinel alert - maintainer review required" comment. This happens in + **every** mode, quiet included, because only a new comment notifies. + A security hold is never folded into the card. +- **Informational.** The author is trusted and the merge is not blocked. In + `github.notifications.mode: quiet` (the default) this is the `sentinel` + section of the PR's `hive:status` card, edited in place. A new head + rewrites that section, so the PR gets no notice comment at all. The card + is created only when the PR has none yet. The section is stamped + ``. It never carries the + `` marker, because the sweep reads that marker back + to tell which head it alerted on and whether a maintainer cleared it. When + the same PR is later put on hold, the hive posts the alert comment and + drops the stale informational section from the card. A PR that already + has a sentinel comment from before this change keeps it, rewritten in + place for the new head. + +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`. + ### Hive-maintained Actions workflows that defer to the card Some comments come from GitHub Actions workflows in this repository rather diff --git a/src/docs/operator-reference/sweeps-and-operations.md b/src/docs/operator-reference/sweeps-and-operations.md index 1adeee5c39..e60fabb31f 100644 --- a/src/docs/operator-reference/sweeps-and-operations.md +++ b/src/docs/operator-reference/sweeps-and-operations.md @@ -587,6 +587,11 @@ post on issues and merged PRs as comments of their own: - a contributor's **claim marker** (``) posted by the contribute hub — claim readers scan every hive comment body for the marker, so the section is as authoritative as the comment was; +- the sentinel's **informational notice** for a trusted author's PR (no + label, merge not blocked), as a `sentinel` section stamped + ``. A sentinel **hold** + (`sentinel-alert` label, maintainer review required) is never folded: it + always posts its own `` comment (hivecommons/hive#18453); - an agent's relayed **status notes**: `hive/awaiting-ci: …`, `Parking on stage/045-needs-decision: …` and `Already fixed …`. Any other relayed comment — a finding, a triage verdict with evidence, a question — is still @@ -696,7 +701,10 @@ auto-merge lane (dashboard queue, self-authored App sweep, trusted bot authors, or trusted authors). Trusted authors (the Hive App, configured trusted bots and owner/trusted-author allow-list entries) default to an informational notice and audit/dashboard finding only; no alert label is added unless the operator opts -into blocking them. A maintainer who removes the label keeps the PR clear until +into blocking them. In `github.notifications.mode: quiet` (the default) that +informational notice is a `sentinel` section of the PR's `hive:status` card, +edited in place, rather than a comment; an alert that needs a maintainer always +gets its own comment ([#18453](https://github.com/hivecommons/hive/issues/18453)). A maintainer who removes the label keeps the PR clear until the author pushes again: the sweep reads the clearance back from the alert comment it left for that head (alert comment present, label absent), so it survives a hub restart or a second replica and nothing else needs to be posted. @@ -723,7 +731,7 @@ push re-arms it. |---|---|---| | `sentinel.enabled` | **on** when unset | `false` disables the sweep entirely. | | `sentinel.label` | `sentinel-alert` | Label added to untrusted flagged PRs (created red if missing). Neutral on purpose: it means "look closely", not "malicious". This configured label is also added to Hive's hold/exclude set and blocks Hive approval plus every auto-merge lane until a human removes it. | -| `sentinel.trusted_authors_block` | `false` | When `false`, trusted author findings are notice-only: comment, audit/dashboard record, no label, no approval/merge block. Set `true` to add the blocking label for trusted authors too. | +| `sentinel.trusted_authors_block` | `false` | When `false`, trusted author findings are notice-only: audit/dashboard record, no label, no approval/merge block. The notice is the `sentinel` section of the PR's `hive:status` card in `github.notifications.mode: quiet` (the default) and its own comment in `normal` mode. Set `true` to add the blocking label and post the alert comment for trusted authors too. | | `sentinel.sensitive_paths` | shipped defaults (`sentinel.DefaultSensitivePaths`) | Glob list (same syntax as `intent.guardrail_path_patterns`; `**` crosses directories) that **replaces** the defaults when set. Defaults cover OWNERS/CODEOWNERS/MAINTAINERS, SECURITY.md, GOVERNANCE.md, `.github/workflows/**`, actions, dependabot, codeql, rulesets, CI config, Makefile/Justfile, pre-commit hooks, `policies/**`, `hive.yaml*`, `gh-wrapper*`, proxy rules, Dockerfiles, `install.sh`, dependency manifests and lockfiles, release workflows, `.env*`/key material, `deploy/**`, Terraform, Helm/k8s manifests. | | `sentinel.disabled_behaviors` | empty | Rule names from the table above to switch off. Unknown names are rejected. | | `sentinel.exempt_logins` | empty | GitHub logins never flagged (e.g. a release bot). Use sparingly. | diff --git a/src/pkg/github/notification_write_sites.go b/src/pkg/github/notification_write_sites.go index aa923dc950..798ab9a7d6 100644 --- a/src/pkg/github/notification_write_sites.go +++ b/src/pkg/github/notification_write_sites.go @@ -54,6 +54,7 @@ var notificationWriteSites = map[string]NotificationWriteSite{ "github.(*Client).closeIssueForMergedPRClaimWithIssue": {Class: NotificationClassStatus}, "github.(*Client).closeSupersededPRDecision": {Class: NotificationClassStatus}, "github.(*Client).fileReviewBacklog": {Class: NotificationClassStatus}, + "github.(*Client).foldSentinelNotice": {Class: NotificationClassStatus}, "github.(*Client).joinFleetReportIssue": {Class: NotificationClassStatus}, "github.(*Client).markInProgressStarted": {Class: NotificationClassStatus}, "github.(*Client).postUnblockedNote": {Class: NotificationClassStatus}, diff --git a/src/pkg/github/sentinel_status_card.go b/src/pkg/github/sentinel_status_card.go new file mode 100644 index 0000000000..80d14973c4 --- /dev/null +++ b/src/pkg/github/sentinel_status_card.go @@ -0,0 +1,116 @@ +package github + +import ( + "context" + "fmt" + "sort" + "strings" + + "github.com/hivecommons/hive/pkg/sentinel" +) + +// Sentinel notices in the status card (hivecommons/hive#18453). +// +// A sentinel result is one of two kinds: +// +// - actionable: the finding blocks (untrusted author, or +// sentinel.trusted_authors_block), so the alert label goes on and a +// maintainer has to review or clear it. That always gets its own +// `` comment, in every notification mode, because +// a new comment is the only write that notifies anyone. +// - informational: the author is trusted and the merge is not blocked. +// Nobody has to act. In github.notifications.mode: quiet this becomes the +// `sentinel` section of the PR's hive:status card, edited in place, so a +// trusted author's PR is not emailed a notice per head. In normal mode it +// is still its own comment, as before. +// +// The card section carries SentinelNoticeCardMarker, never SentinelMarker: +// the sweep reads its own sentinel comment back (which head it alerted on, +// whether a maintainer cleared it), and a card that carried that marker +// would be read as the sentinel comment and could be rewritten into an +// alert that notifies nobody. +const ( + // SentinelStatusKey is the hive:status section holding the + // informational sentinel notice in quiet mode. + SentinelStatusKey = "sentinel" + // SentinelNoticeCardMarker stamps the card section with the head it + // describes. It deliberately does not contain SentinelMarker. + SentinelNoticeCardMarker = "\n", SentinelNoticeCardMarker, head) + fmt.Fprintf(&b, "ℹ️ **Sentinel:** informational, author is trusted (%s), merge is not blocked. Head `%s` matched:\n", reason, shortSHA(head)) + for _, f := range findings { + fmt.Fprintf(&b, "- `%s`: %s", f.Rule, f.Summary) + paths := append([]string(nil), f.Paths...) + sort.Strings(paths) + if len(paths) > 0 { + shown := paths + if len(shown) > sentinelCardMaxPaths { + shown = shown[:sentinelCardMaxPaths] + } + quoted := make([]string, 0, len(shown)) + for _, p := range shown { + quoted = append(quoted, "`"+p+"`") + } + fmt.Fprintf(&b, " (%s", strings.Join(quoted, ", ")) + if extra := len(paths) - len(shown); extra > 0 { + fmt.Fprintf(&b, ", +%d more", extra) + } + b.WriteString(")") + } + b.WriteString("\n") + } + fmt.Fprintf(&b, "\nNo `%s` label was added. The finding is recorded in the dashboard Security tab and `/api/sentinel`; set `%s.trusted_authors_block: true` to block trusted authors too.", decision.Label, SentinelConfigKey) + return b.String() +} diff --git a/src/pkg/github/sentinel_status_card_test.go b/src/pkg/github/sentinel_status_card_test.go new file mode 100644 index 0000000000..48043cdd7f --- /dev/null +++ b/src/pkg/github/sentinel_status_card_test.go @@ -0,0 +1,281 @@ +package github + +// Tests for hivecommons/hive#18453: in github.notifications.mode: quiet an +// informational sentinel notice (trusted author, merge not blocked) is the +// `sentinel` section of the PR's hive:status card, edited in place; a +// blocking alert (untrusted author, or trusted_authors_block) still posts +// its own comment; normal mode is unchanged. + +import ( + "context" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/prstatus" + "github.com/hivecommons/hive/pkg/sentinel" +) + +const sentinelCardBot = "hive-app[bot]" + +func sentinelWorkflowFiles(num int) map[int][]map[string]any { + return map[int][]map[string]any{num: {{ + "filename": ".github/workflows/ci.yml", "status": "modified", "patch": "+permissions: write-all\n", + }}} +} + +func trustedSentinelOpts() SentinelSweepOptions { + opts := defaultSentinelOpts(nil) + opts.TrustedAuthor = func(repo, author string) SentinelAuthorTrust { + if author == "mallory" { + return SentinelAuthorTrust{} + } + return SentinelAuthorTrust{Trusted: true, Reason: "hive agent"} + } + return opts +} + +func quietSentinelClient(t *testing.T, srv *httptest.Server, quiet bool) *Client { + t.Helper() + c := newTestClient(t, srv, "o", []string{"o/r"}) + c.appBotLogin = sentinelCardBot + c.SetNotificationsQuiet(func() bool { return quiet }) + return c +} + +func countContaining(bodies []string, needle string) int { + n := 0 + for _, b := range bodies { + if strings.Contains(b, needle) { + n++ + } + } + return n +} + +func TestSentinelQuietTrustedNoticeFoldsIntoStatusCard(t *testing.T) { + f := &sentinelFixture{ + prs: []map[string]any{sentinelPR(30, "hivecommons-hive[bot]", "head1aaaaaaa")}, + files: sentinelWorkflowFiles(30), + } + srv := newSentinelServer(t, f) + defer srv.Close() + c := quietSentinelClient(t, srv, true) + + res, err := c.SweepSentinel(context.Background(), trustedSentinelOpts()) + if err != nil { + t.Fatalf("sweep: %v", err) + } + if len(res.Notified) != 1 || len(res.Flagged) != 0 || len(res.Errors) != 0 { + t.Fatalf("res=%+v", res) + } + if len(f.labels[30]) != 0 { + t.Fatalf("informational notice must not label: %v", f.labels[30]) + } + if n := countContaining(f.comments[30], SentinelMarker); n != 0 { + t.Fatalf("informational notice must not post a sentinel comment: %v", f.comments[30]) + } + if len(f.comments[30]) != 1 || !prstatus.IsStatusComment(f.comments[30][0]) { + t.Fatalf("want exactly the status card, got %v", f.comments[30]) + } + section, ok := prstatus.Get(f.comments[30][0], SentinelStatusKey) + if !ok { + t.Fatalf("card has no sentinel section:\n%s", f.comments[30][0]) + } + for _, want := range []string{SentinelNoticeCardMarker + " head1aaaaaaa", "informational", "hive agent", "merge is not blocked", "`permission_escalation`"} { + if !strings.Contains(section, want) { + t.Errorf("section missing %q:\n%s", want, section) + } + } + + // A new head on the same PR edits the card section in place: still one + // comment on the PR, now naming the new head. + f.mu.Lock() + f.commentUsers = map[int][]string{30: {sentinelCardBot}} + f.prs[0]["head"] = map[string]string{"sha": "head2bbbbbbb"} + f.mu.Unlock() + _, _, suppressedBefore := c.NotificationCounts() + res, err = c.SweepSentinel(context.Background(), trustedSentinelOpts()) + if err != nil { + t.Fatalf("sweep 2: %v", err) + } + if len(res.Notified) != 1 || len(res.Errors) != 0 { + t.Fatalf("res2=%+v", res) + } + if len(f.comments[30]) != 1 { + t.Fatalf("new head must edit the card, not comment: %v", f.comments[30]) + } + section, _ = prstatus.Get(f.comments[30][0], SentinelStatusKey) + if !strings.Contains(section, "head2bbbbbbb") || strings.Contains(section, "head1aaaaaaa") { + t.Fatalf("section not rewritten for the new head:\n%s", section) + } + if _, _, suppressedAfter := c.NotificationCounts(); suppressedAfter <= suppressedBefore { + t.Fatalf("folded notice should count as suppressed: before=%d after=%d", suppressedBefore, suppressedAfter) + } +} + +func TestSentinelQuietUntrustedHoldStillComments(t *testing.T) { + card := prstatus.Upsert("", SentinelStatusKey, SentinelNoticeCardMarker+" old -->\nℹ️ **Sentinel:** informational, merge is not blocked.") + card = prstatus.Upsert(card, "other", "keep me") + f := &sentinelFixture{ + prs: []map[string]any{sentinelPR(31, "mallory", "evil1")}, + files: sentinelWorkflowFiles(31), + comments: map[int][]string{31: {card}}, + commentUsers: map[int][]string{31: {sentinelCardBot}}, + } + srv := newSentinelServer(t, f) + defer srv.Close() + c := quietSentinelClient(t, srv, true) + + res, err := c.SweepSentinel(context.Background(), trustedSentinelOpts()) + if err != nil { + t.Fatalf("sweep: %v", err) + } + if len(res.Flagged) != 1 || len(res.Notified) != 0 || len(res.Errors) != 0 { + t.Fatalf("res=%+v", res) + } + if got := f.labels[31]; len(got) != 1 || got[0] != "sentinel-alert" { + t.Fatalf("hold label=%v", got) + } + if n := countContaining(f.comments[31], sentinelAlertHeading); n != 1 { + t.Fatalf("hold must post its own alert comment: %v", f.comments[31]) + } + if _, ok := prstatus.Get(f.comments[31][0], SentinelStatusKey); ok { + t.Fatalf("stale informational section must be cleared on alert:\n%s", f.comments[31][0]) + } + if body, ok := prstatus.Get(f.comments[31][0], "other"); !ok || body != "keep me" { + t.Fatalf("other card sections must survive: %q %v", body, ok) + } +} + +func TestSentinelQuietTrustedAuthorsBlockStillComments(t *testing.T) { + f := &sentinelFixture{ + prs: []map[string]any{sentinelPR(32, "hivecommons-hive[bot]", "blk1")}, + files: sentinelWorkflowFiles(32), + } + srv := newSentinelServer(t, f) + defer srv.Close() + c := quietSentinelClient(t, srv, true) + opts := trustedSentinelOpts() + opts.TrustedAuthorsBlock = true + + res, err := c.SweepSentinel(context.Background(), opts) + if err != nil { + t.Fatalf("sweep: %v", err) + } + if len(res.Flagged) != 1 || len(res.Errors) != 0 { + t.Fatalf("res=%+v", res) + } + if len(f.comments[32]) != 1 || !strings.Contains(f.comments[32][0], sentinelAlertHeading) || prstatus.IsStatusComment(f.comments[32][0]) { + t.Fatalf("security alert must be its own comment, not a card: %v", f.comments[32]) + } + if len(f.labels[32]) != 1 { + t.Fatalf("labels=%v", f.labels[32]) + } +} + +func TestSentinelNormalModeTrustedNoticeUnchanged(t *testing.T) { + f := &sentinelFixture{ + prs: []map[string]any{sentinelPR(33, "hivecommons-hive[bot]", "norm1")}, + files: sentinelWorkflowFiles(33), + } + srv := newSentinelServer(t, f) + defer srv.Close() + c := quietSentinelClient(t, srv, false) + + res, err := c.SweepSentinel(context.Background(), trustedSentinelOpts()) + if err != nil { + t.Fatalf("sweep: %v", err) + } + if len(res.Notified) != 1 || len(res.Errors) != 0 { + t.Fatalf("res=%+v", res) + } + if len(f.comments[33]) != 1 || !strings.Contains(f.comments[33][0], sentinelNoticeHeading) || prstatus.IsStatusComment(f.comments[33][0]) { + t.Fatalf("normal mode must post the notice comment as before: %v", f.comments[33]) + } +} + +func TestSentinelQuietPriorNoticeCommentEditedInPlace(t *testing.T) { + f := &sentinelFixture{ + prs: []map[string]any{sentinelPR(34, "hivecommons-hive[bot]", "new1")}, + files: sentinelWorkflowFiles(34), + comments: map[int][]string{34: {SentinelMarker + " old1\n" + sentinelNoticeHeading}}, + commentUsers: map[int][]string{34: {sentinelCardBot}}, + } + srv := newSentinelServer(t, f) + defer srv.Close() + c := quietSentinelClient(t, srv, true) + + if _, err := c.SweepSentinel(context.Background(), trustedSentinelOpts()); err != nil { + t.Fatalf("sweep: %v", err) + } + if len(f.comments[34]) != 1 || !strings.Contains(f.comments[34][0], SentinelMarker+" new1") { + t.Fatalf("legacy notice comment should be rewritten in place, no card: %v", f.comments[34]) + } +} + +func TestSentinelFoldsNotice(t *testing.T) { + var nilClient *Client + if nilClient.sentinelFoldsNotice(false) { + t.Fatal("nil client must not fold") + } + c := &Client{} + if c.sentinelFoldsNotice(false) { + t.Fatal("unwired quiet mode must not fold") + } + c.SetNotificationsQuiet(func() bool { return true }) + if !c.sentinelFoldsNotice(false) { + t.Fatal("quiet mode with no prior comment must fold") + } + if c.sentinelFoldsNotice(true) { + t.Fatal("a prior sentinel comment is edited in place, not folded") + } +} + +func TestSentinelStatusSectionShape(t *testing.T) { + paths := []string{"g", "f", "e", "d", "c", "b", "a"} + body := SentinelStatusSection(SentinelDecision{Label: "sentinel-alert"}, "0123456789abcdef", []sentinel.Finding{ + {Rule: sentinel.RuleSensitivePath, Summary: "touches sensitive paths", Paths: paths}, + {Rule: "custom", Summary: "no paths"}, + }) + for _, want := range []string{ + SentinelNoticeCardMarker + " 0123456789abcdef -->", + "(trusted author)", + "Head `" + shortSHA("0123456789abcdef") + "` matched", + "(`a`, `b`, `c`, `d`, `e`, +2 more)", + "- `custom`: no paths\n", + "No `sentinel-alert` label", + "sentinel.trusted_authors_block: true", + } { + if !strings.Contains(body, want) { + t.Errorf("section missing %q:\n%s", want, body) + } + } + if strings.Contains(body, SentinelMarker) { + t.Fatalf("card section must never carry the sentinel comment marker:\n%s", body) + } + if strings.Contains(body, "@") { + t.Fatalf("card section must not mention anyone:\n%s", body) + } + if paths[0] != "g" { + t.Fatal("input paths must not be reordered") + } +} + +func TestSentinelStatusCardErrors(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusInternalServerError) + })) + defer srv.Close() + c := quietSentinelClient(t, srv, true) + err := c.foldSentinelNotice(context.Background(), "o/r", 1, "h", SentinelDecision{Label: "x"}, nil) + if err == nil || !strings.Contains(err.Error(), "folding sentinel notice") { + t.Fatalf("want fold error, got %v", err) + } + // Clearing is best effort: an API failure is logged, never panics. + c.clearSentinelNoticeSection(context.Background(), "o/r", 1) + // Normal mode never touches the card. + c.SetNotificationsQuiet(func() bool { return false }) + c.clearSentinelNoticeSection(context.Background(), "o/r", 1) +} diff --git a/src/pkg/github/sentinel_sweep.go b/src/pkg/github/sentinel_sweep.go index d83985ffe7..ff9959edb5 100644 --- a/src/pkg/github/sentinel_sweep.go +++ b/src/pkg/github/sentinel_sweep.go @@ -780,6 +780,14 @@ func (c *Client) trySentinelPR(ctx context.Context, displayRepo, owner, repo str return event, true, nil } if !posted { + // Informational: nobody has to act, so in quiet mode the notice + // is a status-card section edited in place (#18453). + if c.sentinelFoldsNotice(prior != nil) { + if err := c.foldSentinelNotice(ctx, displayRepo, number, head, decision, findings); err != nil { + return SentinelSweepEvent{}, false, err + } + return event, true, nil + } if err := writeSentinelComment(body, "notice"); err != nil { return SentinelSweepEvent{}, false, err } @@ -794,9 +802,12 @@ func (c *Client) trySentinelPR(ctx context.Context, displayRepo, owner, repo str if err != nil { return SentinelSweepEvent{}, false, fmt.Errorf("adding %s label: %w", label, err) } + // Actionable: the alert always gets its own comment, in every + // notification mode, because only a new comment notifies (#18453). if err := writeSentinelComment(SentinelComment(decision, head, author, findings), "alert"); err != nil { return SentinelSweepEvent{}, false, err } + c.clearSentinelNoticeSection(ctx, displayRepo, number) return event, true, nil }