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/added-16237-sentinel-paths-in-decision.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The *Let hive decide* dialog, the tracker payload (`sentinel_details`), `/api/sentinel` (`findings`) and the hive's "reviewed, intended" decision comment now name the files and the sentinel rule that fired — bounded to 10 paths per finding with a "+N more" count — instead of only "changes N sensitive path(s)" ([#16237](https://github.com/hivecommons/hive/issues/16237)).
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,8 @@ A pull request the suspicious-activity sentinel flagged — it wears the `sentin

The tooltip reads "Sentinel flagged security-relevant changes at `<sha7>`: `<reason>`" (a generic description stands in when the bundle has no reason). An issue carried by one flagged PR shows the lane text too, and a nested PR sub-row shows its own. The *Decide…* dialogs for a flagged PR open with a ⚠ line per flagged PR naming the sentinel reason, and *Approve* is styled as a dangerous action.

The payload also carries `sentinel_details`: one entry per finding with its `rule` (`sensitive_path`, `permission_escalation`, `ci_gate_weakening`, …), `summary`, the flagged `paths` (sorted, at most 10 per finding) and `more_paths` for any cut. The *Let hive decide* dialog's ▼ Details and the ⚠ chip tooltip list them under the sentinel line — `· sensitive_path: .github/workflows/release.yml (+N more)` — so the person can see *which* files tripped the sentinel, not just how many; `/api/sentinel` serves the same `findings` per row, and the hive's "reviewed, intended" decision comment on a trusted author's flagged PR names the same files after the reason. The findings come from the head's review evidence bundle or the sweep's own record; nothing is re-fetched from GitHub.

A person's *Approve* through that dialog **is** the human review the alert asked for: it removes the `sentinel-alert` label when present and records a `sentinel_acknowledged` human action keyed to the head in the review evidence bundle, so a bundle-only alert (findings but no label — hivecommons/crux#30) clears too; the payload then reads `sentinel_alert: false` with `sentinel_reason` suffixed `— acknowledged by @login`, the findings stay on record, and a new head starts over.

The delegated *Let hive decide* path never clears it. Hovering the lit chevron of a parked row names the parking stage itself (`Needs human decision`), not the 080 column it rides on; `Next move` follows the real stage (human at 085, hive at 080). Lane text and chip update in place on refresh (keyed reconcile, no flash).
Expand Down
23 changes: 22 additions & 1 deletion src/pkg/dashboard/api_repo_item_decide_delegated.go
Original file line number Diff line number Diff line change
Expand Up @@ -661,6 +661,7 @@ func (s *Server) gatherDelegatedInput(ctx context.Context, repoFull string, numb
}
in.CIGreen, in.CIPending = ci.green, ci.pending
s.gatherDelegatedRecordedPark(repoFull, number, pr.GetHead().GetSHA(), &in)
in.SentinelReason = s.delegatedSentinelReason(repoFull, number, pr.GetHead().GetSHA(), req.SentinelReason)
if files, _, err := api.PullRequests.ListFiles(ctx, owner, repoName, number, &gh.ListOptions{PerPage: delegatedDecisionGatherLimit}); err == nil && len(files) > 0 {
in.LowRiskPaths = true
for _, f := range files {
Expand All @@ -687,7 +688,9 @@ func (s *Server) gatherDelegatedInput(ctx context.Context, repoFull string, numb
in.SentinelAlert = true
}
}
in.SentinelReason = strings.TrimSpace(req.SentinelReason)
if in.SentinelReason == "" {
in.SentinelReason = strings.TrimSpace(req.SentinelReason)
}
lowerReason := strings.ToLower(reason)
if in.Kind == delegatedecision.KindPR && in.HiveAuthored && s.hiveSupersedingAutoMerge() {
in.HiveSuperseding = ghpkg.HiveSupersedingPR(true, in.Body)
Expand Down Expand Up @@ -730,6 +733,24 @@ func (s *Server) delegatedAdoptionGraceElapsed(repoFull string, number int) bool
return rec.AdoptionBlocked(rec.NudgeHead) != ""
}

// delegatedSentinelReason is the sentinel reason the decider and its comment
// carry: the tracker row's own words ("changes 1 sensitive path(s)") followed
// by the paths the hive recorded for head, so the "reviewed, intended"
// rationale names the files, as the operator asked. The row's words stand
// alone when the hive holds no findings for that head.
func (s *Server) delegatedSentinelReason(repoFull string, number int, head, rowReason string) string {
reason := strings.TrimSpace(rowReason)
text := sentinelDetailsText(s.sentinelDetailsForHead(repoFull, number, head))
switch {
case text == "":
return reason
case reason == "":
return text
default:
return reason + " — " + text
}
}

// delegatedHeadCIState is what the head's checks say: green (every
// gating check passed), pending (some still running, none failed), or
// neither (a check failed, or none ever reported).
Expand Down
40 changes: 28 additions & 12 deletions src/pkg/dashboard/api_writeback.go
Original file line number Diff line number Diff line change
Expand Up @@ -88,17 +88,20 @@ func (s *Server) handleWritebackSuppressed(w http.ResponseWriter, r *http.Reques
// SentinelFinding is one sentinel evaluation the dashboard keeps for the
// Security tab and /api/sentinel, whether or not it reached GitHub.
type SentinelFinding struct {
At time.Time `json:"at"`
Repo string `json:"repo"`
Number int `json:"number"`
Author string `json:"author"`
Title string `json:"title,omitempty"`
HeadSHA string `json:"head_sha,omitempty"`
Rules []string `json:"rules"`
Blocked bool `json:"blocked"`
TrustedReason string `json:"trusted_reason,omitempty"`
Suppressed bool `json:"suppressed"`
SuppressedReason string `json:"suppressed_reason,omitempty"`
At time.Time `json:"at"`
Repo string `json:"repo"`
Number int `json:"number"`
Author string `json:"author"`
Title string `json:"title,omitempty"`
HeadSHA string `json:"head_sha,omitempty"`
Rules []string `json:"rules"`
// Findings names each rule's flagged paths (bounded per finding), so
// the Security tab and the decision dialog can say which files.
Findings []SentinelDetail `json:"findings,omitempty"`
Blocked bool `json:"blocked"`
TrustedReason string `json:"trusted_reason,omitempty"`
Suppressed bool `json:"suppressed"`
SuppressedReason string `json:"suppressed_reason,omitempty"`
}

const maxSentinelFindings = 1000
Expand All @@ -113,7 +116,7 @@ func (f *sentinelFindings) record(ev github.SentinelSweepEvent, now time.Time) {
f.mu.Lock()
defer f.mu.Unlock()
item := SentinelFinding{At: now.UTC(), Repo: ev.Repo, Number: ev.Number, Author: ev.Author, Title: ev.Title, HeadSHA: ev.HeadSHA,
Rules: ev.Rules(), Blocked: ev.Blocked, TrustedReason: ev.TrustedReason, Suppressed: ev.Suppressed, SuppressedReason: ev.SuppressedReason}
Rules: ev.Rules(), Findings: sentinelDetailsFromSweep(ev), Blocked: ev.Blocked, TrustedReason: ev.TrustedReason, Suppressed: ev.Suppressed, SuppressedReason: ev.SuppressedReason}
// One row per repo#number@head: a re-evaluation of the same head
// replaces the earlier row rather than stacking.
for i := range f.items {
Expand All @@ -137,6 +140,19 @@ func (f *sentinelFindings) list() []SentinelFinding {
return out
}

// detailsFor returns the findings recorded for repo#number at head, or nil.
func (f *sentinelFindings) detailsFor(repo string, number int, head string) []SentinelDetail {
f.mu.Lock()
defer f.mu.Unlock()
for i := range f.items {
it := &f.items[i]
if it.Number == number && strings.EqualFold(it.Repo, repo) && strings.EqualFold(it.HeadSHA, head) {
return append([]SentinelDetail(nil), it.Findings...)
}
}
return nil
}

// RecordSentinelFinding is the sentinel sweep's Audit hook target: every
// finding, written or suppressed, lands here for the Security tab.
func (s *Server) RecordSentinelFinding(ev github.SentinelSweepEvent) {
Expand Down
141 changes: 141 additions & 0 deletions src/pkg/dashboard/sentinel_details.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
package dashboard

import (
"fmt"
"sort"
"strings"

"github.com/hivecommons/hive/pkg/evidence"
"github.com/hivecommons/hive/pkg/github"
)

// SentinelDetail is one sentinel finding as the decision dialog and the
// hive's comment name it: the rule that fired, its one-line summary and the
// files it fired on. "Changes 1 sensitive path(s)" alone left the operator
// unable to decide ("knowing what the sensitive path(s) (and files) are in
// this alert dialog would really help me make a decision"), so the rows
// carry the paths themselves, bounded to SentinelDetailMaxPaths per finding
// with MorePaths counting the rest.
type SentinelDetail struct {
Rule string `json:"rule"`
Summary string `json:"summary,omitempty"`
Paths []string `json:"paths,omitempty"`
// MorePaths is how many flagged paths were cut after the first
// SentinelDetailMaxPaths; 0 when every path is listed.
MorePaths int `json:"more_paths,omitempty"`
}

// SentinelDetailMaxPaths bounds the paths one finding lists in a tracker
// row, the dialog and the hive's comment.
const SentinelDetailMaxPaths = 10

// sentinelDetailOf builds the bounded detail for one finding; paths are
// sorted so the list is stable across snapshots.
func sentinelDetailOf(rule, summary string, paths []string) SentinelDetail {
d := SentinelDetail{Rule: strings.TrimSpace(rule), Summary: strings.TrimSpace(summary)}
sorted := make([]string, 0, len(paths))
for _, p := range paths {
if p = strings.TrimSpace(p); p != "" {
sorted = append(sorted, p)
}
}
sort.Strings(sorted)
if len(sorted) > SentinelDetailMaxPaths {
d.MorePaths = len(sorted) - SentinelDetailMaxPaths
sorted = sorted[:SentinelDetailMaxPaths]
}
if len(sorted) > 0 {
d.Paths = sorted
}
return d
}

// sentinelDetailsFromEvidence converts a review evidence bundle's sentinel
// findings for the tracker payload.
func sentinelDetailsFromEvidence(findings []evidence.SentinelFinding) []SentinelDetail {
if len(findings) == 0 {
return nil
}
out := make([]SentinelDetail, 0, len(findings))
for _, f := range findings {
out = append(out, sentinelDetailOf(f.Rule, f.Summary, f.Paths))
}
return out
}

// sentinelDetailsFromSweep converts the sweep event's own findings for the
// /api/sentinel ring (field access only: the dashboard does not import the
// sentinel package — see TestDashboardInternalImportCountRatchet).
func sentinelDetailsFromSweep(ev github.SentinelSweepEvent) []SentinelDetail {
if len(ev.Findings) == 0 {
return nil
}
out := make([]SentinelDetail, 0, len(ev.Findings))
for _, f := range ev.Findings {
out = append(out, sentinelDetailOf(f.Rule, f.Summary, f.Paths))
}
return out
}

// sentinelDetailsText renders the details on one line for a comment or a
// tooltip: "sensitive_path: .github/workflows/ci.yml, OWNERS (+3 more);
// ci_gate_weakening: .github/workflows/ci.yml". Findings without paths name
// the rule and its summary. Empty when there is nothing to say.
func sentinelDetailsText(details []SentinelDetail) string {
parts := make([]string, 0, len(details))
for _, d := range details {
label := d.Rule
if label == "" {
label = d.Summary
}
if label == "" {
continue
}
if len(d.Paths) == 0 {
if d.Rule != "" && d.Summary != "" {
label += " (" + d.Summary + ")"
}
parts = append(parts, label)
continue
}
line := label + ": " + strings.Join(d.Paths, ", ")
if d.MorePaths > 0 {
line += fmt.Sprintf(" (+%d more)", d.MorePaths)
}
parts = append(parts, line)
}
return strings.Join(parts, "; ")
}

// sentinelDetailsFor returns the sentinel findings the hive holds for
// repo#number at head without touching GitHub: the /api/sentinel ring the
// sweep's audit hook fills. Nil when the sweep never saw that head.
func (s *Server) sentinelDetailsFor(repo string, number int, head string) []SentinelDetail {
if s == nil || number <= 0 || strings.TrimSpace(head) == "" {
return nil
}
return s.sentinelFindings.detailsFor(repo, number, head)
}

// sentinelDetailsForHead is sentinelDetailsFor with the on-disk review
// evidence bundle as the second source, for a request path that has not
// loaded the bundle itself (the delegated decision). The ring is in-memory
// and empties on restart; the bundle survives it.
func (s *Server) sentinelDetailsForHead(repo string, number int, head string) []SentinelDetail {
head = strings.TrimSpace(head)
if details := s.sentinelDetailsFor(repo, number, head); len(details) > 0 {
return details
}
if s == nil || number <= 0 || head == "" {
return nil
}
verifier, err := s.reviewEvidenceVerifier()
if err != nil {
return nil
}
b, err := github.LoadVerifiedReviewEvidence(github.ReviewEvidencePath("", repo, number, head), verifier)
if err != nil || b == nil {
return nil
}
return sentinelDetailsFromEvidence(b.Sentinel)
}
129 changes: 129 additions & 0 deletions src/pkg/dashboard/sentinel_details_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
package dashboard

import (
"encoding/json"
"fmt"
"path/filepath"
"reflect"
"strings"
"testing"

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

// TestSentinelDetailBoundsAndText: a finding's paths are sorted, bounded
// to SentinelDetailMaxPaths with the rest counted, and rendered on one line
// per rule for the hive's comment.
func TestSentinelDetailBoundsAndText(t *testing.T) {
var many []string
for i := 0; i < SentinelDetailMaxPaths+3; i++ {
many = append(many, fmt.Sprintf("p/%02d.yml", SentinelDetailMaxPaths+3-i))
}
d := sentinelDetailOf(sentinel.RuleSensitivePath, fmt.Sprintf("changes %d sensitive path(s)", len(many)), many)
if len(d.Paths) != SentinelDetailMaxPaths || d.MorePaths != 3 {
t.Fatalf("bound: %d paths, %d more", len(d.Paths), d.MorePaths)
}
if d.Paths[0] != "p/01.yml" || d.Paths[SentinelDetailMaxPaths-1] != fmt.Sprintf("p/%02d.yml", SentinelDetailMaxPaths) {
t.Fatalf("paths not sorted/bounded: %v", d.Paths)
}
if got := sentinelDetailsText([]SentinelDetail{d}); !strings.HasPrefix(got, "sensitive_path: p/01.yml, p/02.yml") || !strings.HasSuffix(got, " (+3 more)") {
t.Fatalf("text = %q", got)
}

two := sentinelDetailsFromSweep(github.SentinelSweepEvent{Findings: []sentinel.Finding{
{Rule: sentinel.RuleSensitivePath, Summary: "changes 2 sensitive path(s)", Paths: []string{"OWNERS", ".github/workflows/ci.yml"}},
{Rule: sentinel.RulePermissionEscalation, Summary: "widens workflow permissions"},
}})
want := "sensitive_path: .github/workflows/ci.yml, OWNERS; permission_escalation (widens workflow permissions)"
if got := sentinelDetailsText(two); got != want {
t.Fatalf("text = %q, want %q", got, want)
}
if sentinelDetailsText(nil) != "" || sentinelDetailsFromSweep(github.SentinelSweepEvent{}) != nil || sentinelDetailsFromEvidence(nil) != nil {
t.Fatal("empty input must render nothing")
}
}

// TestSentinelRingCarriesPathsForDecision: the sweep's audit hook stores
// each finding's paths; /api/sentinel serves them and the decision path
// reads them back by repo#number@head without touching GitHub.
func TestSentinelRingCarriesPathsForDecision(t *testing.T) {
s := covApiServer(t)
ev := github.SentinelSweepEvent{Repo: "acme/console", Number: 16230, Author: "m", HeadSHA: "4396f46abc", Blocked: true, Findings: []sentinel.Finding{
{Rule: sentinel.RuleSensitivePath, Summary: "changes 1 sensitive path(s)", Paths: []string{".github/workflows/release.yml"}},
}}
s.RecordSentinelFinding(ev)

rec := doGet(s, "/api/sentinel?repo=acme/console")
var payload struct {
Findings []SentinelFinding `json:"findings"`
}
if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil || len(payload.Findings) != 1 {
t.Fatalf("sentinel = %d %s (%v)", rec.Code, rec.Body.String(), err)
}
if got := payload.Findings[0].Findings; len(got) != 1 || got[0].Rule != sentinel.RuleSensitivePath || !reflect.DeepEqual(got[0].Paths, []string{".github/workflows/release.yml"}) {
t.Fatalf("api findings = %+v", got)
}

if got := s.sentinelDetailsFor("ACME/console", 16230, "4396F46ABC"); len(got) != 1 || got[0].Paths[0] != ".github/workflows/release.yml" {
t.Fatalf("detailsFor = %+v", got)
}
if got := s.sentinelDetailsFor("acme/console", 16230, "other"); got != nil {
t.Fatalf("other head = %+v", got)
}
// The delegated decision's comment names the files after the row's words.
want := "changes 1 sensitive path(s) — sensitive_path: .github/workflows/release.yml"
if got := s.delegatedSentinelReason("acme/console", 16230, "4396f46abc", "changes 1 sensitive path(s)"); got != want {
t.Fatalf("reason = %q, want %q", got, want)
}
if got := s.delegatedSentinelReason("acme/console", 16230, "4396f46abc", ""); got != "sensitive_path: .github/workflows/release.yml" {
t.Fatalf("reason without row words = %q", got)
}
if got := s.delegatedSentinelReason("acme/console", 1, "nohead", "changes 1 sensitive path(s)"); got != "changes 1 sensitive path(s)" {
t.Fatalf("unknown head keeps the row's words: %q", got)
}
}

// TestStageTrackerSentinelDetailsFromBundleOrRing: the tracker row's
// sentinel_details come from the verified evidence bundle for the head,
// or from the sweep's ring when no bundle was written, so the decision
// dialog can name the files either way.
func TestStageTrackerSentinelDetailsFromBundleOrRing(t *testing.T) {
prev := github.ReviewEvidenceRoot
root := filepath.Join(t.TempDir(), "evidence")
github.ReviewEvidenceRoot = root
t.Cleanup(func() { github.ReviewEvidenceRoot = prev })
s := newTestServer()
verifier := &github.ReviewEvidenceVerifier{}
const head = "4396f46aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
writeSentinelBundle(t, root, "acme/console", 501, head, []evidence.SentinelFinding{
{Rule: "sensitive_path", Summary: "changes 2 sensitive path(s)", Paths: []string{"OWNERS", ".github/workflows/ci.yml"}},
})
_, _, _, details := s.stageTrackerSentinel(verifier, "acme/console", 501, head, []string{config.DefaultSentinelLabel})
if len(details) != 1 || !reflect.DeepEqual(details[0].Paths, []string{".github/workflows/ci.yml", "OWNERS"}) || details[0].Rule != "sensitive_path" {
t.Fatalf("bundle details = %+v", details)
}
if got := s.sentinelDetailsForHead("acme/console", 501, head); !reflect.DeepEqual(got, details) {
t.Fatalf("detailsForHead via bundle = %+v, want %+v", got, details)
}

s.RecordSentinelFinding(github.SentinelSweepEvent{Repo: "acme/console", Number: 502, HeadSHA: head, Blocked: true, Findings: []sentinel.Finding{
{Rule: sentinel.RuleCIGateWeakening, Summary: "softens CI gates", Paths: []string{".github/workflows/ci.yml"}},
}})
_, n, reason, details := s.stageTrackerSentinel(verifier, "acme/console", 502, head, []string{config.DefaultSentinelLabel})
if n != 0 || reason != "" || len(details) != 1 || details[0].Rule != sentinel.RuleCIGateWeakening {
t.Fatalf("ring fallback = %d %q %+v", n, reason, details)
}
if _, _, _, details := s.stageTrackerSentinel(verifier, "acme/console", 503, head, nil); details != nil {
t.Fatalf("unknown PR = %+v", details)
}

var it StageTrackerItem
it.SentinelDetails = details
raw, _ := json.Marshal(it)
if !strings.Contains(string(raw), `"sentinel_details":[{"rule":"ci_gate_weakening","summary":"softens CI gates","paths":[".github/workflows/ci.yml"]}]`) {
t.Fatalf("payload = %s", raw)
}
}
Loading
Loading