remit-actions 1__py3-none-any.whl

remit/__init__.py

@@ -0,0 +1,3 @@
+"""Remit: report what a pull request changes about GitHub Actions workflow privileges."""
+
+__version__ = "1"

remit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

remit/cli.py

@@ -0,0 +1,101 @@
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from .report import markdown
+from .sarif import sarif
+from .scan import audit, compare, error_report, permissions
+from .sources import InputError, directory, git_snapshot
+
+
+def _outputs(parser):
+    parser.add_argument("--default-permissions", help='Trusted explicit JSON map, for example {"contents":"read"}')
+    parser.add_argument("--format", choices=("json", "markdown", "sarif"), default="json")
+    parser.add_argument("--output", type=Path)
+    parser.add_argument("--summary", type=Path, help="Explicit path to append a Markdown job summary")
+    parser.add_argument("--sarif", type=Path, help="Also write a SARIF 2.1.0 report to this path")
+
+
+def _defaults(value):
+    if value is None:
+        return None
+    try:
+        defaults = json.loads(value)
+        if not isinstance(defaults, dict):
+            raise ValueError("Explicit map required")
+        return permissions(defaults)
+    except (ValueError, TypeError) as exc:
+        raise InputError("Default permissions must be a supported explicit JSON permission map.") from exc
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="remit")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    scan = commands.add_parser("scan", help="Report what a change does to workflow privileges")
+    source = scan.add_mutually_exclusive_group(required=True)
+    source.add_argument("--dirs", nargs=2, metavar=("BASE_DIR", "HEAD_DIR"))
+    source.add_argument("--repo", help="Local Git repository; reads objects without checkout")
+    scan.add_argument("--base", help="Base ref, resolved and recorded as an exact commit")
+    scan.add_argument("--head", help="Head ref, resolved and recorded as an exact commit")
+    _outputs(scan)
+
+    check = commands.add_parser("audit", help="Report pull request content reachable from privileged workflows now "
+                                              "(WF010, WF011)")
+    target = check.add_mutually_exclusive_group(required=True)
+    target.add_argument("--dir", help="Directory containing .github/workflows")
+    target.add_argument("--repo", help="Local Git repository; reads objects without checkout")
+    check.add_argument("--ref", help="Commit or ref to audit with --repo (default: HEAD)")
+    check.add_argument("--fail-on-findings", action="store_true",
+                       help="Exit 1 when the audit is complete and has findings")
+    _outputs(check)
+
+    args = parser.parse_args(argv)
+    if args.command == "scan":
+        if args.repo and (not args.base or not args.head):
+            parser.error("--repo requires --base and --head")
+        if args.dirs and (args.base or args.head):
+            parser.error("--base and --head are only used with --repo")
+    elif args.dir and args.ref:
+        parser.error("--ref is only used with --repo")
+
+    try:
+        defaults = _defaults(args.default_permissions)
+        if args.command == "audit":
+            snapshot = directory(args.dir) if args.dir else git_snapshot(args.repo, args.ref or "HEAD")
+            result = audit(snapshot, defaults)
+        else:
+            if args.dirs:
+                base, head = (directory(path) for path in args.dirs)
+            else:
+                base = git_snapshot(args.repo, args.base)
+                head = git_snapshot(args.repo, args.head)
+            result = compare(base, head, defaults)
+    except (InputError, OSError) as exc:
+        # Do not echo filesystem errors, source text, credentials, or git stderr.
+        reason = str(exc) if isinstance(exc, InputError) else "Could not read comparison inputs."
+        result = error_report(reason)
+        if args.command == "audit":
+            result["mode"] = "audit"
+
+    if args.format == "markdown":
+        text = markdown(result)
+    else:
+        text = json.dumps(sarif(result) if args.format == "sarif" else result, indent=2, sort_keys=True) + "\n"
+    try:
+        if args.output:
+            args.output.write_text(text, encoding="utf-8")
+        else:
+            sys.stdout.write(text)
+        if args.sarif:
+            args.sarif.write_text(json.dumps(sarif(result), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        if args.summary:
+            with args.summary.open("a", encoding="utf-8") as handle:
+                handle.write(markdown(result))
+    except OSError:
+        print("Could not write report output.", file=sys.stderr)
+        return 2
+    if result["analysis"] != "complete":
+        return 2
+    return 1 if args.command == "audit" and args.fail_on_findings and result["findings"] else 0

remit/contexts.py

@@ -0,0 +1,279 @@
+"""Configured runner/environment changes, without inventory or runtime claims."""
+import re
+from itertools import product
+from .expressions import IDENTIFIER
+
+# A deliberately explicit convention list, not discovery of runner ownership.
+# Unknown/custom labels and groups merit review instead of being called self-hosted.
+HOSTED_LABELS = set("""ubuntu-latest ubuntu-slim ubuntu-22.04 ubuntu-24.04 ubuntu-26.04
+ubuntu-22.04-arm ubuntu-24.04-arm ubuntu-26.04-arm windows-latest windows-2022 windows-2025
+windows-2025-vs2026 windows-11-arm windows-11-vs2026-arm macos-latest macos-13
+macos-14 macos-15 macos-26 xcode-27
+macos-15-intel macos-26-intel macos-14-large macos-14-xlarge macos-15-large
+macos-15-xlarge macos-26-large macos-26-xlarge""".split())
+MAX_MATRIX_ROWS = 256
+MATRIX = re.compile(r"\s*\$\{\{\s*(?i:matrix)\.(" + IDENTIFIER + r")\s*\}\}\s*")
+
+
+def _matrix(job):
+    strategy = (job or {}).get("strategy", {})
+    return strategy.get("matrix") if isinstance(strategy, dict) else None
+
+
+def _is_dynamic(value):
+    if isinstance(value, str):
+        return "${{" in value
+    if isinstance(value, dict):
+        return any(_is_dynamic(x) for x in value.values())
+    if isinstance(value, list):
+        return any(_is_dynamic(x) for x in value)
+    return False
+
+
+def _matrix_rows(matrix):
+    """Expand a small literal matrix using GitHub's exclude/include ordering.
+
+    Returns None when the matrix is dynamic, malformed, ambiguous or too large.
+    """
+    def fields(mapping):
+        # Matrix variable names are case-insensitive; reject case-only duplicates.
+        folded = {key.casefold(): value for key, value in mapping.items()}
+        return folded if len(folded) == len(mapping) else None
+
+    if _is_dynamic(matrix):
+        return None
+    axes = fields({k: v for k, v in matrix.items() if k not in ("include", "exclude")})
+    include, exclude = matrix.get("include", []), matrix.get("exclude", [])
+    if axes is None or any(not isinstance(v, list) or not v for v in axes.values()):
+        return None
+    for items in (include, exclude):
+        if not isinstance(items, list) or len(items) > MAX_MATRIX_ROWS:
+            return None
+        if any(not isinstance(x, dict) for x in items):
+            return None
+    include = [fields(item) for item in include]
+    exclude = [fields(item) for item in exclude]
+    if any(item is None for item in include + exclude):
+        return None
+    size = 1
+    for values in axes.values():
+        size *= len(values)
+        if size > MAX_MATRIX_ROWS:
+            return None
+
+    originals = [dict(zip(axes, values)) for values in product(*axes.values())] if axes else []
+    originals = [row for row in originals
+                 if not any(all(k in row and row[k] == v for k, v in item.items()) for item in exclude)]
+    rows = [row.copy() for row in originals]
+    appended = []
+    for item in include:
+        # An include entry extends every original row it does not contradict;
+        # otherwise it becomes a new row.
+        matched = False
+        for original, row in zip(originals, rows):
+            if all(k not in original or original[k] == v for k, v in item.items()):
+                row.update(item)
+                matched = True
+        if not matched:
+            appended.append(item.copy())
+    rows += appended
+    return rows if len(rows) <= MAX_MATRIX_ROWS else None
+
+
+def _options(value, job):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("Runner/environment selectors must be nonempty strings.")
+    if "${{" not in value:
+        return [value], False
+    match = MATRIX.fullmatch(value)
+    matrix = _matrix(job)
+    if not match or not isinstance(matrix, dict):
+        return [], True
+    field = match.group(1).casefold()
+    rows = _matrix_rows(matrix)
+    if not rows or any(field not in row for row in rows):
+        return [], True
+    values = [row[field] for row in rows]
+    if not values or any(not isinstance(x, str) or not x.strip() or "${{" in x for x in values):
+        return [], True
+    return values, False
+
+
+def _runner(job):
+    if not job or "runs-on" not in job:
+        return {"labels": [], "groups": []}, False
+    value = job["runs-on"]
+    groups = []
+    unknown = False
+    if isinstance(value, dict):
+        if not value or set(value) - {"group", "labels"}:
+            raise ValueError("Unsupported runs-on mapping.")
+        if "group" in value:
+            groups, unknown = _options(value["group"], job)
+        value = value.get("labels", [])
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list):
+        raise ValueError("Unsupported runs-on declaration.")
+    if not value and not groups and not unknown:
+        raise ValueError("Empty runs-on selection.")
+    labels = []
+    for label in value:
+        options, unresolved = _options(label, job)
+        labels.extend(x.casefold() for x in options)
+        unknown |= unresolved
+    return {"labels": sorted(set(labels)), "groups": sorted(set(groups))}, unknown
+
+
+def _environment(job):
+    if not job or "environment" not in job:
+        return {"names": []}, False
+    value = job["environment"]
+    if isinstance(value, dict):
+        if "name" not in value:
+            raise ValueError("Environment mapping needs a name.")
+        value = value["name"]
+    names, unknown = _options(value, job)
+    # Environment names are case insensitive. URL-only edits do not change context.
+    return {"names": sorted({x.casefold() for x in names})}, unknown
+
+
+def _runner_targets(job, *, include_environment=False):
+    """Keep resolved selectors from each matrix row together, never cross-join unions."""
+    if not job or "runs-on" not in job:
+        return []
+    value = job["runs-on"]
+    group = value.get("group") if isinstance(value, dict) else None
+    labels = value.get("labels", []) if isinstance(value, dict) else value
+    if isinstance(labels, str):
+        labels = [labels]
+    environment = job.get("environment") if include_environment else None
+    if isinstance(environment, dict):
+        environment = environment.get("name")
+    selectors = labels + ([group] if group is not None else []) + ([environment] if environment is not None else [])
+    rows = _matrix_rows(_matrix(job)) if any(MATRIX.fullmatch(x) for x in selectors) else [{}]
+    # Called only after the corresponding resolvers established static values.
+    if not rows:
+        raise ValueError("Runner target combinations cannot be resolved.")
+
+    def selected(text, row):
+        match = MATRIX.fullmatch(text)
+        return row[match.group(1).casefold()] if match else text
+
+    targets = set()
+    for row in rows:
+        label_set = tuple(sorted({selected(label, row).casefold() for label in labels}))
+        groups = (selected(group, row),) if group is not None else ()
+        name = selected(environment, row).casefold() if environment is not None else None
+        targets.add((label_set, groups, name))
+    return [{"labels": list(labels), "groups": list(groups),
+             **({"environment": name} if include_environment else {})}
+            for labels, groups, name in sorted(targets)]
+
+
+def _context_selection(job):
+    def selector(value, *, fold=False):
+        match = MATRIX.fullmatch(value)
+        if match:
+            return "matrix", match.group(1).casefold()
+        if "${{" in value:
+            return "expression", value
+        return "literal", value.casefold() if fold else value
+
+    runner = job.get("runs-on")
+    group = runner.get("group") if isinstance(runner, dict) else None
+    labels = runner.get("labels", []) if isinstance(runner, dict) else runner
+    if isinstance(labels, str):
+        labels = [labels]
+    # Normalize syntax without erasing which matrix field each row selects.
+    runner = (tuple(sorted({selector(label, fold=True) for label in labels})),
+              selector(group) if group is not None else None)
+    environment = job.get("environment")
+    if isinstance(environment, dict):
+        environment = environment.get("name")
+    return runner, selector(environment, fold=True), _matrix(job)
+
+
+def _compare_associations(before, after, unresolved):
+    """Close the equal-marginals gap; individual context changes have their own rules."""
+    if not before or not all(field in job for job in (before, after) for field in ("runs-on", "environment")):
+        return [], []
+    if _context_selection(before) == _context_selection(after):
+        return [], []
+    if not unresolved["runs-on"] and _runner_targets(before) != _runner_targets(after):
+        return [], []
+    if any(unresolved.values()):
+        return [], [("incomplete", "Changed runner/environment associations cannot be fully resolved; "
+                                   "only direct static matrix fields are supported.")]
+    old = _runner_targets(before, include_environment=True)
+    new = _runner_targets(after, include_environment=True)
+    if not any(pair not in old for pair in new):
+        return [], []
+    return [{"rule": "WF008", "before": {"pairs": old}, "after": {"pairs": new},
+             "message": "New runner/environment pairing introduced while individual target sets stay unchanged. "
+                        "Review the paired runner and environment-scoped settings; actual access and protection "
+                        "policies are not verified."}], []
+
+
+def compare_contexts(before, after):
+    findings, diagnostics, assumptions = [], [], []
+    unresolved = {}
+    for field, rule, resolve in (("runs-on", "WF005", _runner), ("environment", "WF007", _environment)):
+        try:
+            old, old_unknown = resolve(before)
+            new, new_unknown = resolve(after)
+        except ValueError as exc:
+            diagnostics.append(("error", str(exc)))
+            continue
+        unresolved[field] = old_unknown or new_unknown
+        old_selector, new_selector = (before or {}).get(field), after.get(field)
+        if field == "environment":
+            if isinstance(old_selector, dict):
+                old_selector = old_selector.get("name")
+            if isinstance(new_selector, dict):
+                new_selector = new_selector.get("name")
+        if old_unknown or new_unknown:
+            if old_selector == new_selector and _matrix(before) == _matrix(after):
+                assumptions.append(f"Unchanged unresolved {field} selector/matrix compares symbolically; "
+                                   "external runtime context is assumed fixed and is not observed.")
+                continue
+            diagnostics.append(("incomplete", f"Changed {field} selection cannot be fully resolved; "
+                                              "only direct static matrix fields are supported."))
+            if old_selector == new_selector:
+                # A matrix/context edit does not prove that the unchanged
+                # unresolved selector targets a different resource.
+                continue
+            old = {**old, "unresolved": old_unknown}
+            new = {**new, "unresolved": new_unknown}
+        elif old == new:
+            if field != "runs-on":
+                continue
+            if old_selector == new_selector and _matrix(before) == _matrix(after):
+                continue
+            try:
+                old_targets, new_targets = _runner_targets(before), _runner_targets(after)
+            except ValueError as exc:
+                diagnostics.append(("error", str(exc)))
+                continue
+            if old_targets == new_targets:
+                continue
+            # Equal unions can hide changed label/group combinations. Include
+            # row targets so the finding explains the actual configured change.
+            old, new = {**old, "targets": old_targets}, {**new, "targets": new_targets}
+        if field == "runs-on":
+            if not (old_unknown or new_unknown) and not (new["groups"] or set(new["labels"]) - HOSTED_LABELS):
+                continue
+            message = ("Runner selection changed to a self-hosted, custom/group, or unresolved context. "
+                       "Review infrastructure access; ownership and execution are not verified.")
+        else:
+            message = ("Environment selection changed. Review scoped configuration and approval requirements; "
+                       "secret availability and protection policies are not verified.")
+        findings.append({"rule": rule, "before": old, "after": new, "message": message})
+    if not findings and not diagnostics:
+        try:
+            changes, issues = _compare_associations(before, after, unresolved)
+            findings.extend(changes)
+            diagnostics.extend(issues)
+        except ValueError as exc:
+            diagnostics.append(("error", str(exc)))
+    return findings, diagnostics, assumptions

remit/expressions.py

@@ -0,0 +1,7 @@
+"""Shared lexical boundary for supported GitHub expression property names.
+
+This is not an expression evaluator. Hyphens belong to identifiers, so a
+property such as inputs.use-secrets must never become a secrets context read.
+"""
+
+IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_-]*"