Skip to content

Commit 049796e

Browse files
committed
feat(workflowcheck): Enforce condition-compatible steps, pinned executable bindings, and structural argument validation
Address three P1 PR #131 review findings against the static toolchain contract. - Step conditions: contract-relevant steps in a job must all carry the exact same whitespace-normalized if: expression (or none), and constant-false conditions are rejected, so an assertion can never be skipped while an npm operation runs. The production publish segment's uniform upstream-success gate remains compatible. - Executable binding: the publish diagnostics and publish steps must resolve NPM_EXECUTABLE to exactly the provisioning step output expression, at step or job env scope, rejecting ambient or hardcoded rebinding. - Argument validation: shell comments are stripped before matching and the --npm-executable argument token must be exactly the pinned expression; comment-supplied evidence, duplicate flags, concatenated tokens, unknown variables, and single-quoted literal variable names are rejected. - Preflight report contract: the node-only assertion and provisioning steps must now pass --report-path "$REPORT_PATH" with REPORT_PATH bound to the outcome report path, so the persistence wiring added for the outcome-report finding cannot be dropped silently. Fixtures model the production shape. Signed-off-by: Yunseo Kim <[email protected]>
1 parent 7bd8d41 commit 049796e

6 files changed

Lines changed: 312 additions & 16 deletions

File tree

‎internal/workflowcheck/check.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ type workflowOutput struct {
9292
}
9393

9494
type workflowJob struct {
95+
Env map[string]string `yaml:"env"`
9596
If string `yaml:"if"`
9697
Needs any `yaml:"needs"`
9798
RunsOn string `yaml:"runs-on"`
@@ -242,7 +243,7 @@ func CheckPublishJob(path string) (PublishJobResult, error) {
242243
if result.MutationKey != publishConcurrencyGroup || result.CancelInProgress || result.Queue != "max" {
243244
return PublishJobResult{}, fmt.Errorf("publish job must use the exact queued mutation concurrency contract")
244245
}
245-
if err := checkPublishSteps(job.Steps, &result); err != nil {
246+
if err := checkPublishSteps(job, &result); err != nil {
246247
return PublishJobResult{}, err
247248
}
248249
result.Result = "pass"
@@ -362,7 +363,8 @@ func checkNPMWorkflowCall(call workflowCall) error {
362363
return nil
363364
}
364365

365-
func checkPublishSteps(steps []workflowStep, result *PublishJobResult) error {
366+
func checkPublishSteps(job workflowJob, result *PublishJobResult) error {
367+
steps := job.Steps
366368
if len(steps) == 0 || !strings.HasPrefix(steps[0].Uses, "step-security/harden-runner@") || scalar(steps[0].With["egress-policy"]) != "audit" {
367369
return fmt.Errorf("harden-runner with audit egress must be the first publish step")
368370
}
@@ -405,7 +407,7 @@ func checkPublishSteps(steps []workflowStep, result *PublishJobResult) error {
405407
if err := checkPinnedNode(steps, "publish"); err != nil {
406408
return err
407409
}
408-
return checkPublishToolchain(steps)
410+
return checkPublishToolchain(job)
409411
}
410412

411413
func sortedNeeds(value any) []string {

‎internal/workflowcheck/check_test.go‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -228,10 +228,12 @@ jobs:
228228
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
229229
with: {node-version: "24.21.0"}
230230
- working-directory: .slsa-builder
231-
run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert --node-only
231+
env: {REPORT_PATH: "${{ runner.temp }}/windlass-npm-outcome-report.json"}
232+
run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert --node-only --report-path "$REPORT_PATH"
232233
- id: npm-provision
233234
working-directory: .slsa-builder
234-
run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm --output-directory "${{ runner.temp }}/windlass-npm-cli" --github-output "$GITHUB_OUTPUT"
235+
env: {REPORT_PATH: "${{ runner.temp }}/windlass-npm-outcome-report.json"}
236+
run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm --output-directory "${{ runner.temp }}/windlass-npm-cli" --github-output "$GITHUB_OUTPUT" --report-path "$REPORT_PATH"
235237
- run: '"${{ steps.npm-provision.outputs.npm-executable }}" --version'
236238
- id: publish
237239
run: go run ./cmd/slsa-builder-internal npm-profile-publish --npm-executable "${{ steps.npm-provision.outputs.npm-executable }}"
@@ -395,8 +397,8 @@ func writeWorkflow(t *testing.T, contents string) string {
395397
func TestToolchainContractRejectsDrift(t *testing.T) {
396398
t.Parallel()
397399
const pairStep = " - working-directory: .slsa-builder\n run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert\n"
398-
const nodeOnlyStep = " - working-directory: .slsa-builder\n run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert --node-only\n"
399-
const provisionStep = " - id: npm-provision\n working-directory: .slsa-builder\n run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm --output-directory \"${{ runner.temp }}/windlass-npm-cli\" --github-output \"$GITHUB_OUTPUT\"\n"
400+
const nodeOnlyStep = " - working-directory: .slsa-builder\n env: {REPORT_PATH: \"${{ runner.temp }}/windlass-npm-outcome-report.json\"}\n run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert --node-only --report-path \"$REPORT_PATH\"\n"
401+
const provisionStep = " - id: npm-provision\n working-directory: .slsa-builder\n env: {REPORT_PATH: \"${{ runner.temp }}/windlass-npm-outcome-report.json\"}\n run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm --output-directory \"${{ runner.temp }}/windlass-npm-cli\" --github-output \"$GITHUB_OUTPUT\" --report-path \"$REPORT_PATH\"\n"
400402
const diagnostics = " - run: '\"${{ steps.npm-provision.outputs.npm-executable }}\" --version'\n"
401403
const output = "${{ steps.npm-provision.outputs.npm-executable }}"
402404

@@ -426,6 +428,10 @@ func TestToolchainContractRejectsDrift(t *testing.T) {
426428
tests["wrong output"] = replaceOnce(t, body, `--npm-executable "`+output+`"`, `--npm-executable "${{ steps.other.outputs.npm-executable }}"`)
427429
tests["missing executable flag"] = replaceOnce(t, body, ` --npm-executable "`+output+`"`, "")
428430
tests["missing github output"] = replaceOnce(t, body, ` --github-output "$GITHUB_OUTPUT"`, "")
431+
tests["missing assert report-path"] = replaceOnce(t, body, ` --node-only --report-path "$REPORT_PATH"`, " --node-only")
432+
tests["missing assert report env"] = replaceOnce(t, body, " env: {REPORT_PATH: \"${{ runner.temp }}/windlass-npm-outcome-report.json\"}\n run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert", " run: go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert")
433+
tests["missing provision report-path"] = replaceOnce(t, body, ` --github-output "$GITHUB_OUTPUT" --report-path "$REPORT_PATH"`, ` --github-output "$GITHUB_OUTPUT"`)
434+
tests["wrong provision report env"] = replaceOnce(t, body, "env: {REPORT_PATH: \"${{ runner.temp }}/windlass-npm-outcome-report.json\"}\n run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm", "env: {REPORT_PATH: \"${{ runner.temp }}/other.json\"}\n run: go run ./cmd/slsa-builder-internal npm-profile-provision-npm")
429435
} else {
430436
command := "npm-profile-build"
431437
if job == "provenance-sign" {

‎internal/workflowcheck/toolchain.go‎

Lines changed: 81 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,30 @@ package workflowcheck
33
import (
44
"fmt"
55
"regexp"
6+
"slices"
67
"strings"
78
)
89

910
const (
1011
toolchainAssertCommand = "go run ./cmd/slsa-builder-internal npm-profile-toolchain-assert"
1112
provisionNPMCommand = "go run ./cmd/slsa-builder-internal npm-profile-provision-npm"
13+
outcomeReportPath = "${{ runner.temp }}/windlass-npm-outcome-report.json"
1214
)
1315

1416
// Exclude npm-profile subcommands, npm-executable flags, and diagnostic labels (npm:).
1517
var npmReferencePattern = regexp.MustCompile(`(^|[^a-zA-Z0-9_.-])npm($|[^a-zA-Z0-9_.:-])`)
1618

19+
// Capture the whole shell word, including concatenated quoted/unquoted fragments.
20+
var npmExecutableArgumentPattern = regexp.MustCompile(`(?:^|[\s;|&])--npm-executable(?:[ \t]+|=)((?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s"';|&])+)`)
21+
1722
func checkPairAssertion(steps []workflowStep, job string) error {
23+
if err := checkToolchainConditions(steps); err != nil {
24+
return fmt.Errorf("%s: %w", job, err)
25+
}
1826
asserted := false
1927
nodeReady := false
2028
for _, current := range steps {
29+
current.Run = toolchainShellText(current.Run)
2130
if strings.HasPrefix(current.Uses, "actions/setup-node@") {
2231
nodeReady = true
2332
asserted = false
@@ -40,7 +49,11 @@ func checkPairAssertion(steps []workflowStep, job string) error {
4049
return nil
4150
}
4251

43-
func checkPublishToolchain(steps []workflowStep) error {
52+
func checkPublishToolchain(job workflowJob) error {
53+
steps := job.Steps
54+
if err := checkToolchainConditions(steps); err != nil {
55+
return err
56+
}
4457
nodeReady := false
4558
asserted := false
4659
provisionID := ""
@@ -50,35 +63,55 @@ func checkPublishToolchain(steps []workflowStep) error {
5063
asserted = false
5164
provisionID = ""
5265
}
53-
run := strings.ReplaceAll(current.Run, "\\\n", " ")
66+
run := toolchainShellText(current.Run)
5467
if npmReferencePattern.MatchString(run) {
5568
return fmt.Errorf("publish job must use the provisioning output instead of ambient npm")
5669
}
5770
if strings.Contains(run, "npm-profile-toolchain-assert") {
5871
if !nodeReady || current.WorkingDirectory != ".slsa-builder" ||
59-
strings.TrimSpace(run) != toolchainAssertCommand+" --node-only" {
60-
return fmt.Errorf("publish job must invoke npm-profile-toolchain-assert --node-only after Node.js setup")
72+
strings.TrimSpace(run) != toolchainAssertCommand+` --node-only --report-path "$REPORT_PATH"` ||
73+
current.Env["REPORT_PATH"] != outcomeReportPath {
74+
return fmt.Errorf("publish job must invoke npm-profile-toolchain-assert --node-only --report-path after Node.js setup")
6175
}
6276
asserted = true
6377
}
6478
if strings.Contains(run, "npm-profile-provision-npm") {
6579
if !asserted || current.ID == "" || current.WorkingDirectory != ".slsa-builder" ||
6680
!strings.HasPrefix(strings.TrimSpace(run), provisionNPMCommand+" ") ||
67-
!containsAll(run, `--output-directory "${{ runner.temp }}/windlass-npm-cli"`, `--github-output "$GITHUB_OUTPUT"`) {
68-
return fmt.Errorf("publish npm provisioning must have an id and emit GitHub outputs after the node-only assertion")
81+
!containsAll(run, `--output-directory "${{ runner.temp }}/windlass-npm-cli"`, `--github-output "$GITHUB_OUTPUT"`, `--report-path "$REPORT_PATH"`) ||
82+
current.Env["REPORT_PATH"] != outcomeReportPath {
83+
return fmt.Errorf("publish npm provisioning must have an id, emit GitHub outputs, and persist a failure report after the node-only assertion")
6984
}
7085
provisionID = current.ID
7186
}
72-
if strings.Contains(run, "npm-executable") || strings.Contains(run, "npm-profile-publish") {
87+
if strings.Contains(run, "npm-executable") || strings.Contains(run, "npm-profile-publish") || strings.Contains(run, "NPM_EXECUTABLE") {
7388
if provisionID == "" {
7489
return fmt.Errorf("npm provisioning must precede publish diagnostics and npm-profile-publish")
7590
}
7691
output := "${{ steps." + provisionID + ".outputs.npm-executable }}"
92+
argumentRun := run
93+
if strings.Contains(run, "NPM_EXECUTABLE") {
94+
binding, present := current.Env["NPM_EXECUTABLE"]
95+
if !present {
96+
binding = job.Env["NPM_EXECUTABLE"]
97+
}
98+
if binding != output {
99+
return fmt.Errorf("NPM_EXECUTABLE must bind to %s", output)
100+
}
101+
run = strings.NewReplacer("${{ env.NPM_EXECUTABLE }}", output,
102+
"$NPM_EXECUTABLE", output, "${NPM_EXECUTABLE}", output).Replace(run)
103+
}
77104
if !strings.Contains(run, output) || strings.Contains(strings.ReplaceAll(run, output, ""), ".outputs.npm-executable") {
78105
return fmt.Errorf("publish npm references must use %s", output)
79106
}
80-
if strings.Contains(run, "npm-profile-publish") && !strings.Contains(run, `--npm-executable "`+output+`"`) {
81-
return fmt.Errorf("npm-profile-publish --npm-executable must use %s", output)
107+
if strings.Contains(run, "npm-profile-publish") {
108+
arguments := npmExecutableArgumentPattern.FindAllStringSubmatch(argumentRun, -1)
109+
if len(arguments) != 1 || strings.Count(argumentRun, "--npm-executable") != 1 ||
110+
!slices.Contains([]string{`"` + output + `"`, "'" + output + "'",
111+
`"${{ env.NPM_EXECUTABLE }}"`, `'${{ env.NPM_EXECUTABLE }}'`,
112+
`"$NPM_EXECUTABLE"`, `"${NPM_EXECUTABLE}"`}, arguments[0][1]) {
113+
return fmt.Errorf("npm-profile-publish --npm-executable must use exactly one pinned output argument: %s", output)
114+
}
82115
}
83116
}
84117
}
@@ -87,3 +120,42 @@ func checkPublishToolchain(steps []workflowStep) error {
87120
}
88121
return nil
89122
}
123+
124+
// Conditions are compared as whitespace-normalized strings, not evaluated.
125+
// Missing gates must also agree so npm cannot run while its assertion is skipped.
126+
func checkToolchainConditions(steps []workflowStep) error {
127+
gate := ""
128+
seen := false
129+
for _, step := range steps {
130+
step.Run = toolchainShellText(step.Run)
131+
if !strings.HasPrefix(step.Uses, "actions/setup-node@") &&
132+
!npmReferencePattern.MatchString(step.Run) &&
133+
!strings.Contains(step.Run, "npm-profile-toolchain-assert") &&
134+
!strings.Contains(step.Run, "npm-profile-provision-npm") &&
135+
!strings.Contains(step.Run, "npm-profile-build") &&
136+
!strings.Contains(step.Run, "npm-profile-sign") &&
137+
!strings.Contains(step.Run, "npm-profile-publish") &&
138+
!strings.Contains(step.Run, "npm-executable") &&
139+
!strings.Contains(step.Run, "NPM_EXECUTABLE") {
140+
continue
141+
}
142+
condition := strings.Join(strings.Fields(step.If), " ")
143+
if normalizeExpression(condition) == "false" || (seen && condition != gate) {
144+
return fmt.Errorf("toolchain step conditions must be identical and not constant false")
145+
}
146+
gate = condition
147+
seen = true
148+
}
149+
return nil
150+
}
151+
152+
// This conservative line-based strip treats every # as a comment delimiter,
153+
// including inside quotes. It is not a shell evaluator; ambiguous syntax fails
154+
// closed. Strip before joining continuations so comments cannot supply evidence.
155+
func toolchainShellText(run string) string {
156+
lines := strings.Split(run, "\n")
157+
for index, line := range lines {
158+
lines[index], _, _ = strings.Cut(line, "#")
159+
}
160+
return strings.ReplaceAll(strings.Join(lines, "\n"), "\\\n", " ")
161+
}
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
package workflowcheck
2+
3+
import (
4+
"strings"
5+
"testing"
6+
)
7+
8+
func TestPublishExecutableArgumentRejectsSpoofing(t *testing.T) {
9+
t.Parallel()
10+
const expectedFlag = `--npm-executable "` + provisionOutput + `"`
11+
for name, argument := range map[string]string{
12+
"comment only": `--npm-executable "$AMBIENT" # ` + expectedFlag,
13+
"comment on separate line": `--npm-executable "$AMBIENT"` + "\n# " + expectedFlag,
14+
"unknown variable": `--npm-executable "$AMBIENT"`,
15+
"appended shell token": expectedFlag + `"$AMBIENT"`,
16+
"duplicate flag": expectedFlag + ` --npm-executable "$AMBIENT"`,
17+
"wrong first flag": `--npm-executable "$AMBIENT" ` + expectedFlag,
18+
"different flag name": `--other-` + expectedFlag,
19+
"literal environment name": `--npm-executable '$NPM_EXECUTABLE'`,
20+
} {
21+
t.Run(name, func(t *testing.T) {
22+
t.Parallel()
23+
// Given a publish invocation whose actual argument is not the pinned output.
24+
document, err := decodeWorkflow([]byte(validNPMOnlyWorkflow))
25+
if err != nil {
26+
t.Fatal(err)
27+
}
28+
for index, step := range document.Jobs["publish"].Steps {
29+
if step.ID == "publish" {
30+
document.Jobs["publish"].Steps[index].Env = map[string]string{"NPM_EXECUTABLE": provisionOutput}
31+
document.Jobs["publish"].Steps[index].Run = "go run ./cmd/slsa-builder-internal npm-profile-publish " + argument
32+
}
33+
}
34+
// When checked through the YAML contract.
35+
_, err = CheckPublishJob(writeWorkflowDocument(t, document))
36+
// Then comments and substrings cannot substitute for the argument token.
37+
if err == nil {
38+
t.Fatal("untrusted executable argument accepted, want rejection")
39+
}
40+
})
41+
}
42+
}
43+
44+
func TestPublishExecutableArgumentAcceptsPinnedToken(t *testing.T) {
45+
t.Parallel()
46+
for _, argument := range []string{
47+
`--npm-executable "` + provisionOutput + `"`,
48+
`--npm-executable='` + provisionOutput + `'`,
49+
"--npm-executable \\\n\"" + provisionOutput + "\" # trusted CLI",
50+
} {
51+
t.Run(argument, func(t *testing.T) {
52+
t.Parallel()
53+
// Given a quoted pinned token with shell formatting variations.
54+
document, err := decodeWorkflow([]byte(validNPMOnlyWorkflow))
55+
if err != nil {
56+
t.Fatal(err)
57+
}
58+
for index, step := range document.Jobs["publish"].Steps {
59+
if step.ID == "publish" {
60+
document.Jobs["publish"].Steps[index].Run = "go run ./cmd/slsa-builder-internal npm-profile-publish " + argument
61+
}
62+
}
63+
// When checked.
64+
_, err = CheckPublishJob(writeWorkflowDocument(t, document))
65+
// Then only shell formatting, not the executable identity, differs.
66+
if err != nil {
67+
t.Fatal(err)
68+
}
69+
})
70+
}
71+
}
72+
73+
func TestPublishCommentsCannotSupplyProvisioning(t *testing.T) {
74+
t.Parallel()
75+
// Given an inert provisioning command in a shell comment.
76+
contents := replaceOnce(t, validNPMOnlyWorkflow, " run: "+provisionNPMCommand,
77+
" run: |\n # "+provisionNPMCommand)
78+
// When checked.
79+
_, err := CheckPublishJob(writeWorkflow(t, contents))
80+
// Then diagnostics have no executed provisioner.
81+
if err == nil || !strings.Contains(err.Error(), "provision") {
82+
t.Fatalf("commented provisioner error = %v, want provisioning rejection", err)
83+
}
84+
}
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
package workflowcheck
2+
3+
import (
4+
"strings"
5+
"testing"
6+
)
7+
8+
const provisionOutput = "${{ steps.npm-provision.outputs.npm-executable }}"
9+
10+
func TestPublishExecutableBinding(t *testing.T) {
11+
t.Parallel()
12+
for _, scope := range []string{"step", "job"} {
13+
for _, binding := range []string{provisionOutput, "${{ vars.AMBIENT_NPM }}", "/usr/bin/npm", "${{ steps.other.outputs.npm-executable }}", ""} {
14+
t.Run(scope+"/"+binding, func(t *testing.T) {
15+
t.Parallel()
16+
// Given diagnostics using the same environment variable as production.
17+
contents := replaceOnce(t, validNPMOnlyWorkflow,
18+
" - run: '\""+provisionOutput+"\" --version'",
19+
" - run: '\"$NPM_EXECUTABLE\" --version'")
20+
if scope == "step" {
21+
contents = replaceOnce(t, contents, " - run: '\"$NPM_EXECUTABLE\" --version'",
22+
" - env:\n NPM_EXECUTABLE: \""+binding+"\"\n run: '\"$NPM_EXECUTABLE\" --version'")
23+
} else {
24+
contents = replaceOnce(t, contents, " publish:\n", " publish:\n env:\n NPM_EXECUTABLE: \""+binding+"\"\n")
25+
}
26+
// When checked through the public YAML entry point.
27+
_, err := CheckPublishJob(writeWorkflow(t, contents))
28+
// Then only the exact provisioning output is accepted.
29+
if binding == provisionOutput {
30+
if err != nil {
31+
t.Fatal(err)
32+
}
33+
} else if err == nil || !strings.Contains(err.Error(), "NPM_EXECUTABLE") {
34+
t.Fatalf("binding error = %v, want NPM_EXECUTABLE rejection", err)
35+
}
36+
})
37+
}
38+
}
39+
}
40+
41+
func TestPublishExecutableBindingStepPrecedence(t *testing.T) {
42+
t.Parallel()
43+
for _, binding := range []string{provisionOutput, "${{ vars.AMBIENT_NPM }}", ""} {
44+
t.Run(binding, func(t *testing.T) {
45+
t.Parallel()
46+
// Given a trusted job binding overridden by the publish step.
47+
contents := replaceOnce(t, validNPMOnlyWorkflow, " publish:\n",
48+
" publish:\n env:\n NPM_EXECUTABLE: "+provisionOutput+"\n")
49+
contents = replaceOnce(t, contents, " - id: publish\n",
50+
" - id: publish\n env:\n NPM_EXECUTABLE: \""+binding+"\"\n")
51+
contents = replaceOnce(t, contents, `--npm-executable "`+provisionOutput+`"`, `--npm-executable "${{ env.NPM_EXECUTABLE }}"`)
52+
// When the publish command uses environment indirection.
53+
_, err := CheckPublishJob(writeWorkflow(t, contents))
54+
// Then the step binding wins, including an explicitly empty override.
55+
if (err != nil) != (binding != provisionOutput) {
56+
t.Fatalf("step override error = %v, binding = %q", err, binding)
57+
}
58+
})
59+
}
60+
}

0 commit comments

Comments
 (0)