Skip to content

Commit 02ab76b

Browse files
claudeclaude
committed
ci(hypatia): adopt standards hypatia-scan-reusable wrapper
Replace the standalone ~300-line Hypatia scanner with a thin wrapper around hyperpolymath/standards hypatia-scan-reusable.yml, matching governance.yml and scorecard.yml. The reusable is a faithful equivalent: Elixir build, scan, SARIF convert + upload under category `hypatia`, gitbot-fleet Phase 2 submission, advisory critical check, and PR comment. - Pinned to the estate-canonical standards commit 861b5e9 (same as governance.yml / scorecard.yml) so the estate moves in lockstep. - secrets: inherit passes GITHUB_TOKEN + HYPATIA_DISPATCH_PAT through; the PAT is required by the gitbot-fleet Phase 2 learning submission (non-fatal). - Preserves triggers, the concurrency guardrail, the MPL-2.0 header, and the contents:read / security-events:write / pull-requests:write grant (the caller is the ceiling for the reusable's GITHUB_TOKEN). - Hypatia stays advisory (hypatia#213): critical findings surface on the code-scanning page but do not fail the check. Also corrects the file's header comment, which already claimed to be a thin wrapper while still carrying the full inline scanner. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AHygjxRyU3WwmXEhA9KF5L
1 parent ee5a618 commit 02ab76b

1 file changed

Lines changed: 19 additions & 295 deletions

File tree

‎.github/workflows/hypatia-scan.yml‎

Lines changed: 19 additions & 295 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,16 @@
11
# // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
22
# SPDX-License-Identifier: MPL-2.0
3-
# Thin wrapper around hyperpolymath/standards hypatia-scan-reusable.yml.
4-
# See standards#191 for the reusable's purpose and design.
5-
3+
# hypatia-scan.yml — thin wrapper calling the shared Hypatia neurosymbolic scan
4+
# in hyperpolymath/standards (hypatia-scan-reusable.yml) instead of carrying the
5+
# per-repo copy. Pinned to the same standards commit as governance.yml and
6+
# scorecard.yml so the estate moves in lockstep. See standards#191 for the
7+
# reusable's purpose and design.
8+
#
9+
# secrets: inherit passes GITHUB_TOKEN and HYPATIA_DISPATCH_PAT through to the
10+
# reusable — the latter is needed by the gitbot-fleet Phase 2 learning
11+
# submission (best-effort / non-fatal). The reusable keeps Hypatia advisory:
12+
# critical findings surface on the code-scanning page (category: hypatia) but
13+
# do not fail the check; tighten via branch protection, not here (hypatia#213).
614
name: Hypatia Security Scan
715
on:
816
push:
@@ -17,301 +25,17 @@ on:
1725
concurrency:
1826
group: ${{ github.workflow }}-${{ github.ref }}
1927
cancel-in-progress: true
28+
29+
# Caller is the ceiling for the reusable's GITHUB_TOKEN; the single job below
30+
# inherits these. The reusable needs:
31+
# security-events: write — upload SARIF + read Dependabot alerts
32+
# pull-requests: write — post the findings comment on PRs
33+
# contents: read — checkout
2034
permissions:
2135
contents: read
2236
security-events: write
2337
pull-requests: write
2438
jobs:
2539
scan:
26-
name: Hypatia Neurosymbolic Analysis
27-
runs-on: ubuntu-latest
28-
timeout-minutes: 15
29-
steps:
30-
- name: Checkout repository
31-
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
32-
with:
33-
fetch-depth: 0 # Full history for better pattern analysis
34-
- name: Setup Elixir for Hypatia scanner
35-
uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.18.2
36-
with:
37-
elixir-version: '1.18'
38-
otp-version: '27'
39-
- name: Clone Hypatia
40-
run: |
41-
if [ ! -d "$HOME/hypatia" ]; then
42-
git clone https://github.com/hyperpolymath/hypatia.git "$HOME/hypatia"
43-
fi
44-
- name: Build Hypatia scanner (if needed)
45-
run: |
46-
cd "$HOME/hypatia"
47-
if [ ! -f hypatia ]; then
48-
echo "Building hypatia scanner..."
49-
mix deps.get
50-
mix escript.build
51-
fi
52-
- name: Run Hypatia scan
53-
id: scan
54-
env:
55-
# Pass the built-in Actions token through to Hypatia so the
56-
# DependabotAlerts rule can query this repo's own alerts.
57-
# For cross-repo scanning (fleet-coordinator scan-supervised),
58-
# a PAT with `security_events` scope is required instead.
59-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
60-
run: |
61-
echo "Scanning repository: ${{ github.repository }}"
62-
63-
# Run scanner (exits non-zero when findings exist — suppress to continue)
64-
HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json || true
65-
66-
# Count findings
67-
FINDING_COUNT=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0)
68-
echo "findings_count=$FINDING_COUNT" >> $GITHUB_OUTPUT
69-
70-
# Extract severity counts
71-
CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json)
72-
HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json)
73-
MEDIUM=$(jq '[.[] | select(.severity == "medium")] | length' hypatia-findings.json)
74-
75-
echo "critical=$CRITICAL" >> $GITHUB_OUTPUT
76-
echo "high=$HIGH" >> $GITHUB_OUTPUT
77-
echo "medium=$MEDIUM" >> $GITHUB_OUTPUT
78-
79-
echo "## Hypatia Scan Results" >> $GITHUB_STEP_SUMMARY
80-
echo "- Total findings: $FINDING_COUNT" >> $GITHUB_STEP_SUMMARY
81-
echo "- Critical: $CRITICAL" >> $GITHUB_STEP_SUMMARY
82-
echo "- High: $HIGH" >> $GITHUB_STEP_SUMMARY
83-
echo "- Medium: $MEDIUM" >> $GITHUB_STEP_SUMMARY
84-
- name: Upload findings artifact
85-
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
86-
with:
87-
name: hypatia-findings
88-
path: hypatia-findings.json
89-
retention-days: 90
90-
- name: Convert Hypatia findings to SARIF
91-
# Always runs (no findings_count guard): an EMPTY SARIF run is
92-
# valid and intentional — uploading it clears stale Hypatia
93-
# alerts from the code-scanning page when a repo goes clean.
94-
# The converter is dependency-free Node (Node ships on
95-
# ubuntu-latest; no npm install — estate npm ban respected) and
96-
# is hardened against the heterogeneous Hypatia JSON schema:
97-
# most findings are {rule_module,severity,type,file,reason,
98-
# action}; only some carry an integer `line`; `file` may be
99-
# empty or absolute. See lib/hypatia/cli.ex (collect_findings).
100-
run: |
101-
cat > "$RUNNER_TEMP/hypatia-sarif.cjs" <<'CJS'
102-
const fs = require('fs');
103-
const path = require('path');
104-
const crypto = require('crypto');
105-
106-
const ws = process.env.GITHUB_WORKSPACE || process.cwd();
107-
108-
let findings = [];
109-
try {
110-
const parsed = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
111-
if (Array.isArray(parsed)) findings = parsed;
112-
} catch (_) {
113-
// Scanner unavailable / empty / malformed -> empty SARIF.
114-
// Intentionally clears stale alerts rather than erroring.
115-
findings = [];
116-
}
117-
118-
// Mirrors Hypatia's own "github" annotation mapping
119-
// (lib/hypatia/cli.ex output/2): critical|high -> error,
120-
// medium -> warning, everything else -> note.
121-
const levelFor = (sev) => {
122-
switch (String(sev || '').toLowerCase()) {
123-
case 'critical':
124-
case 'high': return 'error';
125-
case 'medium': return 'warning';
126-
default: return 'note';
127-
}
128-
};
129-
130-
// SARIF artifactLocation.uri must be a repo-relative POSIX
131-
// path. Hypatia may emit absolute paths (scanned under
132-
// $GITHUB_WORKSPACE) or "" / "." for repo-level findings.
133-
const relUri = (file) => {
134-
if (!file) return '.';
135-
let f = String(file);
136-
if (path.isAbsolute(f)) {
137-
const rel = path.relative(ws, f);
138-
f = (rel && !rel.startsWith('..')) ? rel : path.basename(f);
139-
}
140-
f = f.replace(/\\/g, '/').replace(/^\.\//, '');
141-
return f || '.';
142-
};
143-
144-
const rules = new Map();
145-
const results = findings.map((f) => {
146-
const mod = String(f.rule_module || 'hypatia');
147-
const type = String(f.type || 'finding');
148-
const ruleId = `hypatia/${mod}/${type}`;
149-
const level = levelFor(f.severity);
150-
if (!rules.has(ruleId)) {
151-
rules.set(ruleId, {
152-
id: ruleId,
153-
name: `${mod}.${type}`,
154-
shortDescription: { text: `Hypatia ${mod}: ${type}` },
155-
defaultConfiguration: { level }
156-
});
157-
}
158-
const uri = relUri(f.file);
159-
const msg = String(f.reason || f.type || 'Hypatia finding');
160-
const startLine =
161-
Number.isInteger(f.line) && f.line > 0 ? f.line : 1;
162-
// Stable cross-run fingerprint for dedupe (no line, so a
163-
// moved finding in the same file/rule stays one alert).
164-
const fp = crypto
165-
.createHash('sha256')
166-
.update([ruleId, uri, type, msg].join('|'))
167-
.digest('hex');
168-
return {
169-
ruleId,
170-
level,
171-
message: { text: msg },
172-
locations: [
173-
{
174-
physicalLocation: {
175-
artifactLocation: { uri },
176-
region: { startLine }
177-
}
178-
}
179-
],
180-
partialFingerprints: { 'hypatiaFindingHash/v1': fp }
181-
};
182-
});
183-
184-
const sarif = {
185-
$schema: 'https://json.schemastore.org/sarif-2.1.0.json',
186-
version: '2.1.0',
187-
runs: [
188-
{
189-
tool: {
190-
driver: {
191-
name: 'Hypatia',
192-
informationUri: 'https://github.com/hyperpolymath/hypatia',
193-
rules: Array.from(rules.values())
194-
}
195-
},
196-
results
197-
}
198-
]
199-
};
200-
201-
fs.writeFileSync('hypatia.sarif', JSON.stringify(sarif, null, 2));
202-
console.log(`hypatia.sarif written: ${results.length} result(s).`);
203-
CJS
204-
node "$RUNNER_TEMP/hypatia-sarif.cjs"
205-
- name: Upload SARIF to GitHub code scanning
206-
# Fork PRs get a read-only GITHUB_TOKEN, so security-events:write
207-
# is unavailable and upload-sarif cannot publish — skip there
208-
# rather than hard-fail (the push/schedule run on the default
209-
# branch is the authoritative upload). Same-repo PRs and pushes
210-
# do upload. This step is deliberately NOT continue-on-error:
211-
# if the security-surface integration breaks we want a loud red,
212-
# not a silently-ungated scanner (the exact failure mode #35
213-
# exists to end). The empty-SARIF "clear stale alerts" path is
214-
# handled in the converter above and does not error here.
215-
if: >-
216-
always() && (github.event_name != 'pull_request' ||
217-
218-
219-
220-
221-
222-
github.event.pull_request.head.repo.fork != true)
223-
uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3.28.1
224-
with:
225-
sarif_file: hypatia.sarif
226-
# Distinct category so Hypatia results coexist with CodeQL's
227-
# (codeql.yml) instead of overwriting them on the same surface.
228-
category: hypatia
229-
- name: Submit findings to gitbot-fleet (Phase 2)
230-
if: steps.scan.outputs.findings_count > 0
231-
# Phase 2 is the collaborative LEARNING side-channel ("bots share
232-
# findings via gitbot-fleet"), not the security gate. The gate is
233-
# the baseline-aware "Check for critical or high-severity issues"
234-
# step below. A fleet-side regression (e.g. the submit script being
235-
# moved/removed) must NEVER hard-fail every consuming repo's scan.
236-
# Same reasoning as the "Comment on PR with findings" step.
237-
# See hyperpolymath/hypatia#213 (gate decoupling) and the exit-127
238-
# estate-wide breakage when gitbot-fleet/scripts/submit-finding.sh
239-
# no longer existed on the default branch.
240-
continue-on-error: true
241-
env:
242-
# All GitHub context values surface as env vars so the run
243-
# block never interpolates `${{ … }}` inline (closes the
244-
# workflow_audit/unsafe_curl_payload + actions_expression_injection
245-
# findings).
246-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
247-
FLEET_PUSH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
248-
FLEET_DISPATCH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
249-
GITHUB_REPOSITORY: ${{ github.repository }}
250-
GITHUB_SHA: ${{ github.sha }}
251-
FINDINGS_COUNT: ${{ steps.scan.outputs.findings_count }}
252-
run: "echo \"\U0001F4E4 Submitting $FINDINGS_COUNT findings to gitbot-fleet...\"\n\n# Clone gitbot-fleet to temp directory. A clone failure (network,\n# repo gone) is non-fatal: learning submission is best-effort.\nFLEET_DIR=\"/tmp/gitbot-fleet-$$\"\nif ! git clone --depth 1 https://github.com/hyperpolymath/gitbot-fleet.git \"$FLEET_DIR\"; then\n echo \"::warning::Could not clone gitbot-fleet — skipping Phase 2 learning submission (non-fatal).\"\n exit 0\nfi\n\n# The submission script's location in gitbot-fleet has drifted\n# before (it was absent from the default branch, which exit-127'd\n# every consuming repo's scan). Probe known locations rather than\n# hard-coding one path, and skip gracefully if none is present.\nSUBMIT_SCRIPT=\"\"\nfor cand in \\\n \"$FLEET_DIR/scripts/submit-finding.sh\" \\\n \"$FLEET_DIR/scripts/submit_finding.sh\" \\\n \"$FLEET_DIR/bin/submit-finding.sh\" \\\n \"$FLEET_DIR/submit-finding.sh\"; do\n if [ -f \"$cand\" ]; then\n SUBMIT_SCRIPT=\"$cand\"\n break\n fi\ndone\n\nif [ -z \"$SUBMIT_SCRIPT\" ]; then\n echo \"::warning::gitbot-fleet submit-finding script not found at any known path — skipping Phase 2 learning submission (non-fatal). Findings are still uploaded as an artifact and gated below.\"\n rm -rf \"$FLEET_DIR\"\n exit 0\nfi\n\n# Run submission script. Pass the findings path as ABSOLUTE —\n# the script cd's into its own working dir before reading the\n# file, so a relative path would resolve to the wrong place.\n# A submission-script failure is logged but non-fatal.\nif bash \"$SUBMIT_SCRIPT\" \"$GITHUB_WORKSPACE/hypatia-findings.json\"; then\n echo \"✅ Finding submission complete\"\nelse\n echo \"::warning::gitbot-fleet submission script exited non-zero — Phase 2 learning submission skipped (non-fatal).\"\nfi\n\n# Cleanup\nrm -rf \"$FLEET_DIR\"\n"
253-
- name: Check for critical issues
254-
if: steps.scan.outputs.critical > 0
255-
# GATING POLICY (explicit, by design — not an oversight):
256-
# Hypatia is ADVISORY here. Critical findings are surfaced
257-
# (step annotation + SARIF alert on the code-scanning page +
258-
# PR comment) but do NOT fail this check. Enforcement is
259-
# delegated to the code-scanning surface: tighten by adding a
260-
# branch-protection "required" status on the `hypatia` SARIF
261-
# category, not by reintroducing an `exit 1` here. This keeps
262-
# the gate decision in one auditable place (hypatia#213 gate
263-
# decoupling) and lets a repo opt into fail-on-critical without
264-
# editing this canonical workflow. To change the policy, change
265-
# branch protection — deliberately no commented-out `exit 1`.
266-
run: |
267-
echo "::warning::Hypatia found critical security issue(s) — advisory."
268-
echo "See the Security → Code scanning page (category: hypatia)"
269-
echo "and the hypatia-findings.json artifact for details."
270-
- name: Generate scan report
271-
run: |
272-
cat << EOF > hypatia-report.md
273-
# Hypatia Security Scan Report
274-
275-
**Repository:** ${{ github.repository }}
276-
**Scan Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
277-
**Commit:** ${{ github.sha }}
278-
279-
## Summary
280-
281-
| Severity | Count |
282-
|----------|-------|
283-
| Critical | ${{ steps.scan.outputs.critical }} |
284-
| High | ${{ steps.scan.outputs.high }} |
285-
| Medium | ${{ steps.scan.outputs.medium }} |
286-
| **Total**| ${{ steps.scan.outputs.findings_count }} |
287-
288-
## Next Steps
289-
290-
1. Triage findings on the **Security → Code scanning** page
291-
(SARIF category \`hypatia\`) — dismiss/track them there like
292-
CodeQL alerts.
293-
2. The full finding set is also attached as the
294-
\`hypatia-findings.json\` build artifact for offline review.
295-
3. Findings are **advisory** today (surfaced, not gated); the
296-
gating policy is documented in the workflow's "Check for
297-
critical issues" step.
298-
299-
## Learning
300-
301-
These findings feed Hypatia's learning engine to improve future rules.
302-
303-
---
304-
*Powered by [Hypatia](https://github.com/hyperpolymath/hypatia) - Neurosymbolic CI/CD Intelligence*
305-
EOF
306-
307-
cat hypatia-report.md >> $GITHUB_STEP_SUMMARY
308-
- name: Comment on PR with findings
309-
if: github.event_name == 'pull_request' && steps.scan.outputs.findings_count > 0
310-
# Advisory only — posting findings as a PR comment must never gate
311-
# the scan (hypatia#213 gate decoupling). Belt-and-braces alongside
312-
# the pull-requests: write permission above: a token/API hiccup or
313-
# a fork PR (read-only token) skips the comment, not the check.
314-
continue-on-error: true
315-
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
316-
with:
317-
script: "const fs = require('fs');\nconst findings = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));\n\nconst critical = findings.filter(f => f.severity === 'critical').length;\nconst high = findings.filter(f => f.severity === 'high').length;\n\nlet comment = `## \U0001F50D Hypatia Security Scan\\n\\n`;\ncomment += `**Findings:** ${findings.length} issues detected\\n\\n`;\ncomment += `| Severity | Count |\\n|----------|-------|\\n`;\ncomment += `| \U0001F534 Critical | ${critical} |\\n`;\ncomment += `| \U0001F7E0 High | ${high} |\\n`;\ncomment += `| \U0001F7E1 Medium | ${findings.length - critical - high} |\\n\\n`;\n\nif (critical > 0) {\n comment += `⚠️ **Action Required:** Critical security issues found!\\n\\n`;\n}\n\ncomment += `<details><summary>View findings</summary>\\n\\n`;\ncomment += `\\`\\`\\`json\\n${JSON.stringify(findings.slice(0, 10), null, 2)}\\n\\`\\`\\`\\n`;\ncomment += `</details>\\n\\n`;\ncomment += `*Powered by Hypatia Neurosymbolic CI/CD Intelligence*`;\n\ngithub.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.issue.number,\n body: comment\n});"
40+
uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@861b5e911d9e5dcfb3c0ab3dd2a9a3c8fd0a1613
41+
secrets: inherit

0 commit comments

Comments
 (0)