1212 restated here, so a row reordered or reworded on either side fails.
1313* :class:`TestWorkflowSafety` -- the workflow runs on ``pull_request_target`` with
1414 a secret in scope, so it must never check out code, never splice an expression
15- into a ``run:`` script or a ``shell:`` command, and never read the event payload outside ``env:`` beyond
15+ into a ``run:`` script, a ``shell:`` command, a Docker ``options:`` string or a
16+ ``working-directory:``, and never read the event payload outside ``env:`` beyond
1617 the item number. Asserted over the file, because nothing at run time would
1718 announce the mistake. :class:`TestScannerFailsClosed` holds the line scan those
1819 assertions read to refusing any YAML it cannot read with certainty.
@@ -194,6 +195,26 @@ def strip_comments(text: 'str') -> 'str':
194195#: it (#1068).
195196SHELL_EVALUATED = frozenset ({'run' , 'shell' })
196197
198+ #: Path suffixes whose value reaches a command line other than the script:
199+ #: ``container.options`` and ``services.<id>.options`` are passed to
200+ #: ``docker create``, so an expression there can add flags such as ``--privileged``,
201+ #: and ``working-directory`` sets where the script runs (#1077). Matched by suffix
202+ #: rather than by last key, because ``options`` and ``working-directory`` are also
203+ #: legal ``env:`` names, and ``env:`` is the safe channel for a value.
204+ SPLICED_SUFFIXES = (('container' , 'options' ), ('steps' , 'working-directory' ),
205+ ('run' , 'working-directory' ))
206+
207+
208+ def expression_spliced (path : 'tuple[str, ...]' ) -> 'bool' :
209+ """Whether a ``${{ }}`` at ``path`` is substituted into a command before it runs."""
210+ if path [- 1 :] and path [- 1 ] in SHELL_EVALUATED :
211+ return True
212+ if path [- 2 :] in SPLICED_SUFFIXES :
213+ return True
214+ # ``services.<id>.options``: the service id sits between the two keys.
215+ return len (path ) >= 3 and path [- 3 ] == 'services' and path [- 1 ] == 'options'
216+
217+
197218_KEY_RE = re .compile (r'''(?P<key>[\w-]+|'[^']*'|"[^"\\]*"):(?:[ ]+(?P<rest>.*))?$''' )
198219_BLOCK_INDICATORS = {'|' , '|-' , '|+' , '>' , '>-' , '>+' }
199220#: Characters a plain scalar may not start with: anchors, aliases, tags, flow
@@ -228,20 +249,20 @@ def _scalar(value: 'str', lineno: 'int') -> 'str':
228249def scan (text : 'str' ) -> 'list[tuple[tuple[str, ...], str]]' :
229250 """Every scalar in a workflow, as ``(key path, value)``; list indices dropped.
230251
231- A line scan rather than a YAML parser, because :mod:`yaml` is in no extra of
232- :file:`pyproject.toml` and this check has to run everywhere.
233- :class:`TestYAMLAgreesWithTheScanner` holds it to :func:`yaml.safe_load`
234- wherever PyYAML is installed. It understands the subset these workflows use:
235- block mappings, ``- `` sequence items, block scalars (``|``, ``>`` and their
236- chomping forms), one-line quoted and plain scalars, ``{}``, and flow sequences
237- of such scalars.
252+ A line scan rather than a YAML parser, because it is the guard and a guard
253+ must not depend on an optional import: it runs wherever the tests run, and
254+ :class:`TestYAMLAgreesWithTheScanner` is the cross-check, holding it to
255+ :func:`yaml.safe_load` wherever PyYAML is installed. It understands the
256+ subset these workflows use: block mappings, ``- `` sequence items, block
257+ scalars (``|``, ``>`` and their chomping forms), one-line quoted and plain
258+ scalars, ``{}``, and flow sequences of such scalars.
238259
239260 It *fails closed*: any line outside that subset raises :exc:`UnsupportedYAML`
240261 rather than being read as something it is not. A value the scan misreads is a
241262 ``run:`` script the safety tests never see -- a flow-mapping step, ``run :``,
242- ``run: |2``, or ``run: *alias`` all were (#1060) -- and CI has no PyYAML to
243- catch the disagreement, so refusing is the only answer that cannot pass
244- vacuously.
263+ ``run: |2``, or ``run: *alias`` all were (#1060) -- and a run without PyYAML
264+ has nothing to catch the disagreement, so refusing is the only answer that
265+ cannot pass vacuously.
245266
246267 """
247268 lines = text .splitlines ()
@@ -371,10 +392,11 @@ def test_nothing_from_the_pull_request_head(self) -> None:
371392 def test_no_expression_inside_a_run_script (self ) -> None :
372393 # An expression is substituted into the script text before the shell sees
373394 # it, so a PR title containing `'; curl … | sh #` becomes code. Values
374- # reach the script through `env:` only. `shell:` is spliced the same way.
395+ # reach the script through `env:` only. `shell:`, Docker `options:` and
396+ # `working-directory:` are spliced the same way.
375397 self .assertTrue ([path for path , _ in self .pairs if path [- 1 ] == 'run' ],
376398 'the scanner found no run: block to check' )
377- guarded = [(path , value ) for path , value in self .pairs if path [ - 1 ] in SHELL_EVALUATED ]
399+ guarded = [(path , value ) for path , value in self .pairs if expression_spliced ( path ) ]
378400 for path , value in guarded :
379401 with self .subTest (path = '.' .join (path )):
380402 self .assertNotIn ('${{' , value )
@@ -468,13 +490,46 @@ def test_nothing_is_cancelled(self) -> None:
468490 f' env:\n X: { _INPUT } \n run: echo "$X"\n ' )
469491
470492
493+ def _spliced_key_fixtures (value : 'str' ) -> 'dict[str, tuple[str, tuple[str, ...]]]' :
494+ """A workflow per :data:`SPLICED_SUFFIXES` key holding ``value``, with its path."""
495+ return {
496+ 'container options' : (f'jobs:\n j:\n container:\n image: alpine\n '
497+ f' options: { value } \n ' ,
498+ ('jobs' , 'j' , 'container' , 'options' )),
499+ 'service options' : (f'jobs:\n j:\n services:\n db:\n image: postgres\n '
500+ f' options: { value } \n ' ,
501+ ('jobs' , 'j' , 'services' , 'db' , 'options' )),
502+ 'step working-directory' : (f'{ _STEPS } - name: x\n '
503+ f' working-directory: { value } \n run: echo\n ' ,
504+ ('jobs' , 'j' , 'steps' , 'working-directory' )),
505+ 'defaults working-directory' : (f'defaults:\n run:\n working-directory: { value } \n ' ,
506+ ('defaults' , 'run' , 'working-directory' )),
507+ 'job defaults working-directory' : (f'jobs:\n j:\n defaults:\n run:\n '
508+ f' working-directory: { value } \n ' ,
509+ ('jobs' , 'j' , 'defaults' , 'run' , 'working-directory' )),
510+ }
511+
512+
513+ #: An expression in each key Docker or the runner splices into a command line
514+ #: (#1077). Each is in the subset :func:`scan` reads, so it must trip the guard
515+ #: rather than be refused.
516+ SPLICED_BYPASSES = _spliced_key_fixtures (f'--cpus 1 { _INPUT } ' )
517+
518+ #: The same keys holding a literal, which must pass.
519+ SPLICED_SAFE = _spliced_key_fixtures ('--cpus 1' )
520+
521+ #: An ``env:`` name that matches a guarded key but is the safe channel, so the
522+ #: guard must not trip on it.
523+ ENV_NAMED_OPTIONS = f'{ _STEPS } - name: x\n env:\n options: { _INPUT } \n run: echo\n '
524+
525+
471526def guard_trips (text : 'str' ) -> 'bool' :
472527 """Whether :meth:`TestWorkflowSafety.test_no_expression_inside_a_run_script` fails on ``text``."""
473528 try :
474529 pairs = scan (text )
475530 except UnsupportedYAML :
476531 return True
477- return any (path and path [ - 1 ] in SHELL_EVALUATED and '${{' in value for path , value in pairs )
532+ return any (path and expression_spliced ( path ) and '${{' in value for path , value in pairs )
478533
479534
480535class TestScannerFailsClosed (unittest .TestCase ):
@@ -509,6 +564,24 @@ def test_the_safe_shell_form_is_read(self) -> None:
509564 self .assertIn ((('jobs' , 'j' , 'steps' , 'env' , 'X' ), _INPUT ), pairs )
510565 self .assertFalse (guard_trips (_STEPS + SHELL_SAFE ))
511566
567+ def test_an_expression_in_each_spliced_key_trips_the_guard (self ) -> None :
568+ for form , (text , path ) in SPLICED_BYPASSES .items ():
569+ with self .subTest (form = form ):
570+ pairs = scan (text )
571+ self .assertIn ((path , f'--cpus 1 { _INPUT } ' ), pairs )
572+ self .assertEqual (payload_outside_env (pairs ), [])
573+ self .assertTrue (guard_trips (text ), f'the expression in { path [- 1 ]} : went unseen' )
574+
575+ def test_a_literal_in_each_spliced_key_is_read (self ) -> None :
576+ for form , (text , path ) in SPLICED_SAFE .items ():
577+ with self .subTest (form = form ):
578+ self .assertIn ((path , '--cpus 1' ), scan (text ))
579+ self .assertFalse (guard_trips (text ))
580+
581+ def test_an_env_name_matching_a_spliced_key_is_not_guarded (self ) -> None :
582+ self .assertIn ((('jobs' , 'j' , 'steps' , 'env' , 'options' ), _INPUT ), scan (ENV_NAMED_OPTIONS ))
583+ self .assertFalse (guard_trips (ENV_NAMED_OPTIONS ))
584+
512585 def test_the_workflow_is_inside_the_subset (self ) -> None :
513586 self .assertTrue (scan (WORKFLOW .read_text (encoding = 'utf-8' )))
514587
@@ -529,7 +602,7 @@ def yaml_pairs(node, path=()):
529602class TestYAMLAgreesWithTheScanner (unittest .TestCase ):
530603 """The hand-rolled :func:`scan` reads the workflow as PyYAML does.
531604
532- No CI job installs PyYAML, so this class skips there . It is a cross-check and
605+ The class skips where PyYAML is not installed . It is a cross-check and
533606 not the guard: :class:`TestScannerFailsClosed` is what holds without it.
534607
535608 """
@@ -564,6 +637,17 @@ def test_the_shell_fixtures_are_real(self) -> None:
564637 self .assertIn ((('jobs' , 'j' , 'steps' , 'shell' ), want ),
565638 list (yaml_pairs (yaml .safe_load (_STEPS + step ))))
566639
640+ def test_the_spliced_key_fixtures_are_real (self ) -> None :
641+ import yaml
642+ fixtures = [(text , path , f'--cpus 1 { _INPUT } ' ) for text , path in SPLICED_BYPASSES .values ()]
643+ fixtures += [(text , path , '--cpus 1' ) for text , path in SPLICED_SAFE .values ()]
644+ fixtures .append ((ENV_NAMED_OPTIONS , ('jobs' , 'j' , 'steps' , 'env' , 'options' ), _INPUT ))
645+ for text , path , want in fixtures :
646+ with self .subTest (text = text ):
647+ pairs = list (yaml_pairs (yaml .safe_load (text )))
648+ self .assertIn ((path , want ), pairs )
649+ self .assertEqual (sorted (scan (text )), sorted (pairs ))
650+
567651 def test_no_step_uses_an_action (self ) -> None :
568652 self .assertIn ('pull_request_target' , self .doc .get ('on' , self .doc .get (True )))
569653 for name , job in self .doc ['jobs' ].items ():
0 commit comments