diff --git a/.codapult/guard/rules.json b/.codapult/guard/rules.json index d3bb844b1..c323f2cfa 100644 --- a/.codapult/guard/rules.json +++ b/.codapult/guard/rules.json @@ -9,6 +9,22 @@ "waiverPolicy": { "warningDays": 14 }, - "revision": 1, - "contentFingerprint": "1ae062148e97cb74a235586949b55b2608977b4efe497216857cc7c8e83f120d" + "revision": 2, + "contentFingerprint": "4f256912acd5af4f1ca37018f38f145b1bcef05528c8c324ad09521c908684b1", + "githubActions": { + "workflows": [ + { + "path": ".github/workflows/codapult-guard.yml", + "job": "guard", + "requiredRunIncludes": [ + "pnpm exec codapult-guard verify", + "--policy-base" + ], + "maxPermissions": { + "contents": "read", + "security-events": "write" + } + } + ] + } } diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index cccb81b4a..2e607aab9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1,2 @@ /.github/** @Andarist @bluwy @emmatown +/.codapult/guard/** @Andarist @bluwy @emmatown diff --git a/.github/workflows/guard-trusted-pr-attestation.yml b/.github/workflows/guard-trusted-pr-attestation.yml new file mode 100644 index 000000000..7bc32fa57 --- /dev/null +++ b/.github/workflows/guard-trusted-pr-attestation.yml @@ -0,0 +1,482 @@ +name: Guard Trusted PR Verification + +on: + # GitHub loads this workflow from the repository's default branch, so PR changes cannot + # alter or skip the verifier that produces the required status check. + pull_request_target: + types: [opened, synchronize, reopened, ready_for_review, edited] + +permissions: {} + +jobs: + inspect: + runs-on: ubuntu-latest + outputs: + number: ${{ steps.pr.outputs.number }} + head_sha: ${{ steps.pr.outputs.head_sha }} + base_sha: ${{ steps.pr.outputs.base_sha }} + fork: ${{ steps.pr.outputs.fork }} + steps: + - name: Read the associated pull request context + id: pr + env: + EVENT_PATH: ${{ github.event_path }} + run: | + node --input-type=module <<'NODE' + import { appendFileSync, readFileSync } from 'node:fs'; + const event = JSON.parse(readFileSync(process.env.EVENT_PATH, 'utf8')); + const pullRequest = event.pull_request; + const isRepository = (value) => typeof value === 'string' && /^[^/\s]+\/[^/\s]+$/.test(value); + const number = pullRequest?.number; + const headSha = pullRequest?.head?.sha; + const baseSha = pullRequest?.base?.sha; + const headRepository = pullRequest?.head?.repo?.full_name; + const baseRepository = pullRequest?.base?.repo?.full_name; + const eventRepository = event.repository?.full_name; + if ( + !Number.isSafeInteger(number) || + number < 1 || + !/^[a-f0-9]{40}$/i.test(headSha ?? '') || + !/^[a-f0-9]{40}$/i.test(baseSha ?? '') || + !isRepository(headRepository) || + !isRepository(baseRepository) || + !isRepository(eventRepository) || + baseRepository.toLowerCase() !== eventRepository.toLowerCase() + ) { + throw new Error('Pull request number, repositories, head SHA, or base SHA is missing or invalid.'); + } + const fork = headRepository.toLowerCase() !== baseRepository.toLowerCase(); + appendFileSync(process.env.GITHUB_OUTPUT, `number=${number}\nhead_sha=${headSha}\nbase_sha=${baseSha}\nfork=${fork}\n`); + NODE + + verify: + needs: inspect + if: needs.inspect.result == 'success' + name: Guard trusted verification + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + attestation: ${{ steps.result.outputs.attestation }} + steps: + - name: Check out the PR head from the base repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: refs/pull/${{ needs.inspect.outputs.number }}/head + fetch-depth: 0 + + - name: Fetch the exact base commit and verify the checkout + env: + BASE_SHA: ${{ needs.inspect.outputs.base_sha }} + HEAD_SHA: ${{ needs.inspect.outputs.head_sha }} + run: | + git fetch --no-tags origin "$BASE_SHA" + actual_head=$(git rev-parse HEAD) + if [ "$actual_head" != "$HEAD_SHA" ]; then + echo "Checked out $actual_head, expected PR head $HEAD_SHA" >&2 + exit 1 + fi + + - name: Set up Node.js + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 22 + + - name: Fetch the pinned Guard source revision + working-directory: ${{ runner.temp }} + env: + GUARD_VERSION: ${{ vars.CODAPULT_GUARD_VERSION }} + GUARD_COMMIT: ${{ vars.CODAPULT_GUARD_COMMIT }} + run: | + if ! [[ "$GUARD_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then + echo "Set CODAPULT_GUARD_VERSION to an exact Guard release version." >&2 + exit 1 + fi + if ! [[ "$GUARD_COMMIT" =~ ^[a-f0-9]{40}$ ]]; then + echo "Set CODAPULT_GUARD_COMMIT to the full 40-character commit SHA for that Guard release tag." >&2 + exit 1 + fi + git init codapult-guard-source + git -C codapult-guard-source remote add origin https://github.com/codapult/codapult-guard.git + git -C codapult-guard-source fetch --depth=1 origin "refs/tags/v$GUARD_VERSION:refs/tags/guard-release" + fetched_commit=$(git -C codapult-guard-source rev-parse 'refs/tags/guard-release^{commit}') + if [ "$fetched_commit" != "$GUARD_COMMIT" ]; then + echo "Guard release tag resolved to $fetched_commit, expected $GUARD_COMMIT." >&2 + exit 1 + fi + git -C codapult-guard-source checkout --detach "$GUARD_COMMIT" + if [ "$(node -p "require('./codapult-guard-source/package.json').version")" != "$GUARD_VERSION" ]; then + echo "Guard source package version does not match CODAPULT_GUARD_VERSION." >&2 + exit 1 + fi + + - name: Build pinned Guard with its frozen dependency graph + working-directory: ${{ runner.temp }}/codapult-guard-source + run: | + corepack enable + corepack pnpm install --frozen-lockfile --ignore-scripts + corepack pnpm --filter @codapult/guard build + + - name: Verify PR with trusted Guard and base policy + env: + BASE_SHA: ${{ needs.inspect.outputs.base_sha }} + GUARD_POLICY_MODE: ${{ vars.CODAPULT_GUARD_POLICY_MODE || 'strict' }} + GUARD_RESULT_FILE: ${{ runner.temp }}/guard-verification.json + GUARD_STATEMENT_FILE: ${{ runner.temp }}/guard-verification.intoto.json + run: | + check_args=(--no-project-checks --tools off) + case "$GUARD_POLICY_MODE" in + host-review) + ;; + strict) + check_args+=(--fail-on-policy-change --fail-on-protected-changes) + ;; + *) + echo "Unsupported CODAPULT_GUARD_POLICY_MODE: $GUARD_POLICY_MODE (expected host-review or strict)." >&2 + exit 2 + ;; + esac + node "$RUNNER_TEMP/codapult-guard-source/dist/cli/index.js" verify \ + "${check_args[@]}" \ + --policy-base "$BASE_SHA" \ + --json \ + --attestation-out "$GUARD_STATEMENT_FILE" \ + > "$GUARD_RESULT_FILE" + + - name: Confirm the receipt matches this PR + id: result + env: + BASE_SHA: ${{ needs.inspect.outputs.base_sha }} + HEAD_SHA: ${{ needs.inspect.outputs.head_sha }} + GUARD_VERSION: ${{ vars.CODAPULT_GUARD_VERSION }} + GUARD_POLICY_MODE: ${{ vars.CODAPULT_GUARD_POLICY_MODE || 'strict' }} + GUARD_RESULT_FILE: ${{ runner.temp }}/guard-verification.json + GUARD_STATEMENT_FILE: ${{ runner.temp }}/guard-verification.intoto.json + run: | + node --input-type=module <<'NODE' + import { createHash } from 'node:crypto'; + import { appendFileSync, readFileSync, rmSync } from 'node:fs'; + const result = JSON.parse(readFileSync(process.env.GUARD_RESULT_FILE, 'utf8')); + const receipt = result.run?.receipt; + const scope = receipt?.verificationScope; + if (result.outcome !== 'pass' || receipt?.outcome !== 'pass') throw new Error('Guard did not pass.'); + if (receipt.version !== 1 || receipt.kind !== 'verification-receipt' || typeof receipt.runId !== 'string' || receipt.runId.length === 0) { + throw new Error('Guard receipt has an unsupported schema or no run ID.'); + } + const supportedStages = new Set([ + 'runtime', + 'project-checks', + 'adapters', + 'architecture-policy', + 'policy-surface', + 'ci-integrity', + 'verification-scope', + ]); + if ( + !Array.isArray(receipt.requiredStages) || + receipt.requiredStages.length === 0 || + !receipt.requiredStages.includes('verification-scope') || + !Array.isArray(receipt.incompleteStages) || + receipt.incompleteStages.length > 0 || + !receipt.stages || + typeof receipt.stages !== 'object' || + Array.isArray(receipt.stages) || + new Set(receipt.requiredStages).size !== receipt.requiredStages.length || + receipt.requiredStages.some( + (stage) => !supportedStages.has(stage) || receipt.stages[stage] !== 'ok', + ) + ) { + throw new Error('Guard receipt has incomplete or unsupported required stages.'); + } + if (receipt.subject?.headSha !== process.env.HEAD_SHA || receipt.subject?.baseSha !== process.env.BASE_SHA) { + throw new Error('Guard receipt does not match the triggering PR head and base SHAs.'); + } + if (receipt.policy?.source !== 'git-ref' || receipt.policy?.ref !== process.env.BASE_SHA) { + throw new Error('Guard did not use the exact policy revision from the PR base.'); + } + if (typeof receipt.policy.changedFromBase !== 'boolean') { + throw new Error('Guard receipt does not state whether policy changed from the base.'); + } + if (scope?.algorithm !== 'sha256' || scope.complete !== true || scope.stable !== true || !/^[a-f0-9]{64}$/.test(scope.fingerprint ?? '') || !Array.isArray(scope.files)) { + throw new Error('Guard receipt has no complete, stable verification scope.'); + } + if ( + scope.source?.repository !== process.env.GITHUB_REPOSITORY || + scope.source?.commit !== process.env.HEAD_SHA || + scope.source?.headSha !== process.env.HEAD_SHA || + scope.source?.baseSha !== process.env.BASE_SHA || + scope.source?.baseCommit !== process.env.BASE_SHA + ) { + throw new Error('Guard verification scope is not bound to this repository and PR revisions.'); + } + if ( + (receipt.subject?.repository ?? null) !== scope.source.repository || + receipt.subject?.commit !== scope.source.commit || + receipt.subject?.headSha !== scope.source.headSha || + receipt.subject?.baseSha !== scope.source.baseSha || + receipt.subject?.baseCommit !== scope.source.baseCommit + ) { + throw new Error('Guard receipt Git context does not match its fingerprinted source binding.'); + } + if ( + !/^[a-f0-9]{64}$/.test(receipt.policy?.fingerprint ?? '') || + receipt.tool?.name !== '@codapult/guard' || + receipt.tool?.version !== process.env.GUARD_VERSION || + scope.files.some((file) => + !file || + typeof file.path !== 'string' || + file.path.length === 0 || + file.path.includes('\\') || + file.path.startsWith('/') || + /^[a-z]:\//i.test(file.path) || + file.path.split('/').includes('..') || + !['present', 'deleted'].includes(file.status) || + (file.status === 'present' + ? !/^[a-f0-9]{64}$/.test(file.sha256 ?? '') + : file.sha256 !== undefined) + ) + ) { + throw new Error('Guard receipt tool version or verification-scope fingerprint inputs do not match the pinned Guard package.'); + } + let previousScopePath; + for (const file of scope.files) { + if (previousScopePath !== undefined && file.path <= previousScopePath) { + throw new Error('Guard verification-scope paths must be unique and sorted.'); + } + previousScopePath = file.path; + } + const expectedFingerprint = createHash('sha256') + .update(JSON.stringify({ + algorithm: 'sha256', + policyFingerprint: receipt.policy.fingerprint, + tool: { name: receipt.tool.name, version: receipt.tool.version }, + files: scope.files.map((file) => file.status === 'present' + ? { path: file.path, status: file.status, sha256: file.sha256 } + : { path: file.path, status: file.status }), + source: { + repository: scope.source.repository, + commit: scope.source.commit, + headSha: scope.source.headSha, + baseSha: scope.source.baseSha, + baseCommit: scope.source.baseCommit, + }, + }), 'utf8') + .digest('hex'); + if (scope.fingerprint !== expectedFingerprint) { + throw new Error('Guard verification-scope fingerprint does not match its inventory.'); + } + const surface = receipt.policySurface; + if ( + !surface || + surface.complete !== true || + typeof surface.workflowChanged !== 'boolean' || + !Array.isArray(surface.changedPaths) || + !surface.changedPaths.every((path) => typeof path === 'string') || + !Array.isArray(surface.suppressionMarkers) || + !surface.suppressionMarkers.every((marker) => typeof marker === 'string') + ) { + throw new Error('Guard did not completely inspect the policy surface against the base.'); + } + const ciIntegrity = receipt.ciIntegrity; + if ( + ciIntegrity !== undefined && + (!['ok', 'policy-weakened', 'incomplete'].includes(ciIntegrity.status) || + !Array.isArray(ciIntegrity.workflows)) + ) { + throw new Error('Guard receipt has an invalid CI integrity result.'); + } + if (!ciIntegrity || ciIntegrity.status !== 'ok') { + throw new Error('Guard requires a complete, passing GitHub Actions integrity contract.'); + } + const policySensitive = + receipt.policy.changedFromBase === true || + surface.changedPaths.length > 0 || + surface.workflowChanged === true || + surface.suppressionMarkers.length > 0; + if (policySensitive && process.env.GUARD_POLICY_MODE === 'strict') { + throw new Error('Strict policy mode passed a policy-sensitive PR unexpectedly.'); + } + if (policySensitive) { + rmSync(process.env.GUARD_STATEMENT_FILE, { force: true }); + appendFileSync(process.env.GITHUB_STEP_SUMMARY, [ + '## Codapult Guard', + '', + '- Guard verdict: **pass under base policy**.', + '- Host review: **required** for the policy-sensitive changes listed by the receipt.', + '- No in-toto statement was emitted for this PR.', + '', + ].join('\n')); + appendFileSync(process.env.GITHUB_OUTPUT, 'attestation=false\n'); + } else { + const statement = JSON.parse(readFileSync(process.env.GUARD_STATEMENT_FILE, 'utf8')); + const statementReceipt = statement?.predicate?.receipt; + if (statement?._type !== 'https://in-toto.io/Statement/v1' || statement.predicateType !== 'https://github.com/codapult/codapult-guard/blob/main/docs/attestations/guard-verification-v1.md') { + throw new Error('in-toto statement or Guard predicate type is invalid.'); + } + const expectedSubjects = [ + { name: 'codapult-guard:verification-context', digest: { sha256: scope.fingerprint } }, + ...scope.files + .filter((file) => file?.status === 'present') + .map((file) => ({ name: `file:${file.path}`, digest: { sha256: file.sha256 } })), + ]; + if (JSON.stringify(statement.subject) !== JSON.stringify(expectedSubjects)) { + throw new Error('in-toto statement subjects do not match the verified scope.'); + } + if (JSON.stringify(statementReceipt) !== JSON.stringify(receipt)) { + throw new Error('in-toto statement does not match the verified receipt and scope.'); + } + appendFileSync(process.env.GITHUB_OUTPUT, 'attestation=true\n'); + } + NODE + + - name: Upload the independently verified statement + if: steps.result.outputs.attestation == 'true' && needs.inspect.outputs.fork != 'true' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: guard-trusted-pr-statement + path: ${{ runner.temp }}/guard-verification.intoto.json + if-no-files-found: error + + fork-pr-summary: + needs: [inspect, verify] + if: needs.inspect.result == 'success' && needs.inspect.outputs.fork == 'true' && needs.verify.result == 'success' + runs-on: ubuntu-latest + permissions: {} + steps: + - name: Explain the fork PR verification result + run: | + cat >> "$GITHUB_STEP_SUMMARY" <<'SUMMARY' + ## Guard fork PR verification + + The trusted verifier checked this PR's exact head and base revisions using policy from the base revision. No signed attestation was created for this fork PR. The required `Guard trusted verification` check reports the verifier result above. + SUMMARY + + attest: + needs: [inspect, verify] + if: needs.inspect.result == 'success' && needs.inspect.outputs.fork != 'true' && needs.verify.result == 'success' && needs.verify.outputs.attestation == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + attestations: write + artifact-metadata: write + steps: + - name: Download the trusted verifier output + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: guard-trusted-pr-statement + + - name: Prepare Guard predicate and subject checksums + env: + STATEMENT_PATH: ${{ github.workspace }}/guard-verification.intoto.json + PREDICATE_PATH: ${{ runner.temp }}/guard-verification-predicate.json + SUBJECT_CHECKSUMS_PATH: ${{ runner.temp }}/guard-verification-subjects.sha256 + run: | + node --input-type=module <<'NODE' + import { writeFileSync, readFileSync } from 'node:fs'; + const statement = JSON.parse(readFileSync(process.env.STATEMENT_PATH, 'utf8')); + if (!Array.isArray(statement.subject) || statement.subject.length === 0 || !statement.predicate?.receipt) { + throw new Error('Guard statement has no subjects or predicate receipt.'); + } + if (statement.subject.length > 1_024) { + throw new Error('Guard statement exceeds the GitHub attestation subject limit of 1,024.'); + } + const predicate = JSON.stringify(statement.predicate); + if (Buffer.byteLength(predicate, 'utf8') > 16 * 1024 * 1024) { + throw new Error('Guard predicate exceeds the GitHub attestation limit of 16 MiB.'); + } + const checksumLines = statement.subject.map((subject) => { + const digest = subject?.digest?.sha256; + const name = subject?.name; + if (!/^[a-f0-9]{64}$/.test(digest ?? '') || typeof name !== 'string' || name.includes('\0')) { + throw new Error('Guard statement contains an invalid subject digest or name.'); + } + const escaped = /[\\\n]/.test(name); + const checksumName = name.replaceAll('\\', '\\\\').replaceAll('\n', '\\n'); + return `${escaped ? '\\' : ''}${digest} ${checksumName}`; + }); + writeFileSync(process.env.PREDICATE_PATH, `${predicate}\n`); + writeFileSync(process.env.SUBJECT_CHECKSUMS_PATH, `${checksumLines.join('\n')}\n`); + NODE + + - name: Sign the Guard statement file provenance + id: sign_statement + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: guard-verification.intoto.json + + - name: Sign the Guard verification predicate + id: sign_guard + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-checksums: ${{ runner.temp }}/guard-verification-subjects.sha256 + predicate-type: https://github.com/codapult/codapult-guard/blob/main/docs/attestations/guard-verification-v1.md + predicate-path: ${{ runner.temp }}/guard-verification-predicate.json + + - name: Export the signed DSSE envelopes as JSONL + env: + GUARD_BUNDLE_PATH: ${{ steps.sign_guard.outputs.bundle-path }} + STATEMENT_BUNDLE_PATH: ${{ steps.sign_statement.outputs.bundle-path }} + STATEMENT_PATH: ${{ github.workspace }}/guard-verification.intoto.json + OUTPUT_PATH: ${{ runner.temp }}/guard-verification.intoto.jsonl + BUNDLE_OUTPUT_PATH: ${{ runner.temp }}/guard-verification.sigstore.jsonl + run: | + node --input-type=module <<'NODE' + import { createHash } from 'node:crypto'; + import { readFileSync, writeFileSync } from 'node:fs'; + const readBundleEnvelope = (path) => { + const bundle = JSON.parse(readFileSync(path, 'utf8')); + const envelope = bundle?.dsseEnvelope; + if ( + !String(bundle?.mediaType ?? '').startsWith('application/vnd.dev.sigstore.bundle.') || + !envelope || + envelope.payloadType !== 'application/vnd.in-toto+json' || + typeof envelope.payload !== 'string' || + !Array.isArray(envelope.signatures) || + envelope.signatures.length === 0 + ) { + throw new Error(`Expected a Sigstore bundle containing a DSSE in-toto envelope: ${path}`); + } + return { + bundle, + envelope, + statement: JSON.parse(Buffer.from(envelope.payload, 'base64').toString('utf8')), + }; + }; + const sortKeys = (value) => Array.isArray(value) + ? value.map(sortKeys) + : value && typeof value === 'object' + ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])])) + : value; + const guardAttestation = readBundleEnvelope(process.env.GUARD_BUNDLE_PATH); + const fileAttestation = readBundleEnvelope(process.env.STATEMENT_BUNDLE_PATH); + const expectedStatement = JSON.parse(readFileSync(process.env.STATEMENT_PATH, 'utf8')); + if (JSON.stringify(sortKeys(guardAttestation.statement)) !== JSON.stringify(sortKeys(expectedStatement))) { + throw new Error('Guard DSSE envelope does not contain the verified Guard statement.'); + } + const statementDigest = createHash('sha256') + .update(readFileSync(process.env.STATEMENT_PATH)) + .digest('hex'); + if (!fileAttestation.statement.subject?.some((subject) => subject?.digest?.sha256 === statementDigest)) { + throw new Error('Statement provenance envelope does not identify the downloaded Guard statement file.'); + } + writeFileSync( + process.env.OUTPUT_PATH, + `${JSON.stringify(guardAttestation.envelope)}\n${JSON.stringify(fileAttestation.envelope)}\n`, + 'utf8', + ); + writeFileSync( + process.env.BUNDLE_OUTPUT_PATH, + `${JSON.stringify(guardAttestation.bundle)}\n${JSON.stringify(fileAttestation.bundle)}\n`, + 'utf8', + ); + NODE + + - name: Upload the signed in-toto JSONL envelope + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: guard-trusted-pr-attestation + path: | + ${{ runner.temp }}/guard-verification.intoto.jsonl + ${{ runner.temp }}/guard-verification.sigstore.jsonl + if-no-files-found: error