trust-path 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
trust_path/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """trust-path: map paths from untrusted input to secrets in GitHub Actions workflows."""
2
+
3
+ __version__ = "0.1.0"
trust_path/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
trust_path/analyze.py ADDED
@@ -0,0 +1,444 @@
1
+ """Find paths from untrusted input to secrets and credentials in workflows.
2
+
3
+ A path is reported as a Record(source, workflow, job, step, sink). See
4
+ docs/model.md for the rules this module implements.
5
+ """
6
+
7
+ import collections
8
+ import os
9
+ import re
10
+ import subprocess
11
+
12
+ from . import yamlsubset
13
+
14
+ Record = collections.namedtuple("Record", "source workflow job step sink")
15
+
16
+
17
+ class AnalysisError(Exception):
18
+ pass
19
+
20
+
21
+ # Triggers whose runs hold the base repository's secrets and token while the
22
+ # triggering text (titles, bodies, comments, branch names) comes from anyone
23
+ # who can open an issue, comment or pull request.
24
+ UNTRUSTED_TRIGGERS = (
25
+ "discussion", "discussion_comment", "issue_comment", "issues",
26
+ "pull_request_review", "pull_request_review_comment", "pull_request_target",
27
+ )
28
+
29
+ # Upstream triggers that make a downstream `workflow_run` untrusted: the
30
+ # ones above, plus pull_request (fork code and branch names, without secrets
31
+ # upstream, but the downstream run has them).
32
+ UPSTREAM_UNTRUSTED = UNTRUSTED_TRIGGERS + ("pull_request",)
33
+
34
+ # Pull request fields are written by the pull request's author. Under
35
+ # pull_request_review(_comment), runs for fork pull requests get no secrets
36
+ # and a read-only token, so those fields count only under pull_request_target.
37
+ _PR = ("pull_request_target",)
38
+ _REVIEW = ("pull_request_review", "pull_request_review_comment")
39
+ _ISSUE = ("issues", "issue_comment")
40
+ _DISCUSSION = ("discussion", "discussion_comment")
41
+
42
+ # Attacker-controlled contexts, as regular expressions over a normalised
43
+ # context name (indexes written as .*), and the triggers whose event payload
44
+ # carries them.
45
+ UNTRUSTED_CONTEXTS = [
46
+ (r"github\.head_ref", _PR),
47
+ (r"github\.event\.pull_request\.(title|body)", _PR),
48
+ (r"github\.event\.pull_request\.head\.(ref|label|repo\.default_branch)", _PR),
49
+ (r"github\.event\.issue\.(title|body)", _ISSUE),
50
+ (r"github\.event\.comment\.body",
51
+ ("issue_comment", "pull_request_review_comment", "discussion_comment")),
52
+ (r"github\.event\.review\.body", ("pull_request_review",)),
53
+ (r"github\.event\.discussion\.(title|body)", _DISCUSSION),
54
+ (r"github\.event\.workflow_run\.(head_branch|display_title)", ("workflow_run",)),
55
+ (r"github\.event\.workflow_run\.head_commit\.(message|author\.(email|name))",
56
+ ("workflow_run",)),
57
+ (r"github\.event\.workflow_run\.head_repository\.description", ("workflow_run",)),
58
+ (r"github\.event\.workflow_run\.pull_requests\.\*\.head\.ref", ("workflow_run",)),
59
+ # The whole event payload, for example toJSON(github.event).
60
+ (r"github\.event", UNTRUSTED_TRIGGERS + ("workflow_run",)),
61
+ (r"github", UNTRUSTED_TRIGGERS + ("workflow_run",)),
62
+ ]
63
+
64
+ # Values of actions/checkout `ref:` or `repository:` that select the pull
65
+ # request's head (fork) code rather than the base branch.
66
+ HEAD_REFS = re.compile(
67
+ r"head\.sha|head\.ref|head_ref|head_sha|head_branch|head\.repo|head_repository"
68
+ r"|merge_commit_sha|refs/pull/")
69
+ # Shell commands that fetch pull request code.
70
+ HEAD_FETCH = re.compile(r"\bgh\s+pr\s+checkout\b|\bpull/\$\{\{|\brefs/pull/")
71
+
72
+ # AI agent actions: given text, they act with the credentials they hold.
73
+ AGENT_ACTIONS = (
74
+ "actions/ai-inference",
75
+ "anthropics/claude-code-action",
76
+ "anthropics/claude-code-base-action",
77
+ "google-github-actions/run-gemini-cli",
78
+ "openai/codex-action",
79
+ "warpdotdev/oz-agent-action",
80
+ )
81
+
82
+ # Actions that download artifacts from another workflow run.
83
+ ARTIFACT_ACTIONS = ("actions/download-artifact", "dawidd6/action-download-artifact")
84
+
85
+ # Token scopes whose write access is a sink. issues and discussions count
86
+ # because text written there is read by other workflows and AI agents that
87
+ # run on issue and discussion events: injected text can travel on.
88
+ WRITE_SCOPES = ("actions", "contents", "discussions", "id-token", "issues", "packages",
89
+ "pull-requests")
90
+
91
+ _EXPR = re.compile(r"\$\{\{(.*?)\}\}", re.S)
92
+ _CONTEXT = re.compile(
93
+ r"(?<![\w.-])(github|inputs|secrets)((?:\.[A-Za-z_*][\w*-]*|\[[^\]]*\])*)")
94
+
95
+
96
+ def _norm(name):
97
+ """github.event.commits[0].message -> github.event.commits.*.message"""
98
+ return re.sub(r"\[[^\]]*\]", ".*", name)
99
+
100
+
101
+ def contexts(value):
102
+ """Context names (github..., inputs..., secrets...) used inside the
103
+ ${{ }} expressions of a string, a list or a mapping."""
104
+ found = set()
105
+ for text in _strings(value):
106
+ for expr in _EXPR.findall(text):
107
+ # ['name'] indexes become .name; other string literals are dropped.
108
+ expr = re.sub(r"\[\s*'([\w-]+)'\s*\]", r".\1", expr)
109
+ expr = re.sub(r"'[^']*'", "''", expr)
110
+ for m in _CONTEXT.finditer(expr):
111
+ found.add(_norm(m.group(1) + m.group(2)))
112
+ return found
113
+
114
+
115
+ def _strings(value):
116
+ if isinstance(value, str):
117
+ yield value
118
+ elif isinstance(value, dict):
119
+ for k in sorted(value):
120
+ for s in _strings(value[k]):
121
+ yield s
122
+ elif isinstance(value, list):
123
+ for v in value:
124
+ for s in _strings(v):
125
+ yield s
126
+
127
+
128
+ def untrusted(names, trigger, tainted_inputs):
129
+ """The untrusted contexts among `names` for a run started by `trigger`."""
130
+ out = set()
131
+ for name in names:
132
+ if name.startswith("inputs."):
133
+ if name.split(".")[1] in tainted_inputs:
134
+ out.add(name)
135
+ continue
136
+ for pattern, triggers in UNTRUSTED_CONTEXTS:
137
+ if trigger in triggers and re.match(pattern + r"$", name):
138
+ out.add(name)
139
+ break
140
+ return out
141
+
142
+
143
+ def secret_names(value):
144
+ """secrets.NAME references; the whole context (toJSON(secrets) or
145
+ secrets[expr]) is written secrets.*"""
146
+ names = set()
147
+ for name in contexts(value):
148
+ parts = name.split(".")
149
+ if parts[0] == "secrets":
150
+ names.add("secrets." + (parts[1] if len(parts) > 1 else "*"))
151
+ return names
152
+
153
+
154
+ def _action(uses):
155
+ """owner/repo of a `uses:` value, lower-cased; '' for docker:// and ./"""
156
+ if not isinstance(uses, str) or uses.startswith(("docker://", "./")):
157
+ return ""
158
+ return "/".join(uses.split("@")[0].split("/")[:2]).lower()
159
+
160
+
161
+ def triggers_of(wf):
162
+ on = wf.get("on")
163
+ if isinstance(on, str):
164
+ return {on: None}
165
+ if isinstance(on, list):
166
+ return dict((t, None) for t in on if isinstance(t, str))
167
+ if isinstance(on, dict):
168
+ return on
169
+ return {}
170
+
171
+
172
+ def _permissions(perms):
173
+ """Write-scope sinks of a permissions value. None (no permissions key)
174
+ means the repository's default token permissions, which the workflow
175
+ files do not show."""
176
+ if perms is None:
177
+ return {"permissions:default"}
178
+ if perms == "write-all":
179
+ return set("permissions.%s:write" % s for s in WRITE_SCOPES)
180
+ if isinstance(perms, dict):
181
+ return set("permissions.%s:write" % s for s in WRITE_SCOPES if perms.get(s) == "write")
182
+ return set()
183
+
184
+
185
+ def _label(step, index):
186
+ for key in ("name", "id", "uses"):
187
+ if isinstance(step.get(key), str) and step[key].strip():
188
+ return step[key]
189
+ return "step %d" % (index + 1)
190
+
191
+
192
+ def _check(doc):
193
+ """Refuse a document that is not a workflow this module can walk."""
194
+ if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):
195
+ raise AnalysisError("not a workflow (no 'jobs' mapping)")
196
+ for job_id, job in sorted(doc["jobs"].items()):
197
+ if not isinstance(job, dict):
198
+ raise AnalysisError("job %r is not a mapping" % job_id)
199
+ if not isinstance(job.get("steps") or [], list):
200
+ raise AnalysisError("steps of job %r are not a list" % job_id)
201
+ return doc
202
+
203
+
204
+ Context = collections.namedtuple(
205
+ "Context", "chain trigger tainted_inputs secrets_allowed caller_permissions")
206
+
207
+
208
+ def _git(root, *args):
209
+ """Run git in root without a shell and return its standard output."""
210
+ try:
211
+ p = subprocess.run(["git"] + list(args), cwd=root, stdout=subprocess.PIPE,
212
+ stderr=subprocess.PIPE, env=dict(os.environ, LC_ALL="C"))
213
+ except OSError as e:
214
+ raise AnalysisError("cannot run git: %s" % e)
215
+ if p.returncode:
216
+ message = p.stderr.decode("utf-8", "replace").strip().splitlines()
217
+ raise AnalysisError(message[-1] if message else "git %s failed" % args[0])
218
+ return p.stdout
219
+
220
+
221
+ def _git_reader(root, ref):
222
+ """name -> function returning the text of each file directly in
223
+ .github/workflows at ref, read from git without a checkout."""
224
+ try:
225
+ _git(root, "rev-parse", "--git-dir")
226
+ except AnalysisError:
227
+ raise AnalysisError("%s: not a git repository" % root)
228
+ try:
229
+ if ref.startswith("-"):
230
+ raise AnalysisError(ref)
231
+ commit = _git(root, "rev-parse", "--verify", "--quiet", ref + "^{commit}")
232
+ except AnalysisError:
233
+ raise AnalysisError("unknown ref %s" % ref)
234
+ listing = _git(root, "ls-tree", "-z", "--full-tree", commit.decode().strip(), "--",
235
+ ".github/workflows/")
236
+ files = {}
237
+ for entry in listing.split(b"\0"):
238
+ if not entry:
239
+ continue
240
+ meta, path = entry.split(b"\t", 1)
241
+ mode, kind, oid = meta.decode().split(" ")
242
+ name = path.decode("utf-8", "replace").split("/")[-1]
243
+ if kind != "blob":
244
+ continue
245
+ if mode == "120000":
246
+ files[name] = None
247
+ else:
248
+ files[name] = lambda oid=oid: _git(root, "cat-file", "blob", oid).decode("utf-8")
249
+ return files
250
+
251
+
252
+ def _dir_reader(root):
253
+ """name -> function returning the text of each file directly in
254
+ DIR/.github/workflows."""
255
+ if not os.path.isdir(root):
256
+ raise AnalysisError("%s: not a directory" % root)
257
+ wdir = os.path.join(root, ".github", "workflows")
258
+
259
+ def read(name):
260
+ with open(os.path.join(wdir, name), encoding="utf-8") as f:
261
+ return f.read()
262
+ names = os.listdir(wdir) if os.path.isdir(wdir) else []
263
+ return dict((name, lambda name=name: read(name)) for name in names)
264
+
265
+
266
+ class Repo(object):
267
+ """The readable workflows of a repository, from the directory or, with
268
+ `ref`, from git at that ref. Files that cannot be read are listed in
269
+ `refused` as sorted (file, reason) pairs and left out."""
270
+
271
+ def __init__(self, root, ref=None):
272
+ self.root = root
273
+ self.workflows = {}
274
+ refused = {}
275
+ files = _dir_reader(root) if ref is None else _git_reader(root, ref)
276
+ for name in sorted(files):
277
+ if not name.endswith((".yml", ".yaml")):
278
+ continue
279
+ rel = ".github/workflows/" + name
280
+ if files[name] is None:
281
+ refused[rel] = "a symbolic link, not read"
282
+ continue
283
+ try:
284
+ self.workflows[rel] = _check(yamlsubset.load(files[name]()))
285
+ except yamlsubset.YamlError as e:
286
+ refused[rel] = "line %d: %s" % (e.line, e.message)
287
+ except AnalysisError as e:
288
+ refused[rel] = str(e)
289
+ except (OSError, UnicodeDecodeError) as e:
290
+ refused[rel] = str(e)
291
+ # A call to a local reusable workflow that does not exist refuses the
292
+ # caller; a call to one that was refused is skipped when analysing.
293
+ for rel in sorted(self.workflows):
294
+ for job_id, job in sorted(self.workflows[rel]["jobs"].items()):
295
+ uses = job.get("uses")
296
+ if isinstance(uses, str) and uses.startswith("./"):
297
+ target = uses[2:].split("@")[0]
298
+ if target not in self.workflows and target not in refused:
299
+ refused[rel] = "job %r calls %s, which is not in %s" % (
300
+ job_id, uses, ".github/workflows")
301
+ for rel in refused:
302
+ self.workflows.pop(rel, None)
303
+ self.refused = sorted(refused.items())
304
+
305
+ def name_of(self, rel):
306
+ name = self.workflows[rel].get("name")
307
+ return name if isinstance(name, str) else rel
308
+
309
+ def contexts_for(self, rel, seen=()):
310
+ """Every untrusted context a workflow can run in, through its own
311
+ triggers or a chain of workflow_run triggers."""
312
+ out = []
313
+ triggers = triggers_of(self.workflows[rel])
314
+ for t in sorted(triggers):
315
+ if t in UNTRUSTED_TRIGGERS:
316
+ out.append(Context(t, t, frozenset(), None, None))
317
+ run = triggers.get("workflow_run")
318
+ if "workflow_run" in triggers:
319
+ wanted = run.get("workflows") if isinstance(run, dict) else None
320
+ wanted = [wanted] if isinstance(wanted, str) else (wanted or [])
321
+ for upstream in sorted(set(w for w in wanted if isinstance(w, str))):
322
+ matches = [r for r in sorted(self.workflows) if self.name_of(r) == upstream]
323
+ if not matches:
324
+ out.append(Context("unknown@%s>workflow_run" % upstream,
325
+ "workflow_run", frozenset(), None, None))
326
+ for up in matches:
327
+ if up in seen or up == rel:
328
+ continue
329
+ for t in sorted(triggers_of(self.workflows[up])):
330
+ if t in UPSTREAM_UNTRUSTED:
331
+ out.append(Context("%s@%s>workflow_run" % (t, up), "workflow_run",
332
+ frozenset(), None, None))
333
+ for ctx in self.contexts_for(up, seen + (rel,)):
334
+ if ctx.trigger == "workflow_run":
335
+ out.append(Context("%s@%s>workflow_run" % (ctx.chain, up),
336
+ "workflow_run", frozenset(), None, None))
337
+ return out
338
+
339
+ def analyse(self):
340
+ records = set()
341
+ for rel in sorted(self.workflows):
342
+ for ctx in self.contexts_for(rel):
343
+ self._workflow(rel, ctx, records, ())
344
+ return sorted(records)
345
+
346
+ def _workflow(self, rel, ctx, records, stack):
347
+ wf = self.workflows[rel]
348
+ for job_id in sorted(wf["jobs"]):
349
+ job = wf["jobs"][job_id]
350
+ if isinstance(job.get("uses"), str):
351
+ self._call(rel, job_id, job, ctx, records, stack)
352
+ else:
353
+ self._job(rel, wf, job_id, job, ctx, records)
354
+
355
+ def _job(self, rel, wf, job_id, job, ctx, records):
356
+ steps = [s if isinstance(s, dict) else {} for s in job.get("steps") or []]
357
+ shared_env = [wf.get("env"), job.get("env")]
358
+
359
+ def allowed(names):
360
+ if ctx.secrets_allowed is None:
361
+ return names
362
+ return set(n for n in names if n == "secrets.GITHUB_TOKEN"
363
+ or n[len("secrets."):] in ctx.secrets_allowed
364
+ or (n == "secrets.*" and ctx.secrets_allowed))
365
+
366
+ perms = job["permissions"] if "permissions" in job else wf.get(
367
+ "permissions", ctx.caller_permissions)
368
+ job_sinks = _permissions(perms)
369
+ env = job.get("environment")
370
+ env = env.get("name") if isinstance(env, dict) else env
371
+ if isinstance(env, str):
372
+ job_sinks.add("environment:" + env)
373
+ job_sinks |= allowed(secret_names(shared_env))
374
+
375
+ # Where untrusted input enters the job: (step index, source).
376
+ entries = set()
377
+ if steps:
378
+ for name in untrusted(contexts(shared_env), ctx.trigger, ctx.tainted_inputs):
379
+ entries.add((0, name))
380
+ for i, step in enumerate(steps):
381
+ fields = [step.get("run"), step.get("with"), step.get("env")]
382
+ for name in untrusted(contexts(fields), ctx.trigger, ctx.tainted_inputs):
383
+ entries.add((i, name))
384
+ action = _action(step.get("uses"))
385
+ with_ = step.get("with") if isinstance(step.get("with"), dict) else {}
386
+ head = ctx.trigger not in _REVIEW
387
+ if head and action == "actions/checkout" and any(
388
+ isinstance(with_.get(k), str) and HEAD_REFS.search(with_[k])
389
+ for k in ("ref", "repository")):
390
+ entries.add((i, "checkout of pull request head"))
391
+ if head and isinstance(step.get("run"), str) and HEAD_FETCH.search(step["run"]):
392
+ entries.add((i, "fetch of pull request head"))
393
+ if ctx.trigger == "workflow_run" and action in ARTIFACT_ACTIONS:
394
+ entries.add((i, "artifact from upstream run"))
395
+ if action in AGENT_ACTIONS:
396
+ entries.add((i, "event text read by agent"))
397
+
398
+ for start, what in sorted(entries):
399
+ source = "%s:%s" % (ctx.chain, what)
400
+ for sink in job_sinks:
401
+ records.add(Record(source, rel, job_id, _label(steps[start], start), sink))
402
+ for i in range(start, len(steps)):
403
+ step = steps[i]
404
+ held = allowed(secret_names([step.get("run"), step.get("with"),
405
+ step.get("env")]))
406
+ for sink in held:
407
+ records.add(Record(source, rel, job_id, _label(step, i), sink))
408
+ action = _action(step.get("uses"))
409
+ credential = held or job_sinks & {"permissions.id-token:write"} or \
410
+ allowed(secret_names(shared_env))
411
+ if action in AGENT_ACTIONS and credential:
412
+ records.add(Record(source, rel, job_id, _label(step, i), "agent:" + action))
413
+
414
+ def _call(self, rel, job_id, job, ctx, records, stack):
415
+ uses = job["uses"]
416
+ with_ = job.get("with") if isinstance(job.get("with"), dict) else {}
417
+ tainted = frozenset(k for k in sorted(with_) if untrusted(
418
+ contexts(with_[k]), ctx.trigger, ctx.tainted_inputs))
419
+ secrets = job.get("secrets")
420
+ if secrets == "inherit":
421
+ passed = None if ctx.secrets_allowed is None else ctx.secrets_allowed
422
+ elif isinstance(secrets, dict):
423
+ passed = frozenset(secrets)
424
+ else:
425
+ passed = frozenset()
426
+ perms = job["permissions"] if "permissions" in job else self.workflows[rel].get(
427
+ "permissions", ctx.caller_permissions)
428
+ if not uses.startswith("./"):
429
+ # A workflow in another repository: report what is handed to it.
430
+ if tainted:
431
+ sinks = ["secrets:inherit"] if secrets == "inherit" else sorted(
432
+ secret_names(secrets))
433
+ sinks += sorted(_permissions(perms))
434
+ for name in sorted(tainted):
435
+ for sink in sinks:
436
+ records.add(Record("%s:%s" % (ctx.chain, "with." + name), rel, job_id,
437
+ uses, sink))
438
+ return
439
+ target = uses[2:].split("@")[0]
440
+ if target not in self.workflows or target in stack:
441
+ return
442
+ inner = Context("%s@%s>workflow_call" % (ctx.chain, rel), ctx.trigger, tainted,
443
+ passed, perms)
444
+ self._workflow(target, inner, records, stack + (rel,))
trust_path/cli.py ADDED
@@ -0,0 +1,58 @@
1
+ """Command line: trust-path [--json] [--ref REF] DIR"""
2
+
3
+ import argparse
4
+ import json
5
+ import sys
6
+
7
+ from . import __version__
8
+ from .analyze import AnalysisError, Repo
9
+
10
+ FIELDS = ("source", "workflow", "job", "step", "sink")
11
+
12
+
13
+ def _clean(text):
14
+ """Keep each record on one line with exactly five fields."""
15
+ return " ".join(str(text).replace("\t", " ").split())
16
+
17
+
18
+ def main(argv=None):
19
+ parser = argparse.ArgumentParser(
20
+ prog="trust-path",
21
+ description="List the paths by which untrusted input (pull request titles, issue "
22
+ "bodies, comments, fork code) can reach a secret, an OIDC token, a write "
23
+ "permission, an environment or an AI agent action in the GitHub Actions "
24
+ "workflows under DIR/.github/workflows. Exit status: 0 no path, 1 paths "
25
+ "found, 2 error.")
26
+ parser.add_argument("dir", metavar="DIR", nargs="?",
27
+ help="a repository checkout (with --ref, a git repository; default .)")
28
+ parser.add_argument("--ref", metavar="REF",
29
+ help="read the workflows from git at REF (a branch, tag or commit) "
30
+ "instead of from the files in DIR, without checking it out")
31
+ parser.add_argument("--json", action="store_true", help="write a JSON array of records")
32
+ parser.add_argument("--version", action="version", version="trust-path " + __version__)
33
+ args = parser.parse_args(argv)
34
+ if args.dir is None and args.ref is None:
35
+ parser.error("DIR is required without --ref")
36
+ try:
37
+ repo = Repo(args.dir or ".", args.ref)
38
+ records = repo.analyse()
39
+ except AnalysisError as e:
40
+ sys.stderr.write("trust-path: %s\n" % e)
41
+ return 2
42
+ rows = [[_clean(v) for v in r] for r in records]
43
+ rows = sorted(set(tuple(r) for r in rows))
44
+ if args.json:
45
+ json.dump([dict(zip(FIELDS, r)) for r in rows], sys.stdout, indent=2, sort_keys=True)
46
+ sys.stdout.write("\n")
47
+ else:
48
+ for r in rows:
49
+ sys.stdout.write("\t".join(r) + "\n")
50
+ for rel, reason in repo.refused:
51
+ sys.stderr.write("trust-path: %s: %s\n" % (rel, _clean(reason)))
52
+ if repo.refused:
53
+ return 2
54
+ return 1 if rows else 0
55
+
56
+
57
+ if __name__ == "__main__":
58
+ sys.exit(main())