Skip to content

Commit 5ee129a

Browse files
committed
fix(ci): close the last two construction holes — typed inputs, per-file digest
Two findings that had each been reported three times. P1, the `INPUT_*` smuggle. An action binds `INPUT_COMMAND: ${{ inputs.command }}` and runs the constant body `bash -c "$INPUT_COMMAND"`; the digest never moves however callers change the value. Asking what a body DOES with a variable is the content analysis this design refuses, and it would lose to `eval`, bare `$X` and indirect expansion. Asking whether a body MENTIONS it is a substring scan. So the loader finds every input an action dereferences into shell, and the constraint lands on the caller's VALUE, which is a literal here and therefore decidable: each such input declares the exact set of values callers may pass. A command cannot be a member of a closed set of literals, so the reported attack is unrepresentable rather than policed. Nine inputs across three actions is the entire surface; `gate` is exempt because GATE_ACTIONS already constrains it to a registered CheckId, which is tighter. P2, the census. The previous commit pinned each file's step COUNT, which stops an addition. It does not stop a replacement: `census()` dedupes by {source, digest}, so swapping one non-gate body for another leaves arity identical, and `--update` records the new digest under unchanged prose. Confirmed by swapping a linux.yml body for `node -e 'import(...)'` — 90 entries, `ok`. Each file now also pins a fingerprint over every digest it contributes, so add, delete and edit all move a hand-written value. That is the explicit owned waiver the review asked for, as 21 fingerprints rather than 90 prose entries. Both attacks re-run verbatim after the fix, each with `--update` first, and both now fail. Three checked-in regressions, all regenerating the baseline before asserting. Also: two declared input values turned out to be passed by nobody, caught by the ablation that requires every declared value to be load-bearing. 77 gate tests. Manifest, lint, typecheck, format, layering, depgraph, production-exports, fallow and trusted-fixture-artifact green locally. Diff verified as text — no tracked TypeScript source contains a raw NUL.
1 parent c859a11 commit 5ee129a

5 files changed

Lines changed: 382 additions & 16 deletions

File tree

‎scripts/gate/audit.test.ts‎

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import path from 'node:path';
1818
import test from 'node:test';
1919
import { audit, formatFailures, plainGateStep } from './audit.ts';
2020
import { census, loadBaseline } from './baseline.ts';
21-
import { ALLOWED_ENV, EXTERNAL_ACTIONS, GATE_CONDITIONS } from './declarations.ts';
21+
import { ALLOWED_ENV, EXTERNAL_ACTIONS, GATE_CONDITIONS, TYPED_INPUTS } from './declarations.ts';
2222
import { loadModel, type Model } from './model.ts';
2323
import { creditsUnder, loadLanes, stepDigest, type Lane } from './workflows.ts';
2424

@@ -434,6 +434,71 @@ test('every declared gate condition that credits is load-bearing', () => {
434434
}
435435
});
436436

437+
test('r8-10: the reported `INPUT_*` command smuggle is rejected, verbatim', () => {
438+
// The attack as all three rounds described it: bind the input to `env:` so no `${{ }}`
439+
// appears in the body, keep the body constant so its digest never moves, and let callers
440+
// supply the command. Planted through the real loader, and regenerated first, so it is not
441+
// the shipped baseline doing the rejecting.
442+
const planted = plantTree({
443+
'.github/workflows/planted.yml': workflow(
444+
` - uses: ./.github/actions/probe\n with:\n command: node -e 'import("./x.ts")'\n`,
445+
),
446+
'.github/actions/probe/action.yml': `inputs:
447+
command:
448+
description: 'a command'
449+
runs:
450+
using: composite
451+
steps:
452+
- name: Run it
453+
shell: bash
454+
env:
455+
INPUT_COMMAND: \${{ inputs.command }}
456+
run: bash -c "$INPUT_COMMAND"
457+
`,
458+
});
459+
const found = audit(planted, regenerate(planted));
460+
const typed = found.filter((f) => f.assertion === 'typed');
461+
assert.equal(typed.length, 1, 'an input read from shell with no vocabulary must be a finding');
462+
assert.match(typed[0]?.message ?? '', /dereferences `inputs\.command` into a shell body/);
463+
});
464+
465+
test('r8-10: a call-site value outside an input`s vocabulary is rejected', () => {
466+
// The other half: the input IS declared, and a caller passes something else. Without this
467+
// the vocabulary would only document, never constrain.
468+
const planted = plantWorkflow(
469+
workflow(` - uses: ./.github/actions/setup-fixture-app
470+
with:
471+
platform: windows; node -e '1'
472+
`),
473+
);
474+
const found = audit(planted, baseline).filter((f) => f.assertion === 'typed');
475+
assert.ok(
476+
found.some((f) => /`platform: windows; node -e '1'`/.test(f.message)),
477+
'a value outside the declared set must be named in the finding',
478+
);
479+
});
480+
481+
test('every TYPED_INPUTS value is load-bearing', () => {
482+
// Dropping any one declared value must produce a finding, or nothing passes it.
483+
for (const [source, inputs] of Object.entries(TYPED_INPUTS)) {
484+
for (const [input, spec] of Object.entries(inputs)) {
485+
for (const value of spec.values) {
486+
const narrowed = {
487+
...TYPED_INPUTS,
488+
[source]: {
489+
...inputs,
490+
[input]: { ...spec, values: spec.values.filter((v) => v !== value) },
491+
},
492+
};
493+
assert.ok(
494+
audit(base, baseline, EXTERNAL_ACTIONS, ALLOWED_ENV, narrowed).length > 0,
495+
`TYPED_INPUTS ${source} \`${input}\` value ${JSON.stringify(value)} is passed by nobody`,
496+
);
497+
}
498+
}
499+
}
500+
});
501+
437502
// Rounds 8, 9 and 10 each asked for per-edge ownership of the generated baseline. The
438503
// concrete defect behind that objection — never stated in the reviews, found by reproducing
439504
// it — is that reasons were keyed per FILE with no arity, so `--update` blessed both a new
@@ -450,7 +515,7 @@ test('r8-10: `--update` cannot bless a new step in an already-described file', (
450515
);
451516
const census_ = found.filter((f) => f.assertion === 'census');
452517
assert.equal(census_.length, 1);
453-
assert.match(census_[0]?.message ?? '', /ci\.yml declares 7 non-gate step\(s\).*has 8/s);
518+
assert.match(census_[0]?.message ?? '', /ci\.yml: a step was added \(7 → 8\)/);
454519
});
455520

456521
test('r8-10: `--update` cannot bless a file nobody has described', () => {
@@ -462,6 +527,32 @@ test('r8-10: `--update` cannot bless a file nobody has described', () => {
462527
assert.match(found[0]?.message ?? '', /planted\.yml has 1 step\(s\).*no REASONS entry/s);
463528
});
464529

530+
test('r11: `--update` cannot bless a body swapped in at unchanged arity', () => {
531+
// Round 11's point, and it was right: `census()` dedupes by {source, digest}, so REPLACING
532+
// one non-gate body with another leaves the file's step count identical. Arity alone was
533+
// not enough; the per-file digest is what moves.
534+
const swapped: Model = {
535+
...base,
536+
lanes: base.lanes.map((lane) => ({
537+
...lane,
538+
steps: lane.steps.map((step) =>
539+
step.source === 'linux.yml' && step.name === 'Install Linux desktop dependencies'
540+
? { ...step, run: `node -e '1'`, digest: stepDigest(`node -e '1'`, step.extras) }
541+
: step,
542+
),
543+
})),
544+
};
545+
const found = audit(swapped, regenerate(swapped));
546+
assert.deepEqual(
547+
found.filter((f) => f.assertion === 'bypass'),
548+
[],
549+
'regeneration accepts the new digest, and the count is unchanged — so neither can be the guard',
550+
);
551+
const census_ = found.filter((f) => f.assertion === 'census');
552+
assert.equal(census_.length, 1);
553+
assert.match(census_[0]?.message ?? '', /linux\.yml: a step's body was edited/);
554+
});
555+
465556
test('r8-10: a REASONS entry describing no live step is inert', () => {
466557
// The other direction, and it was live on this branch: `macos.yml` still carried a reason
467558
// after round 7 moved its build step into the Apple runner action.

‎scripts/gate/audit.ts‎

Lines changed: 79 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,17 @@
77
// functions below, because CI can only reach a gate through `pnpm gate <id>`.
88

99
import { CHECK_CATALOG } from '../check-affected/checks.ts';
10-
import { loadBaseline, reasonFor, type BaselineEntry } from './baseline.ts';
10+
import { fileDigest, loadBaseline, reasonFor, type BaselineEntry } from './baseline.ts';
1111
import {
1212
ALLOWED_ENV,
1313
EXTERNAL_ACTIONS,
1414
GATE_ACTIONS,
1515
GATE_CONDITIONS,
1616
REASONS,
17+
TYPED_INPUTS,
1718
UNPROVABLE_OWNERS,
1819
type ExternalAction,
20+
type TypedInput,
1921
} from './declarations.ts';
2022
import { categories, checkUnits, covered, scriptUnits, type Model } from './model.ts';
2123
import { commandSegments, stripExpressions } from './shell.ts';
@@ -31,6 +33,7 @@ const HEADINGS: Readonly<Record<string, string>> = {
3133
external: 'Third-party actions with no declaration',
3234
surface: 'Execution surfaces the manifest does not model',
3335
'path-coverage': 'Paths whose selected checks no triggered lane runs',
36+
typed: 'Action inputs reaching a shell body with no closed vocabulary',
3437
census: 'Files running shell outside the runner that nobody has described',
3538
condition: 'Gate steps behind an `if:` nobody has ruled on',
3639
inert: 'Declarations that no longer apply',
@@ -392,6 +395,63 @@ function inertOpaque(model: Model): Failure[] {
392395
});
393396
}
394397

398+
// 3b. Every local-action input that reaches a shell body has a closed vocabulary, and every
399+
// caller stays inside it.
400+
//
401+
// The last standing P1 from rounds 8–10: an action binds `INPUT_COMMAND` from an input
402+
// and runs `bash -c "$INPUT_COMMAND"`. The body is constant, so its digest never moves,
403+
// and `INPUT_` is allowed wholesale — the caller's command is invisible.
404+
//
405+
// `shellInputs` finds which inputs a body dereferences (a substring scan, not an
406+
// interpretation), and the constraint lands on the caller's VALUE. A command cannot be a
407+
// member of a closed set of literals, so the attack is unrepresentable rather than
408+
// policed — and adding such an input fails until someone writes down what may be passed.
409+
function typedInputs(
410+
model: Model,
411+
declared: Readonly<Record<string, Readonly<Record<string, TypedInput>>>>,
412+
): Failure[] {
413+
const uses = model.lanes
414+
.filter((lane) => lane.qualifying)
415+
.flatMap((lane) => lane.actionInputs.map((use) => ({ ...use, lane: lane.label })));
416+
const findings = uses.flatMap((use) => {
417+
// A GATE_ACTIONS input is constrained harder than any value list: `gateIds` requires it
418+
// to name a registered check, and `gateActionBodies` proves the body runs exactly
419+
// `pnpm gate` on it. Listing its values here would be a weaker duplicate that goes stale
420+
// every time the catalog grows.
421+
if (GATE_ACTIONS[use.source] === use.input) return [];
422+
const spec = declared[use.source]?.[use.input];
423+
if (spec === undefined) {
424+
return [
425+
fail(
426+
'typed',
427+
`${use.source} dereferences \`inputs.${use.input}\` into a shell body, but ` +
428+
`TYPED_INPUTS does not say what callers may pass. Declare the exact values, or ` +
429+
`stop reading the input from shell.`,
430+
),
431+
];
432+
}
433+
if (spec.values.includes(use.value)) return [];
434+
return [
435+
fail(
436+
'typed',
437+
`${use.lane} passes ${use.source} \`${use.input}: ${use.value}\` (via ${use.via}), ` +
438+
`which is not one of its declared values: ${spec.values.join(', ')}.`,
439+
),
440+
];
441+
});
442+
const live = new Set(uses.map((use) => JSON.stringify([use.source, use.input])));
443+
const dead = Object.entries(declared).flatMap(([source, inputs]) =>
444+
Object.keys(inputs)
445+
.filter((input) => !live.has(JSON.stringify([source, input])))
446+
.map((input) =>
447+
fail('inert', `TYPED_INPUTS entry ${source} \`${input}\` reaches no shell body.`),
448+
),
449+
);
450+
return [...new Set(findings.map((f) => f.message))]
451+
.map((message) => fail('typed', message))
452+
.concat(dead);
453+
}
454+
395455
// 4b. Every file in the baseline is DESCRIBED, and described with the right arity.
396456
//
397457
// Rounds 8, 9 and 10 all asked for per-edge ownership of the baseline, and the objection
@@ -412,19 +472,27 @@ function censusFiles(declared: readonly BaselineEntry[]): Failure[] {
412472
fail(
413473
'census',
414474
`${source} has ${count} step(s) in the baseline but no REASONS entry: nothing says why ` +
415-
`this file runs shell outside the runner. Add one with \`steps: ${count}\`.`,
475+
`this file runs shell outside the runner. Add one with ` +
476+
`\`steps: ${count}, digest: '${fileDigest(declared, source)}'\`.`,
416477
),
417478
);
418-
const miscounted = [...counted.entries()].flatMap(([source, count]) => {
479+
const drifted = [...counted.entries()].flatMap(([source, count]) => {
419480
const declaredFile = REASONS[source];
420-
if (declaredFile === undefined || declaredFile.steps === count) return [];
421-
const verb = count > declaredFile.steps ? 'added' : 'removed';
481+
if (declaredFile === undefined) return [];
482+
const digest = fileDigest(declared, source);
483+
if (declaredFile.steps === count && declaredFile.digest === digest) return [];
484+
// Arity moves on add/delete; the digest moves on those AND on an edit that keeps the
485+
// count, which is the case arity alone missed.
486+
const what =
487+
declaredFile.steps === count
488+
? `a step's body was edited (${count} step(s) either way)`
489+
: `a step was ${count > declaredFile.steps ? 'added' : 'removed'} (${declaredFile.steps} → ${count})`;
422490
return [
423491
fail(
424492
'census',
425-
`${source} declares ${declaredFile.steps} non-gate step(s) and the baseline has ` +
426-
`${count}: a step was ${verb}. Confirm it belongs outside \`pnpm gate\`, update the ` +
427-
`reason if it no longer describes the file, and set \`steps: ${count}\`.`,
493+
`${source}: ${what}. Confirm the shell still belongs outside \`pnpm gate\`, update the ` +
494+
`reason if it no longer describes the file, and set ` +
495+
`\`steps: ${count}, digest: '${digest}'\`.`,
428496
),
429497
];
430498
});
@@ -433,7 +501,7 @@ function censusFiles(declared: readonly BaselineEntry[]): Failure[] {
433501
.map((source) =>
434502
fail('inert', `REASONS entry "${source}" describes no step any qualifying lane reaches.`),
435503
);
436-
return [...undeclared, ...miscounted, ...dead];
504+
return [...undeclared, ...drifted, ...dead];
437505
}
438506

439507
function seenConditions(model: Model): Set<string> {
@@ -533,13 +601,15 @@ export function audit(
533601
declared: readonly BaselineEntry[] = loadBaseline(),
534602
externals: readonly ExternalAction[] = EXTERNAL_ACTIONS,
535603
allowedEnv: readonly string[] = ALLOWED_ENV,
604+
typed: Readonly<Record<string, Readonly<Record<string, TypedInput>>>> = TYPED_INPUTS,
536605
): Failure[] {
537606
return [
538607
...unowned(model),
539608
...bypass(model, declared),
540609
...gateIds(model),
541610
...gateConditions(model),
542611
...gateActionBodies(model, GATE_ACTIONS),
612+
...typedInputs(model, typed),
543613
...environment(model, allowedEnv),
544614
...laneSurfaces(model),
545615
...externalActions(model, externals),

‎scripts/gate/baseline.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// inert. Regenerating is an explicit command whose diff a reviewer reads — `pnpm
1212
// check:gate-manifest --update` — not something the audit does for itself.
1313

14+
import { createHash } from 'node:crypto';
1415
import fs from 'node:fs';
1516
import path from 'node:path';
1617
import { REASONS } from './declarations.ts';
@@ -37,6 +38,27 @@ export function reasonFor(source: string): string {
3738

3839
const key = (entry: BaselineEntry) => JSON.stringify([entry.source, entry.digest]);
3940

41+
/**
42+
* One fingerprint over everything a file contributes to the census.
43+
*
44+
* Arity alone was not enough, and round 11 said why: `--update` regenerates digests, so
45+
* REPLACING one non-gate body with another leaves the count identical and the audit green.
46+
* Confirmed on this branch — swapping a `linux.yml` step's body for
47+
* `node -e 'import("./scripts/layering/check.ts")'` kept 90 entries and printed `ok`.
48+
*
49+
* Hashing the file's digests means any add, delete or edit moves this one value, and it lives
50+
* in the hand-written declaration rather than the generated file. That is the "explicit owned
51+
* waiver" the review asked for three rounds running, expressed as 21 fingerprints instead of
52+
* 90 prose entries.
53+
*/
54+
export function fileDigest(entries: readonly BaselineEntry[], source: string): string {
55+
const digests = entries
56+
.filter((entry) => entry.source === source)
57+
.map((entry) => entry.digest)
58+
.sort();
59+
return createHash('sha256').update(digests.join('\n')).digest('hex').slice(0, 12);
60+
}
61+
4062
/**
4163
* Every step a qualifying lane reaches that is not a plain gate invocation, deduplicated by
4264
* declaring file and digest, so a composite action used by eight lanes appears once.

0 commit comments

Comments
 (0)