subcheck 0.2.0__py3-none-any.whl

subcheck/__init__.py

@@ -0,0 +1,23 @@
+"""subcheck: decode and validate GitHub Actions OIDC token claims."""
+
+from .decoder import decode_claims, parse_github_sub
+from .policy import ClaimRule, Policy, load_policy, load_policy_file
+from .report import build_report, to_json, to_text
+from .validator import Result, validate
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "decode_claims",
+    "parse_github_sub",
+    "ClaimRule",
+    "Policy",
+    "load_policy",
+    "load_policy_file",
+    "Result",
+    "validate",
+    "build_report",
+    "to_json",
+    "to_text",
+    "__version__",
+]

subcheck/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m subcheck`."""
+
+from .cli import main
+
+raise SystemExit(main())

subcheck/cli.py

@@ -0,0 +1,80 @@
+"""Command-line interface for subcheck."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .decoder import decode_claims
+from .policy import load_policy_file
+from .report import build_report, to_json, to_text
+from .validator import validate
+
+
+def _load_claims(args: argparse.Namespace) -> dict:
+    if args.token:
+        token = sys.stdin.read() if args.token == "-" else args.token  # noqa: S105  # nosec B105 - a JWT, not a secret to store
+        return decode_claims(token)
+    if args.token_file:
+        return decode_claims(Path(args.token_file).read_text(encoding="utf-8"))
+    if args.claims:
+        return json.loads(Path(args.claims).read_text(encoding="utf-8"))
+    raise ValueError("provide one of --token, --token-file, or --claims")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="subcheck",
+        description="Decode GitHub Actions OIDC token claims and validate them "
+        "against an expected-claims policy.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    src = parser.add_argument_group("claims input (choose one)")
+    src.add_argument("--token", help="the OIDC JWT ('-' reads from stdin)")
+    src.add_argument("--token-file", help="path to a file containing the OIDC JWT")
+    src.add_argument("--claims", help="path to a JSON file of already-decoded claims")
+    parser.add_argument(
+        "--policy", help="path to a policy file (.yaml/.yml/.json); omit to only decode"
+    )
+    parser.add_argument(
+        "--format", choices=["text", "json"], default="text",
+        help="output format (default: text)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    try:
+        claims = _load_claims(args)
+    except (ValueError, OSError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if not args.policy:
+        if args.format == "json":
+            print(json.dumps(claims, indent=2))
+        else:
+            for key, value in claims.items():
+                print(f"{key}: {value}")
+        return 0
+
+    try:
+        policy = load_policy_file(args.policy)
+    except (ValueError, OSError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    report = build_report(claims, validate(claims, policy))
+    print(to_json(report) if args.format == "json" else to_text(report))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

subcheck/decoder.py

@@ -0,0 +1,98 @@
+"""Decode a GitHub Actions OIDC JSON Web Token into its claims.
+
+This decodes the token payload for INSPECTION only. It does NOT verify the token
+signature - verifying the signature against GitHub's JWKS is the cloud provider's
+job at role-assumption time. Never trust these claims as an authentication control;
+use them to catch a misconfigured trust policy before it ships.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+
+
+def _b64url_decode(segment: str) -> bytes:
+    padding = "=" * (-len(segment) % 4)
+    return base64.urlsafe_b64decode(segment + padding)
+
+
+def decode_claims(token: str) -> dict:
+    """Decode the claims (payload) of a JWT without verifying its signature."""
+    parts = token.strip().split(".")
+    if len(parts) != 3:
+        raise ValueError(
+            f"not a JWT: expected 3 dot-separated segments, got {len(parts)}"
+        )
+    try:
+        payload = _b64url_decode(parts[1])
+    except (ValueError, binascii.Error) as exc:
+        raise ValueError(f"could not base64url-decode the JWT payload: {exc}") from exc
+    try:
+        claims = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"JWT payload is not valid JSON: {exc}") from exc
+    if not isinstance(claims, dict):
+        raise ValueError("JWT payload did not decode to a JSON object")
+    return claims
+
+
+# repo:OWNER[@owner_id]/REPO[@repo_id]: ... -- the immutable format appends a numeric
+# owner/repo ID (mandatory for repos created, renamed, or transferred after 2026-07-15).
+# Owner/repo names exclude the '/', '@', ':' delimiters. Mirrors the subvectors subject
+# grammar so the two agree on what a concrete subject decodes to.
+_SUB_RE = re.compile(
+    r"^repo:"
+    r"(?P<owner>[^/@:]+)(?:@(?P<owner_id>\d+))?"
+    r"/"
+    r"(?P<repo>[^/@:]+)(?:@(?P<repo_id>\d+))?"
+    r"(?::(?P<context>.*))?$"
+)
+
+
+def parse_github_sub(sub: str) -> dict:
+    """Best-effort parse of the GitHub Actions ``sub`` claim into its components.
+
+    Handles both the classic name-based format and the immutable format that appends
+    numeric owner/repo IDs (``repo:owner@123/repo@456:...``). ``format`` is ``"immutable"``
+    only when BOTH IDs are present (the documented grammar always carries ``@ID`` on both
+    segments), ``"legacy"`` when neither is, and ``"malformed"`` when exactly one is —
+    a shape GitHub never mints, so it signals a hand-edited or half-migrated value.
+    ``repository`` is always the ``owner/repo`` names.
+
+    Examples::
+
+        repo:acme/api:ref:refs/heads/main       -> repository, context=ref, ref, format=legacy
+        repo:acme/api:environment:production    -> repository, context=environment, environment
+        repo:acme@1/api@2:ref:refs/heads/main   -> repository, repository_id, ..., format=immutable
+        repo:acme/api@2:ref:refs/heads/main     -> format=malformed (only one ID present)
+        repo:acme/api:pull_request              -> repository, context=pull_request
+    """
+    out: dict = {"raw": sub}
+    m = _SUB_RE.match(sub)
+    if m is None:
+        return out
+    owner, repo = m.group("owner"), m.group("repo")
+    owner_id, repo_id = m.group("owner_id"), m.group("repo_id")
+    out["repository_owner"] = owner
+    out["repository"] = f"{owner}/{repo}"
+    if owner_id is not None:
+        out["repository_owner_id"] = owner_id
+    if repo_id is not None:
+        out["repository_id"] = repo_id
+    if owner_id and repo_id:
+        out["format"] = "immutable"
+    elif owner_id or repo_id:
+        out["format"] = "malformed"  # GitHub always emits @ID on both segments, or neither
+    else:
+        out["format"] = "legacy"
+    context = m.group("context")
+    if not context:
+        return out
+    kind, _, value = context.partition(":")
+    out["context"] = kind
+    if value:
+        out[kind] = value
+    return out

subcheck/policy.py

@@ -0,0 +1,115 @@
+"""Load an expected-claims policy and represent it as claim rules."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Trust-boundary anchors are high severity; contextual claims default to medium.
+CLAIM_SEVERITY = {
+    "iss": "high",
+    "aud": "high",
+    "sub": "high",
+    "repository": "high",
+    "repository_owner": "high",
+    "repository_id": "high",         # immutable trust anchors (survive rename/transfer)
+    "repository_owner_id": "high",
+    # the only claim constraining WHICH workflow code minted the token; AWS accepts it as an
+    # alternative identity-provider control to sub.
+    "job_workflow_ref": "high",
+    "ref": "medium",
+    "environment": "medium",
+    "runner_environment": "medium",
+    "actor": "medium",
+}
+DEFAULT_SEVERITY = "medium"
+
+_ALLOWED_KEYS = {"equals", "in", "matches", "glob", "required"}
+
+
+@dataclass
+class ClaimRule:
+    name: str
+    equals: str | None = None
+    one_of: list | None = None
+    matches: str | None = None  # regex, applied with re.search
+    glob: str | None = None     # fnmatch-style pattern
+    required: bool = True
+
+    @property
+    def severity(self) -> str:
+        return CLAIM_SEVERITY.get(self.name, DEFAULT_SEVERITY)
+
+    def describe(self) -> str:
+        if self.equals is not None:
+            return f"equals {self.equals!r}"
+        if self.one_of is not None:
+            return f"one of {self.one_of!r}"
+        if self.matches is not None:
+            return f"matches /{self.matches}/"
+        if self.glob is not None:
+            return f"glob {self.glob!r}"
+        return "present"
+
+
+@dataclass
+class Policy:
+    rules: list = field(default_factory=list)
+
+
+def load_policy(data: dict) -> Policy:
+    """Build a Policy from a parsed mapping (see the README for the schema)."""
+    if not isinstance(data, dict):
+        raise ValueError("policy must be a mapping/object")
+    rules: list = []
+    if "issuer" in data:
+        rules.append(ClaimRule(name="iss", equals=str(data["issuer"])))
+    if "audience" in data:
+        rules.append(ClaimRule(name="aud", equals=str(data["audience"])))
+    claims = data.get("claims") or {}
+    if not isinstance(claims, dict):
+        raise ValueError("policy 'claims' must be a mapping of claim -> rule")
+    for name, spec in claims.items():
+        rules.append(_rule_from_spec(name, spec))
+    if not rules:
+        raise ValueError("policy is empty: define 'issuer', 'audience', or 'claims'")
+    return Policy(rules=rules)
+
+
+def _rule_from_spec(name: str, spec) -> ClaimRule:
+    if isinstance(spec, str):
+        return ClaimRule(name=name, equals=spec)
+    if isinstance(spec, list):
+        return ClaimRule(name=name, one_of=list(spec))
+    if isinstance(spec, dict):
+        unknown = set(spec) - _ALLOWED_KEYS
+        if unknown:
+            raise ValueError(f"claim {name!r}: unknown rule keys {sorted(unknown)}")
+        return ClaimRule(
+            name=name,
+            equals=spec.get("equals"),
+            one_of=spec.get("in"),
+            matches=spec.get("matches"),
+            glob=spec.get("glob"),
+            required=bool(spec.get("required", True)),
+        )
+    raise ValueError(f"claim {name!r}: rule must be a string, list, or mapping")
+
+
+def load_policy_file(path: str | Path) -> Policy:
+    """Load a policy from a .json, .yaml, or .yml file."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    if p.suffix.lower() in {".yaml", ".yml"}:
+        try:
+            import yaml
+        except ModuleNotFoundError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "PyYAML is required to load YAML policies (pip install PyYAML), "
+                "or use a .json policy instead"
+            ) from exc
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+    return load_policy(data)

subcheck/report.py

@@ -0,0 +1,106 @@
+"""Assemble and format the inspection report."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from .decoder import parse_github_sub
+from .validator import FAIL, MISSING, PASS, Result
+
+
+def build_report(claims: dict, results: list[Result]) -> dict:
+    passed = all(r.status == PASS for r in results)
+    return {
+        "passed": passed,
+        "summary": {
+            "total": len(results),
+            "pass": sum(r.status == PASS for r in results),
+            "fail": sum(r.status == FAIL for r in results),
+            "missing": sum(r.status == MISSING for r in results),
+        },
+        "notes": _advisories(claims, results),
+        "results": [asdict(r) for r in results],
+        "claims": claims,
+    }
+
+
+GITHUB_ISSUER = "https://token.actions.githubusercontent.com"
+
+
+def _advisories(claims: dict, results: list[Result]) -> list[str]:
+    """Non-gating hints, chiefly about the 2026 immutable subject-claims migration.
+
+    Immutable subject claims are a github.com-only feature, so the migration hints are
+    suppressed for any other issuer (notably GitHub Enterprise Server, which keeps the
+    mutable name-based format and uses an https://HOSTNAME/_services/token issuer).
+    """
+    sub = claims.get("sub")
+    if not isinstance(sub, str):
+        return []
+    iss = claims.get("iss")
+    if isinstance(iss, str) and iss != GITHUB_ISSUER:
+        return []
+    parsed = parse_github_sub(sub)
+    fmt = parsed.get("format")
+    if fmt is None:
+        return []
+    sub_result = next((r for r in results if r.claim == "sub"), None)
+    name_based_sub_pin = sub_result is not None and "@" not in str(sub_result.expected)
+    notes: list[str] = []
+    if fmt == "immutable":
+        oid, rid = parsed.get("repository_owner_id"), parsed.get("repository_id")
+        notes.append(
+            f"sub uses the immutable format (repository_owner_id={oid}, repository_id={rid}); "
+            "pin these numeric IDs in the cloud trust policy rather than mutable owner/repo names."
+        )
+        if sub_result is not None and sub_result.status == FAIL and name_based_sub_pin:
+            notes.append(
+                "the sub check failed while the token is immutable-format and the expected "
+                "pattern looks name-based; update the expected sub, or pin repository_id / "
+                "repository_owner_id instead."
+            )
+    elif fmt == "malformed":
+        notes.append(
+            "sub carries an owner/repo ID on only one segment; GitHub always emits '@id' on "
+            "both or neither, so this value looks hand-edited or half-migrated."
+        )
+    elif fmt == "legacy" and name_based_sub_pin:
+        notes.append(
+            "sub is pinned by name; when this repo adopts the immutable format the sub becomes "
+            "'owner@id/repo@id:...' and this pattern stops matching - pin repository_id / "
+            "repository_owner_id to stay durable. Adoption is automatic for repos created, "
+            "renamed, or transferred after 2026-07-15, but any repo can be switched on sooner "
+            "via the org-level or repo-level immutable-subject setting, so do not infer the "
+            "format from the repo's age."
+        )
+    return notes
+
+
+def to_json(report: dict) -> str:
+    return json.dumps(report, indent=2)
+
+
+_ICON = {PASS: "[+]", FAIL: "[-]", MISSING: "[!]"}
+
+
+def to_text(report: dict) -> str:
+    summary = report["summary"]
+    verdict = "PASS" if report["passed"] else "FAIL"
+    lines = [
+        f"OIDC claim inspection: {verdict}  "
+        f"({summary['pass']} pass, {summary['fail']} fail, {summary['missing']} missing)",
+        "",
+    ]
+    width = max((len(r["claim"]) for r in report["results"]), default=5)
+    for r in report["results"]:
+        icon = _ICON.get(r["status"], "[?]")
+        lines.append(
+            f"  {icon} {r['claim']:<{width}}  {r['severity']:<6}  {r['message']}"
+        )
+    notes = report.get("notes") or []
+    if notes:
+        lines.append("")
+        lines.append("Notes:")
+        lines.extend(f"  [i] {note}" for note in notes)
+    return "\n".join(lines)

subcheck/validator.py

@@ -0,0 +1,64 @@
+"""Validate decoded claims against a policy."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+
+from .policy import ClaimRule, Policy
+
+PASS = "PASS"  # noqa: S105  # nosec B105 - a status constant, not a secret
+FAIL = "FAIL"
+MISSING = "MISSING"
+
+
+@dataclass
+class Result:
+    claim: str
+    status: str
+    severity: str
+    expected: str
+    actual: object
+    message: str
+
+
+def _matches(rule: ClaimRule, value) -> bool:
+    text = str(value)
+    if rule.equals is not None and value != rule.equals:
+        return False
+    if rule.one_of is not None and value not in rule.one_of:
+        return False
+    if rule.matches is not None and re.search(rule.matches, text) is None:
+        return False
+    if rule.glob is not None and not fnmatch.fnmatchcase(text, rule.glob):
+        return False
+    return True
+
+
+def validate(claims: dict, policy: Policy) -> list[Result]:
+    """Check each policy rule against the claims and return one Result per rule."""
+    results: list[Result] = []
+    for rule in policy.rules:
+        expected = rule.describe()
+        if rule.name not in claims:
+            status = MISSING if rule.required else PASS
+            note = (
+                f"claim {rule.name!r} is required but absent"
+                if rule.required
+                else f"claim {rule.name!r} absent (optional)"
+            )
+            results.append(Result(rule.name, status, rule.severity, expected, None, note))
+            continue
+        actual = claims[rule.name]
+        if _matches(rule, actual):
+            results.append(
+                Result(rule.name, PASS, rule.severity, expected, actual,
+                       f"claim {rule.name!r} satisfies {expected}")
+            )
+        else:
+            results.append(
+                Result(rule.name, FAIL, rule.severity, expected, actual,
+                       f"claim {rule.name!r}={actual!r} does not satisfy {expected}")
+            )
+    return results

subcheck-0.2.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.5
+Name: subcheck
+Version: 0.2.0
+Summary: Decode GitHub Actions OIDC token claims and validate them against an expected-claims policy - a CI gate against over-broad cloud trust.
+Project-URL: Homepage, https://github.com/Dashtid/subcheck
+Project-URL: Related, https://github.com/Dashtid/subvectors
+Author: David Dashti
+License: MIT
+License-File: LICENSE
+Keywords: aws-iam,cicd-security,github-actions,least-privilege,oidc,supply-chain-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# subcheck
+
+Decode a GitHub Actions **OIDC token's claims** and check them against an expected-claims
+policy — so a workflow fails *before* an over-broad cloud trust policy lets the wrong branch,
+workflow, or trigger assume your role.
+
+*Named for the claim that decides everything — `sub`. A focused sibling of
+[subvectors](https://github.com/Dashtid/subvectors), the conformance test-vector suite (an "answer
+key") that grades whether those trust conditions are well-formed, matching, and safe.*
+
+```text
+$ subcheck --claims examples/claims-pull-request.json --policy examples/policy.json
+OIDC claim inspection: FAIL  (5 pass, 1 fail, 1 missing)
+
+  [+] iss                 high    claim 'iss' satisfies equals 'https://token.actions.githubusercontent.com'
+  [+] aud                 high    claim 'aud' satisfies equals 'sts.amazonaws.com'
+  [+] repository          high    claim 'repository' satisfies equals 'acme/payments-api'
+  [+] repository_owner    high    claim 'repository_owner' satisfies equals 'acme'
+  [-] sub                 high    claim 'sub'='repo:acme/payments-api:pull_request' does not satisfy matches /^repo:acme/payments-api:(ref:refs/heads/main|environment:production|ref:refs/tags/v[0-9].*)$/
+  [!] environment         medium  claim 'environment' is required but absent
+  [+] runner_environment  medium  claim 'runner_environment' satisfies equals 'github-hosted'
+```
+
+Exit code is non-zero on any finding, so the command drops straight into a CI step as a gate.
+
+## Why
+
+GitHub Actions can authenticate to AWS/Azure/GCP with a short-lived **OIDC token** instead of a
+long-lived secret. The cloud side (e.g. an AWS IAM role's trust policy) decides *which* tokens
+may assume the role by matching claims — above all `sub`
+(`repo:org/repo:ref:refs/heads/main`, `...:environment:production`, `...:pull_request`, …).
+
+The classic mistake is a trust condition that's too loose — a wildcard `sub`, a missing
+condition, or `...:sub` allowed for `repo:org/*` — so a token minted by something you never
+intended can assume a privileged role. This tool pins down exactly which claims you *expect* and
+flags the moment a token doesn't match.
+
+> **Who can actually mint such a token.** Not a fork's pull request: for `pull_request` runs from
+> a fork GitHub downgrades `id-token: write` and never injects
+> `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, so a fork cannot obtain a token for the upstream repo. The
+> real paths are anyone with push/branch-create access (a wildcard `sub` then covers their
+> branch), `pull_request_target` or `workflow_run` jobs that check out untrusted code, and a
+> compromised third-party action running inside an already-trusted job.
+
+It's the small, focused sibling of **[subvectors](https://github.com/Dashtid/subvectors)** — the
+conformance test-vector suite that grades whether a cloud trust *condition* is well-formed,
+matches, and is safe. This one works the other end: it inspects a single *token* against a policy
+you write — nothing to configure, no cloud account, no network.
+
+## Install
+
+```bash
+pip install subcheck        # v0.2.0 — first PyPI release rolling out
+# or from a clone:
+pip install -e ".[dev]"
+```
+
+Or skip installing entirely and use the GitHub Action — see [In a workflow](#in-a-workflow).
+
+## Usage
+
+Decode a token (claims only):
+
+```bash
+subcheck --token "$TOKEN"      # or: --token -   (read the JWT from stdin)
+```
+
+Validate against a policy and gate on the result:
+
+```bash
+subcheck --token "$TOKEN" --policy .github/oidc-policy.yaml
+echo $?     # 0 = all matched, 1 = a claim didn't match, 2 = usage/parse error
+```
+
+Inputs (choose one): `--token <jwt>` (`-` for stdin), `--token-file <path>`, or
+`--claims <decoded-claims.json>`. Output: `--format text` (default) or `json`.
+
+> Prefer `--token -` (stdin) or `--token-file` over passing the JWT as an argument — a token on the
+> command line leaks into the process list and shell history.
+
+> **Scope (and honesty):** this **decodes** the token payload for inspection — it does **not
+> verify the signature**. Verifying the signature and issuer against GitHub's JWKS is the cloud
+> provider's job at role-assumption time. Use this to catch misconfigured *expectations* early,
+> not as an authentication control.
+
+## Policy
+
+YAML or JSON. `issuer`/`audience` are shortcuts for the `iss`/`aud` claims; everything else lives
+under `claims`. Each claim takes one or more of `equals`, `in` (list), `matches` (regex), `glob`,
+and `required` (default `true`).
+
+```yaml
+issuer: https://token.actions.githubusercontent.com
+audience: sts.amazonaws.com
+claims:
+  repository:
+    equals: acme/payments-api
+  sub:
+    matches: '^repo:acme/payments-api:(ref:refs/heads/main|environment:production)$'
+  runner_environment:
+    equals: github-hosted        # reject self-hosted runners (see note below)
+  environment:
+    equals: production
+    required: true
+```
+
+Shorthand: a bare string means `equals`, a list means `in`:
+
+```yaml
+claims:
+  repository_owner: acme
+  ref: [refs/heads/main, refs/heads/release]
+```
+
+**Matching notes:** `matches` uses `re.search`, so it is *not* anchored — `matches: pull_request`
+matches that substring anywhere in the value. Anchor with `^…$` when you mean the whole claim (the
+examples do). `equals`/`in` compare against the value's real JSON type, so quote a number you expect
+as a string; `matches`/`glob` always operate on the stringified value.
+
+`glob` is `fnmatch`-based: case-sensitive, `*` spans any characters (including `/` and `:`), `?`
+matches one. That lines up with AWS IAM `StringLike` on the properties that matter, with **one
+divergence** — `fnmatch` also honours POSIX character classes, so `glob: 'repo:acme/[ap]*'` matches
+here while IAM treats `[` and `]` as literals and matches nothing. Avoid character classes if the
+pattern is meant to mirror a trust policy. This is an expectation language, not a cloud-semantics
+simulator (see [subvectors](https://github.com/Dashtid/subvectors) for that).
+
+Claims that anchor the trust boundary (`iss`, `aud`, `sub`, `repository`, `repository_owner`,
+`repository_id`, `repository_owner_id`, and `job_workflow_ref`) are reported at **high** severity;
+contextual claims default to **medium**.
+
+**Why check claims the cloud already checks?** Because for several of them it can't.
+`runner_environment` is the clearest case: "reject self-hosted runners" is **not expressible in an
+AWS IAM trust policy at all** — nor are `event_name`, `head_ref`, `base_ref`, or `workflow_ref`. AWS
+exposes only a fixed set of GitHub claims as condition keys, and note that `repository_owner` is not
+among them (only `repository_owner_id` is), so a name-based owner pin here has no trust-policy
+equivalent. Asserting those claims in the job is the only place they can be enforced.
+
+## Immutable subject claims (2026-07-15)
+
+GitHub is migrating the `sub` claim to an **immutable format** that embeds numeric owner/repo IDs —
+`repo:acme@123456/payments-api@456789:ref:refs/heads/main`. Adoption is automatic for repositories
+created, renamed, or transferred after **2026-07-15**, but any repository can be switched on sooner
+through the org-level or repo-level immutable-subject setting — so you cannot infer the format from
+a repo's age. A trust condition (or a `sub` pattern here) written for the legacy
+`repo:owner/repo:...` names silently stops matching, and deploys break with no code change.
+
+Immutable subject claims are **github.com only**; GitHub Enterprise Server keeps the mutable
+name-based format under its own `https://HOSTNAME/_services/token` issuer, and subcheck suppresses
+these migration hints for any non-github.com issuer.
+
+subcheck decodes both formats, reports which one a token uses, and flags the mismatch. Run a
+post-migration token against a name-based policy and it points straight at the cause (rows trimmed):
+
+```text
+$ subcheck --claims examples/claims-immutable.json --policy examples/policy.json
+OIDC claim inspection: FAIL  (6 pass, 1 fail, 0 missing)
+  ...
+  [-] sub                 high    claim 'sub'='repo:acme@123456/payments-api@456789:ref:refs/heads/main' does not satisfy matches /^repo:acme/payments-api:(ref:refs/heads/main|environment:production|ref:refs/tags/v[0-9].*)$/
+  ...
+
+Notes:
+  [i] sub uses the immutable format (repository_owner_id=123456, repository_id=456789); pin these numeric IDs in the cloud trust policy rather than mutable owner/repo names.
+  [i] the sub check failed while the token is immutable-format and the expected pattern looks name-based; update the expected sub, or pin repository_id / repository_owner_id instead.
+```
+
+The durable fix is to pin the numeric IDs — stable across renames and transfers — as in
+[`examples/policy-immutable.json`](examples/policy-immutable.json):
+
+```yaml
+claims:
+  repository_owner_id: "123456"
+  repository_id: "456789"
+```
+
+`repository_id` and `repository_owner_id` are **not new** — they have been separate claims in every
+token since January 2023 and are present on legacy-format tokens too. You do not have to wait for
+the migration to pin them; doing it now is what makes a policy survive the switch.
+
+## In a workflow
+
+The one-line form — this repo ships an [`action.yml`](action.yml) that requests the job's OIDC
+token and checks it against your policy:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: actions/checkout@v4
+  - name: Verify the OIDC token is scoped as expected
+    uses: Dashtid/subcheck@v0.2.0        # or @main
+    with:
+      policy: .github/oidc-policy.yaml
+      audience: sts.amazonaws.com        # default
+```
+
+Or by hand, if you'd rather see every moving part:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: actions/checkout@v4
+  - run: pip install subcheck
+  - name: Verify the OIDC token is scoped as expected
+    run: |
+      TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r .value)
+      echo "$TOKEN" | subcheck --token - --policy .github/oidc-policy.yaml
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q          # tests
+ruff check .       # lint
+bandit -r src      # security lint
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md); good first issues are labelled.
+
+## Related tools
+
+- **[subvectors](https://github.com/Dashtid/subvectors)** — the sibling project, working the other
+  end of the same trust boundary. subcheck checks the token a job *received* against your expected
+  claims; subvectors is the *cloud side* — a cited, versioned suite of conformance test vectors
+  answering "does subject S satisfy trust condition C, and is C safe?" across AWS IAM, Azure FIC,
+  and GCP WIF. subvectors grades the trust *rules*; subcheck asserts the *token*.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

subcheck-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+subcheck/__init__.py,sha256=pZFAujfMcSfmRAldlDtIxGQ5gTuzR-y2Vr6az53fBBE,540
+subcheck/__main__.py,sha256=4wiZ8LHV9WhvMBpR6zirrTCbdJMENUK2tmCLoGMYHfE,84
+subcheck/cli.py,sha256=NR5HmRy7F1-MbRv52uTxBxdfzDc3G3SEQH9cYadAQ1Y,2676
+subcheck/decoder.py,sha256=hcPuSNNvesm2LUYibJ8YrmGo0P7uiXhPZPdihWHWTF0,3851
+subcheck/policy.py,sha256=mvxZzIDzZKD-ckfm3I8_hU6BYGiW8B7tssRTGBwWExg,3881
+subcheck/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+subcheck/report.py,sha256=fTnZf3wEFWUbEpLVWLpjKkqgeoXshdP_SwPZweAEPkY,4128
+subcheck/validator.py,sha256=n1BWCCK1CKOJDLIOd11jz-W2OIPadHwxR3i_8NMQmEg,1987
+subcheck-0.2.0.dist-info/METADATA,sha256=fYON2N918XnZ9KMDAPST0K2iYJi3BMUcXbH87JoyXPY,12104
+subcheck-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+subcheck-0.2.0.dist-info/entry_points.txt,sha256=7Dg3ZOD1DWJyJkph4ZwfLIJH2ZFpw3Oh-XwLGo_GlmA,47
+subcheck-0.2.0.dist-info/licenses/LICENSE,sha256=SM21vnphyagwWbi9zY_fb64WEfpmTDjpXo0e_15iK7I,1069
+subcheck-0.2.0.dist-info/RECORD,,

subcheck-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

subcheck-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+subcheck = subcheck.cli:main

subcheck-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Dashti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.