|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""org_settings_audit.py: read-only audit of GitHub org settings, then each repo's. |
| 3 | +
|
| 4 | +WHY: branch protection, required 2FA, Actions token defaults, installed apps and self-hosted runners are not visible in |
| 5 | +code, yet they decide whether a review gate means anything (the CIS GitHub benchmark covers them). Per repository this |
| 6 | +reuses `repo_settings_audit.audit` unchanged (branch protection and rulesets, Actions, collaborators, deploy keys, |
| 7 | +webhooks, environments, secret scanning and push protection); this file adds the organization-level checks: |
| 8 | + 2FA `two_factor_requirement_enabled` on the organization (owner token only) |
| 9 | + Actions organization default workflow token has write, workflows can approve reviews, allowed actions = all |
| 10 | + apps installed GitHub Apps holding admin or write on repository administration or contents (count) |
| 11 | + outside people outside collaborators (count) |
| 12 | + self-hosted organization-level self-hosted runners (count) |
| 13 | +A 403 or 404, a missing field or an odd reply is a `not checked` row that names the token scope or permission it needs, |
| 14 | +never a pass. |
| 15 | +
|
| 16 | +USAGE: org_settings_audit.py ORG [--max-repos N] [--token-env VAR] [--json] |
| 17 | +
|
| 18 | +Token: the env var named by --token-env, else `gh auth token`; it reaches curl on stdin only (never argv), as in |
| 19 | +org_leak_sweep.py. `GITHUB_API_URL` overrides https://api.github.com (tests point it at a stub). |
| 20 | +Output: `{"org": rows, "repos": {"OWNER/NAME": rows}, "summary": {...}}` with `--json`, else one table. |
| 21 | +Exit codes: 0 the audit ran (findings do not change it), 2 usage or no token. |
| 22 | +Side effects: HTTP GET only; nothing is written or changed. Counts and booleans only: no login, app name or API text. |
| 23 | +Limits: first --max-repos repositories (default 200); a longer org says so in a not-checked row. |
| 24 | +""" |
| 25 | +from __future__ import annotations |
| 26 | + |
| 27 | +import argparse |
| 28 | +import json |
| 29 | +import os |
| 30 | +import re |
| 31 | +import subprocess |
| 32 | +import sys |
| 33 | +import urllib.parse |
| 34 | + |
| 35 | +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) |
| 36 | +import repo_settings_audit as rsa # noqa: E402 |
| 37 | + |
| 38 | +API = "https://api.github.com" |
| 39 | +ORG = re.compile(r"[A-Za-z0-9][A-Za-z0-9-]*") |
| 40 | + |
| 41 | + |
| 42 | +def curl_get(token): |
| 43 | + """get(path, params=None) -> parsed JSON over curl; failure raises OSError('... (HTTP n)') for `rsa.why`.""" |
| 44 | + def get(path, params=None): |
| 45 | + url = os.environ.get("GITHUB_API_URL", API) + path + ("?" + urllib.parse.urlencode(params) if params else "") |
| 46 | + cfg = 'header = "Authorization: Bearer ' + token.replace("\\", "\\\\").replace('"', '\\"') + '"\n' |
| 47 | + r = subprocess.run(["curl", "-sS", "-w", "\n%{http_code}", "-H", "Accept: application/vnd.github+json", |
| 48 | + "--config", "-", url], input=cfg, capture_output=True, text=True, errors="replace") |
| 49 | + body, _, code = r.stdout.rpartition("\n") |
| 50 | + if r.returncode or not code.isdigit(): |
| 51 | + raise OSError("API error") |
| 52 | + if int(code) >= 400: |
| 53 | + try: |
| 54 | + msg = str(json.loads(body).get("message", "")) |
| 55 | + except (ValueError, AttributeError): |
| 56 | + msg = "" |
| 57 | + raise OSError("%s (HTTP %s)" % (msg, code)) |
| 58 | + return json.loads(body) |
| 59 | + return get |
| 60 | + |
| 61 | + |
| 62 | +def need(scope): |
| 63 | + return ("needs " + scope, "re-run with a token that has " + scope) |
| 64 | + |
| 65 | + |
| 66 | +def org_rows(get, org): |
| 67 | + """(check, severity, fix) tuples for the organization itself; any failed read is a not-checked row.""" |
| 68 | + base, rows = "/orgs/" + org, [] |
| 69 | + o, e = rsa.read(get, base, dict) |
| 70 | + if e: |
| 71 | + return [rsa.nc("organization", rsa.why(e, need("read access to the organization")))] |
| 72 | + tf = o.get("two_factor_requirement_enabled") # absent unless the token is an org owner |
| 73 | + if tf is None: |
| 74 | + rows.append(rsa.nc("2FA requirement", need("owner access (admin:org)"))) |
| 75 | + elif tf is not True: |
| 76 | + rows.append(("2FA requirement is off", "high", "enable 'Require two-factor authentication' in the organization security settings")) |
| 77 | + adm = "admin:org (fine-grained: Administration read)" |
| 78 | + w, e = rsa.read(get, base + "/actions/permissions/workflow", dict, |
| 79 | + need=(("default_workflow_permissions",), ("can_approve_pull_request_reviews",))) |
| 80 | + if e: |
| 81 | + rows.append(rsa.nc("org Actions token", rsa.why(e, need(adm)))) |
| 82 | + else: |
| 83 | + if w["default_workflow_permissions"] == "write": |
| 84 | + rows.append(("org default workflow token can write", "medium", "set the organization default workflow permissions to read")) |
| 85 | + if w["can_approve_pull_request_reviews"] is True: |
| 86 | + rows.append(("org workflows can approve pull request reviews", "medium", "turn off 'Allow GitHub Actions to create and approve pull requests'")) |
| 87 | + a, e = rsa.read(get, base + "/actions/permissions", dict, need=(("enabled_repositories",),)) |
| 88 | + if e: |
| 89 | + rows.append(rsa.nc("org allowed actions", rsa.why(e, need(adm)))) |
| 90 | + elif a.get("allowed_actions") == "all": |
| 91 | + rows.append(("org allows all actions", "medium", "restrict allowed actions to GitHub-owned and an allowlist")) |
| 92 | + ins, e = rsa.read(get, base + "/installations", dict, need=(("installations",),)) |
| 93 | + if e: |
| 94 | + rows.append(rsa.nc("installed apps", rsa.why(e, need("admin:read (fine-grained: Administration read)")))) |
| 95 | + else: |
| 96 | + n = sum(1 for i in ins["installations"] if isinstance(i, dict) and any( |
| 97 | + (i.get("permissions") or {}).get(k) in ("write", "admin") for k in ("administration", "contents"))) |
| 98 | + rows.append(("%d installed app(s) hold write or admin on administration or contents" % n, "low" if n else "info", |
| 99 | + "review each app's permissions in the organization installed apps settings")) |
| 100 | + oc, e = rsa.listing(get, base + "/outside_collaborators") |
| 101 | + rows.append(rsa.nc("outside collaborators", rsa.why(e, need("admin:org (owner)"))) if e else |
| 102 | + ("%d outside collaborator(s)" % len(oc), "low" if oc else "info", "confirm each still needs access")) |
| 103 | + rn, e = rsa.listing(get, base + "/actions/runners", key="runners") |
| 104 | + rows.append(rsa.nc("self-hosted runners", rsa.why(e, need("admin:org (fine-grained: Self-hosted runners read)"))) if e else |
| 105 | + ("%d org self-hosted runner(s)" % len(rn), "medium" if rn else "info", |
| 106 | + "keep self-hosted runners off public repositories and use ephemeral runners")) |
| 107 | + return rows |
| 108 | + |
| 109 | + |
| 110 | +def audit(org, get, max_repos=200): |
| 111 | + """(org rows, {slug: rows}); an unreadable or over-long repo list is a not-checked org row.""" |
| 112 | + keys = ("check", "severity", "fix") |
| 113 | + rows = [dict(zip(keys, r)) for r in org_rows(get, org)] |
| 114 | + repos, e = rsa.listing(get, "/orgs/%s/repos" % org, {"type": "all"}, need=(("full_name",),)) |
| 115 | + if e: |
| 116 | + rows.append(dict(zip(keys, rsa.nc("repository list", rsa.why(e, need("read access to the organization's repositories")))))) |
| 117 | + repos = [] |
| 118 | + if len(repos) > max_repos: |
| 119 | + rows.append(dict(zip(keys, rsa.nc("repository list", ("capped at %d repos" % max_repos, "raise --max-repos"))))) |
| 120 | + rows.sort(key=lambda r: rsa.SEVERITY.index(r["severity"])) |
| 121 | + return rows, {r["full_name"]: rsa.audit(r["full_name"], get) for r in repos[:max_repos]} |
| 122 | + |
| 123 | + |
| 124 | +def main(argv=None, get=None): |
| 125 | + ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) |
| 126 | + ap.add_argument("org") |
| 127 | + ap.add_argument("--max-repos", type=int, default=200) |
| 128 | + ap.add_argument("--token-env") |
| 129 | + ap.add_argument("--json", action="store_true") |
| 130 | + a = ap.parse_args(argv) |
| 131 | + if not ORG.fullmatch(a.org): |
| 132 | + print("org_settings_audit: not an organization name", file=sys.stderr) |
| 133 | + return 2 |
| 134 | + if get is None: |
| 135 | + tok = os.environ.get(a.token_env, "") if a.token_env else subprocess.run( |
| 136 | + ["gh", "auth", "token"], capture_output=True, text=True).stdout.strip() |
| 137 | + if not tok: |
| 138 | + print("org_settings_audit: no token (set --token-env VAR or run `gh auth login`)", file=sys.stderr) |
| 139 | + return 2 |
| 140 | + get = curl_get(tok) |
| 141 | + org, repos = audit(a.org, get, a.max_repos) |
| 142 | + flat = [r for v in repos.values() for r in v] |
| 143 | + summ = {"repos": len(repos), "findings": sum(r["severity"] in rsa.FINDING for r in org + flat), |
| 144 | + "not_checked": sum(r["severity"] == "not-checked" for r in org + flat)} |
| 145 | + if a.json: |
| 146 | + print(json.dumps({"org": org, "repos": repos, "summary": summ}, indent=2)) |
| 147 | + else: |
| 148 | + print(rsa.render([dict(r, repo=a.org) for r in org] + flat, len(repos))[0]) |
| 149 | + return 0 |
| 150 | + |
| 151 | + |
| 152 | +if __name__ == "__main__": |
| 153 | + sys.exit(main()) |
0 commit comments