fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#44)

hyperpolymath · claude · web-flow · commit 975f5c32d589 · 2026-05-17T03:44:57.000+01:00
The build step did `cd scanner` / built `hypatia-v2` against a path that
no longer exists in the hypatia repo (mix.exs is at root), so the Hypatia
Neurosymbolic Analysis lane exited 1 every run. The env.HOME and Phase-2
sweeps never normalised this older build-step drift. Replace with the
canonical rsr-template-repo hypatia-scan.yml.

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml
@@ -10,14 +10,33 @@ on:
   schedule:
     - cron: '0 0 * * 0'  # Weekly on Sunday
   workflow_dispatch:
+# Estate guardrail: cancel superseded runs so re-pushes don't pile up
+# queued runs across the estate. Safe here because this workflow only
+# performs read-only checks/lint/test/scan with no publish or mutation.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
-# `read-all` is insufficient: the "Comment on PR with findings" step at
-# the bottom of this workflow posts to the `issues/{n}/comments` endpoint,
-# which requires write access to pull-requests. We keep contents read-only
-# (the workflow only reads the repo tree to scan it) and grant the minimum
-# write scope needed for the PR-comment step.
 permissions:
   contents: read
+  # security-events: write serves two purposes (write implies read):
+  #   1. read — lets the built-in GITHUB_TOKEN query this repo's own
+  #      Dependabot alerts via the Hypatia DependabotAlerts rule
+  #      (DA001-DA004). Without read, `scan_from_path` gets HTTP 403
+  #      and the rule silently returns no findings.
+  #      See 007-lang/audits/audit-dependabot-automation-gap-2026-04-17.md.
+  #   2. write — lets the "Upload SARIF to code scanning" step publish
+  #      Hypatia findings to the Security → Code scanning page so they
+  #      are triaged/deduplicated like CodeQL alerts instead of living
+  #      only in a build artifact nobody is required to look at.
+  #      See hyperpolymath/burble#35 (SARIF integration).
+  # This is a single-job workflow, so job-level scoping would not
+  # narrow the grant further; it stays workflow-level and documented.
+  security-events: write
+  # pull-requests: write lets the advisory "Comment on PR with findings"
+  # step post its summary. Without it the built-in GITHUB_TOKEN gets
+  # "Resource not accessible by integration" and (absent continue-on-error)
+  # hard-fails the scan — exactly what the gate-decoupling design forbids.
   pull-requests: write
 
 jobs:
@@ -27,15 +46,15 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0  # Full history for better pattern analysis
 
       - name: Setup Elixir for Hypatia scanner
-        uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.24.0
+        uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.18.2
         with:
-          elixir-version: '1.19.4'
-          otp-version: '28.3'
+          elixir-version: '1.18'
+          otp-version: '27'
 
       - name: Clone Hypatia
         run: |
@@ -46,22 +65,25 @@ jobs:
       - name: Build Hypatia scanner (if needed)
         run: |
           cd "$HOME/hypatia"
-          if [ ! -f hypatia ] && [ ! -f hypatia-v2 ]; then
-            echo "Building hypatia-v2 scanner..."
+          if [ ! -f hypatia ]; then
+            echo "Building hypatia scanner..."
             mix deps.get
             mix escript.build
           fi
 
       - name: Run Hypatia scan
         id: scan
         env:
-          # Suppress the Dependabot "GITHUB_TOKEN not set" warning.
+          # Pass the built-in Actions token through to Hypatia so the
+          # DependabotAlerts rule can query this repo's own alerts.
+          # For cross-repo scanning (fleet-coordinator scan-supervised),
+          # a PAT with `security_events` scope is required instead.
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           echo "Scanning repository: ${{ github.repository }}"
 
-          # Run scanner
-          HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json
+          # Run scanner (exits non-zero when findings exist — suppress to continue)
+          HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json || true
 
           # Count findings
           FINDING_COUNT=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0)
@@ -89,6 +111,143 @@ jobs:
           path: hypatia-findings.json
           retention-days: 90
 
+      - name: Convert Hypatia findings to SARIF
+        # Always runs (no findings_count guard): an EMPTY SARIF run is
+        # valid and intentional — uploading it clears stale Hypatia
+        # alerts from the code-scanning page when a repo goes clean.
+        # The converter is dependency-free Node (Node ships on
+        # ubuntu-latest; no npm install — estate npm ban respected) and
+        # is hardened against the heterogeneous Hypatia JSON schema:
+        # most findings are {rule_module,severity,type,file,reason,
+        # action}; only some carry an integer `line`; `file` may be
+        # empty or absolute. See lib/hypatia/cli.ex (collect_findings).
+        run: |
+          cat > "$RUNNER_TEMP/hypatia-sarif.cjs" <<'CJS'
+          const fs = require('fs');
+          const path = require('path');
+          const crypto = require('crypto');
+
+          const ws = process.env.GITHUB_WORKSPACE || process.cwd();
+
+          let findings = [];
+          try {
+            const parsed = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
+            if (Array.isArray(parsed)) findings = parsed;
+          } catch (_) {
+            // Scanner unavailable / empty / malformed -> empty SARIF.
+            // Intentionally clears stale alerts rather than erroring.
+            findings = [];
+          }
+
+          // Mirrors Hypatia's own "github" annotation mapping
+          // (lib/hypatia/cli.ex output/2): critical|high -> error,
+          // medium -> warning, everything else -> note.
+          const levelFor = (sev) => {
+            switch (String(sev || '').toLowerCase()) {
+              case 'critical':
+              case 'high': return 'error';
+              case 'medium': return 'warning';
+              default: return 'note';
+            }
+          };
+
+          // SARIF artifactLocation.uri must be a repo-relative POSIX
+          // path. Hypatia may emit absolute paths (scanned under
+          // $GITHUB_WORKSPACE) or "" / "." for repo-level findings.
+          const relUri = (file) => {
+            if (!file) return '.';
+            let f = String(file);
+            if (path.isAbsolute(f)) {
+              const rel = path.relative(ws, f);
+              f = (rel && !rel.startsWith('..')) ? rel : path.basename(f);
+            }
+            f = f.replace(/\\/g, '/').replace(/^\.\//, '');
+            return f || '.';
+          };
+
+          const rules = new Map();
+          const results = findings.map((f) => {
+            const mod = String(f.rule_module || 'hypatia');
+            const type = String(f.type || 'finding');
+            const ruleId = `hypatia/${mod}/${type}`;
+            const level = levelFor(f.severity);
+            if (!rules.has(ruleId)) {
+              rules.set(ruleId, {
+                id: ruleId,
+                name: `${mod}.${type}`,
+                shortDescription: { text: `Hypatia ${mod}: ${type}` },
+                defaultConfiguration: { level }
+              });
+            }
+            const uri = relUri(f.file);
+            const msg = String(f.reason || f.type || 'Hypatia finding');
+            const startLine =
+              Number.isInteger(f.line) && f.line > 0 ? f.line : 1;
+            // Stable cross-run fingerprint for dedupe (no line, so a
+            // moved finding in the same file/rule stays one alert).
+            const fp = crypto
+              .createHash('sha256')
+              .update([ruleId, uri, type, msg].join('|'))
+              .digest('hex');
+            return {
+              ruleId,
+              level,
+              message: { text: msg },
+              locations: [
+                {
+                  physicalLocation: {
+                    artifactLocation: { uri },
+                    region: { startLine }
+                  }
+                }
+              ],
+              partialFingerprints: { 'hypatiaFindingHash/v1': fp }
+            };
+          });
+
+          const sarif = {
+            $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+            version: '2.1.0',
+            runs: [
+              {
+                tool: {
+                  driver: {
+                    name: 'Hypatia',
+                    informationUri: 'https://github.com/hyperpolymath/hypatia',
+                    rules: Array.from(rules.values())
+                  }
+                },
+                results
+              }
+            ]
+          };
+
+          fs.writeFileSync('hypatia.sarif', JSON.stringify(sarif, null, 2));
+          console.log(`hypatia.sarif written: ${results.length} result(s).`);
+          CJS
+          node "$RUNNER_TEMP/hypatia-sarif.cjs"
+
+      - name: Upload SARIF to GitHub code scanning
+        # Fork PRs get a read-only GITHUB_TOKEN, so security-events:write
+        # is unavailable and upload-sarif cannot publish — skip there
+        # rather than hard-fail (the push/schedule run on the default
+        # branch is the authoritative upload). Same-repo PRs and pushes
+        # do upload. This step is deliberately NOT continue-on-error:
+        # if the security-surface integration breaks we want a loud red,
+        # not a silently-ungated scanner (the exact failure mode #35
+        # exists to end). The empty-SARIF "clear stale alerts" path is
+        # handled in the converter above and does not error here.
+        if: >-
+          always() &&
+          (github.event_name != 'pull_request' ||
+           github.event.pull_request.head.repo.fork != true)
+        uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.28.1
+        with:
+          sarif_file: hypatia.sarif
+          # Distinct category so Hypatia results coexist with CodeQL's
+          # (codeql.yml) instead of overwriting them on the same surface.
+          category: hypatia
+
       - name: Submit findings to gitbot-fleet (Phase 2)
         if: steps.scan.outputs.findings_count > 0
         # Phase 2 is the collaborative LEARNING side-channel ("bots share
@@ -160,11 +319,21 @@ jobs:
 
       - name: Check for critical issues
         if: steps.scan.outputs.critical > 0
+        # GATING POLICY (explicit, by design — not an oversight):
+        # Hypatia is ADVISORY here. Critical findings are surfaced
+        # (step annotation + SARIF alert on the code-scanning page +
+        # PR comment) but do NOT fail this check. Enforcement is
+        # delegated to the code-scanning surface: tighten by adding a
+        # branch-protection "required" status on the `hypatia` SARIF
+        # category, not by reintroducing an `exit 1` here. This keeps
+        # the gate decision in one auditable place (hypatia#213 gate
+        # decoupling) and lets a repo opt into fail-on-critical without
+        # editing this canonical workflow. To change the policy, change
+        # branch protection — deliberately no commented-out `exit 1`.
         run: |
-          echo "⚠️  Critical security issues found!"
-          echo "Review hypatia-findings.json for details"
-          # Don't fail the build yet - just warn
-          # exit 1
+          echo "::warning::Hypatia found critical security issue(s) — advisory."
+          echo "See the Security → Code scanning page (category: hypatia)"
+          echo "and the hypatia-findings.json artifact for details."
 
       - name: Generate scan report
         run: |
@@ -186,9 +355,14 @@ jobs:
 
           ## Next Steps
 
-          1. Review findings in the artifact: hypatia-findings.json
-          2. Auto-fixable issues will be addressed by robot-repo-automaton (Phase 3)
-          3. Manual review required for complex issues
+          1. Triage findings on the **Security → Code scanning** page
+             (SARIF category \`hypatia\`) — dismiss/track them there like
+             CodeQL alerts.
+          2. The full finding set is also attached as the
+             \`hypatia-findings.json\` build artifact for offline review.
+          3. Findings are **advisory** today (surfaced, not gated); the
+             gating policy is documented in the workflow's "Check for
+             critical issues" step.
 
           ## Learning
 
@@ -202,85 +376,39 @@ jobs:
 
       - name: Comment on PR with findings
         if: github.event_name == 'pull_request' && steps.scan.outputs.findings_count > 0
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        # Advisory only — posting findings as a PR comment must never gate
+        # the scan (hypatia#213 gate decoupling). Belt-and-braces alongside
+        # the pull-requests: write permission above: a token/API hiccup or
+        # a fork PR (read-only token) skips the comment, not the check.
+        continue-on-error: true
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v7
         with:
           script: |
-            // Diff-scoped + baseline-aware PR comment.
-            //
-            // The scanner reports the WHOLE repo on every run, so a raw
-            // comment nagged every PR with ~44 pre-existing findings it did
-            // not introduce. We instead surface only findings that are BOTH
-            // (a) in a file this PR changed and (b) not in the committed
-            // baseline. If there is nothing actionable for this PR we post
-            // no comment at all (the full set stays in the uploaded
-            // artifact + step summary). See
-            // docs/wiki/internals/checker-allocation-investigation.md.
             const fs = require('fs');
             const findings = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
 
-            const ws = (process.env.GITHUB_WORKSPACE || '').replace(/\/+$/, '');
-            const relPath = (p) => {
-              let r = String(p || '');
-              if (ws && r.startsWith(ws + '/')) r = r.slice(ws.length + 1);
-              return r;
-            };
-            const fp = (f) => `${f.rule_module}/${f.type}:${relPath(f.file)}`;
-
-            let baseline = new Set();
-            try {
-              const b = JSON.parse(fs.readFileSync('.hypatia-baseline.json', 'utf8'));
-              baseline = new Set(b.fingerprints || []);
-            } catch (e) { /* no baseline yet */ }
+            const critical = findings.filter(f => f.severity === 'critical').length;
+            const high = findings.filter(f => f.severity === 'high').length;
 
-            // Files changed by this PR (paginated).
-            const files = await github.paginate(github.rest.pulls.listFiles, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: context.issue.number,
-              per_page: 100,
-            });
-            const changed = new Set(files.map(f => f.filename));
-
-            const baselined = findings.filter(f => baseline.has(fp(f)));
-            const relevant = findings.filter(
-              f => changed.has(relPath(f.file)) && !baseline.has(fp(f))
-            );
-
-            const summary =
-              `Hypatia: ${findings.length} repo-wide finding(s); ` +
-              `${relevant.length} in files this PR changed; ` +
-              `${baselined.length} baselined; ` +
-              `full list in the hypatia-findings artifact.`;
-            core.notice(summary);
-
-            // Nothing this PR can act on -> stay silent.
-            if (relevant.length === 0) return;
-
-            const critical = relevant.filter(f => f.severity === 'critical').length;
-            const high = relevant.filter(f => f.severity === 'high').length;
-
-            let comment = `## 🔍 Hypatia Security Scan — findings in this PR's changed files\n\n`;
-            comment += `**${relevant.length}** finding(s) in files this PR modifies `;
-            comment += `(of ${findings.length} repo-wide; ${baselined.length} baselined, not shown).\n\n`;
+            let comment = `## 🔍 Hypatia Security Scan\n\n`;
+            comment += `**Findings:** ${findings.length} issues detected\n\n`;
             comment += `| Severity | Count |\n|----------|-------|\n`;
             comment += `| 🔴 Critical | ${critical} |\n`;
             comment += `| 🟠 High | ${high} |\n`;
-            comment += `| 🟡 Medium | ${relevant.length - critical - high} |\n\n`;
+            comment += `| 🟡 Medium | ${findings.length - critical - high} |\n\n`;
 
             if (critical > 0) {
-              comment += `⚠️ **Action Required:** critical finding(s) in code this PR touches.\n\n`;
+              comment += `⚠️ **Action Required:** Critical security issues found!\n\n`;
             }
 
-            comment += `<details><summary>View findings (this PR's files only)</summary>\n\n`;
-            comment += `\`\`\`json\n${JSON.stringify(relevant.slice(0, 10), null, 2)}\n\`\`\`\n`;
+            comment += `<details><summary>View findings</summary>\n\n`;
+            comment += `\`\`\`json\n${JSON.stringify(findings.slice(0, 10), null, 2)}\n\`\`\`\n`;
             comment += `</details>\n\n`;
-            comment += `_Pre-existing repo-wide findings are triaged via the Hypatia backlog `;
-            comment += `issue and suppressed here by \`.hypatia-baseline.json\` / \`.hypatia-ignore\`._\n\n`;
             comment += `*Powered by Hypatia Neurosymbolic CI/CD Intelligence*`;
 
-            await github.rest.issues.createComment({
+            github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: context.issue.number,
               body: comment
-            });
+            });
