From 4887f5d0eb7a23ae30f1b8a156c4c05303419bf6 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:04 +0100 Subject: [PATCH 01/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .github/workflows/hypatia-scan.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 703bd34..a895ce4 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -53,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | From ceb2961f4202ad003817f6e36f5766647ed7db6f Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:05 +0100 Subject: [PATCH 02/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- bitfuckit/.github/workflows/hypatia-scan.yml | 190 +++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/bitfuckit/.github/workflows/hypatia-scan.yml b/bitfuckit/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/bitfuckit/.github/workflows/hypatia-scan.yml +++ b/bitfuckit/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From 4756975b9901f095f665fa7da821794138e77215 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:06 +0100 Subject: [PATCH 03/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../must/.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/contractiles/runners/must/.github/workflows/hypatia-scan.yml b/contractiles/runners/must/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/contractiles/runners/must/.github/workflows/hypatia-scan.yml +++ b/contractiles/runners/must/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From b0ce6d5501bdd8e6827e929bd0f09927a17090fd Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:08 +0100 Subject: [PATCH 04/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- gui/.github/workflows/hypatia-scan.yml | 190 +++++++++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/gui/.github/workflows/hypatia-scan.yml b/gui/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/gui/.github/workflows/hypatia-scan.yml +++ b/gui/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From aabd9eba9663fbe4b506b987cf695101e74cfacd Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:09 +0100 Subject: [PATCH 05/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/recon-silly-ation/.github/workflows/hypatia-scan.yml b/recon-silly-ation/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/recon-silly-ation/.github/workflows/hypatia-scan.yml +++ b/recon-silly-ation/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From 6d3ec5a5c73860b38cc66fdb1342b537a2529b2c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:10 +0100 Subject: [PATCH 06/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/rpa-elysium/.github/workflows/hypatia-scan.yml b/rpa-elysium/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/rpa-elysium/.github/workflows/hypatia-scan.yml +++ b/rpa-elysium/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From c57aeea56e6b33832c4023ca87dfecafff4cde70 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:11 +0100 Subject: [PATCH 07/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- scaffoldia/.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/scaffoldia/.github/workflows/hypatia-scan.yml b/scaffoldia/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/scaffoldia/.github/workflows/hypatia-scan.yml +++ b/scaffoldia/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From b042d47eaa397f8e6179172c5ddc071900dfa260 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:13 +0100 Subject: [PATCH 08/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/stateful-artefacts/.github/workflows/hypatia-scan.yml b/stateful-artefacts/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/stateful-artefacts/.github/workflows/hypatia-scan.yml +++ b/stateful-artefacts/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From bc6f35f0489e98f7c02be777c16a735f38b573d6 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:14 +0100 Subject: [PATCH 09/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/tools/dispatcher/.github/workflows/hypatia-scan.yml b/tools/dispatcher/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/tools/dispatcher/.github/workflows/hypatia-scan.yml +++ b/tools/dispatcher/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From 870a0b898675c1e32579d79e3add801419f36b18 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:15 +0100 Subject: [PATCH 10/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- tools/hud/.github/workflows/hypatia-scan.yml | 190 +++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/tools/hud/.github/workflows/hypatia-scan.yml b/tools/hud/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/tools/hud/.github/workflows/hypatia-scan.yml +++ b/tools/hud/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From e57a2d16bd0be8007c8fad05e0254922a2e22f68 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:16 +0100 Subject: [PATCH 11/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/tools/reunify/.github/workflows/hypatia-scan.yml b/tools/reunify/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/tools/reunify/.github/workflows/hypatia-scan.yml +++ b/tools/reunify/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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 From 09b5b33dd2e27eca185b88fcd64e828072f3ae52 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 03:58:18 +0100 Subject: [PATCH 12/12] fix(ci): canonicalise hypatia-scan.yml (templater regeneration source) --- .../.github/workflows/hypatia-scan.yml | 190 ++++++++++++++++-- 1 file changed, 175 insertions(+), 15 deletions(-) diff --git a/tools/rsr-certified/.github/workflows/hypatia-scan.yml b/tools/rsr-certified/.github/workflows/hypatia-scan.yml index 860a2b7..a895ce4 100644 --- a/tools/rsr-certified/.github/workflows/hypatia-scan.yml +++ b/tools/rsr-certified/.github/workflows/hypatia-scan.yml @@ -19,12 +19,20 @@ concurrency: permissions: contents: read - # security-events: read lets the built-in GITHUB_TOKEN query this - # repo's own Dependabot alerts via the Hypatia DependabotAlerts rule - # (DA001-DA004). Without this, `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. - security-events: 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) @@ -45,8 +53,8 @@ jobs: - name: Setup Elixir for Hypatia scanner 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: | @@ -103,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 @@ -174,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: | @@ -200,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