subcheck 0.4.2__tar.gz → 0.5.0__tar.gz

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.
Files changed (44) hide show
  1. {subcheck-0.4.2 → subcheck-0.5.0}/BACKLOG.md +9 -2
  2. {subcheck-0.4.2 → subcheck-0.5.0}/CHANGELOG.md +39 -0
  3. {subcheck-0.4.2 → subcheck-0.5.0}/PKG-INFO +10 -2
  4. {subcheck-0.4.2 → subcheck-0.5.0}/README.md +8 -0
  5. {subcheck-0.4.2 → subcheck-0.5.0}/pyproject.toml +2 -2
  6. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/__init__.py +1 -1
  7. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/report.py +16 -0
  8. {subcheck-0.4.2 → subcheck-0.5.0}/tests/fixtures/github_subjects.json +7 -0
  9. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_report.py +20 -0
  10. {subcheck-0.4.2 → subcheck-0.5.0}/.gitattributes +0 -0
  11. {subcheck-0.4.2 → subcheck-0.5.0}/.github/dependabot.yml +0 -0
  12. {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/ci.yml +0 -0
  13. {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/fixture-drift.yml +0 -0
  14. {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/release.yml +0 -0
  15. {subcheck-0.4.2 → subcheck-0.5.0}/.gitignore +0 -0
  16. {subcheck-0.4.2 → subcheck-0.5.0}/ARCHITECTURE.md +0 -0
  17. {subcheck-0.4.2 → subcheck-0.5.0}/CONTRIBUTING.md +0 -0
  18. {subcheck-0.4.2 → subcheck-0.5.0}/LICENSE +0 -0
  19. {subcheck-0.4.2 → subcheck-0.5.0}/action.yml +0 -0
  20. {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-immutable.json +0 -0
  21. {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-main.json +0 -0
  22. {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-pull-request.json +0 -0
  23. {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-reusable-workflow.json +0 -0
  24. {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy-immutable.json +0 -0
  25. {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy-reusable-workflow.json +0 -0
  26. {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy.json +0 -0
  27. {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy.yaml +0 -0
  28. {subcheck-0.4.2 → subcheck-0.5.0}/scripts/check_fixture_drift.py +0 -0
  29. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/__main__.py +0 -0
  30. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/cli.py +0 -0
  31. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/decoder.py +0 -0
  32. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/policy.py +0 -0
  33. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/py.typed +0 -0
  34. {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/validator.py +0 -0
  35. {subcheck-0.4.2 → subcheck-0.5.0}/tests/conftest.py +0 -0
  36. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_claims_shape.py +0 -0
  37. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_cli.py +0 -0
  38. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_cli_inputs.py +0 -0
  39. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_decoder.py +0 -0
  40. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_decoder_vectors.py +0 -0
  41. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_fixture_provenance.py +0 -0
  42. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_policy_shape.py +0 -0
  43. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_time_notes.py +0 -0
  44. {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_validator.py +0 -0
@@ -130,8 +130,15 @@ Open follow-ups from the same pass:
130
130
  `src/subvectors/github.py:62` now reads `owner_id is not None and repo_id is not None`, so the
131
131
  two grammars agree again. Nothing left to do here.
132
132
  - `[ ]` Re-vendor the subject fixtures if subvectors adds a malformed/asymmetric subject vector.
133
- (Not triggered yet: subvectors added no one-sided-`@id` vector; its grammar test covers the
134
- branch directly.)
133
+ (Still not triggered for THIS form: subvectors added no one-sided-`@id` vector; its grammar test
134
+ covers the branch directly.) **A different form did fire it, 2026-09-02**: the 0.5.2 pin brought
135
+ `repo:octo-org/octo-repo` - a subject with no `ref`, `environment` or event segment - and every
136
+ one of the nine vendored subjects carried a context, so the optional-context branch had no
137
+ fixture reaching it. Re-derived from `vectors/` (9 -> 10), and the entry pins `context` as
138
+ **absent**, because the omission is the whole point of the vector upstream. Worth noting the
139
+ mechanism: the drift check's COVERAGE direction asks whether upstream subjects *decode*, and this
140
+ one always did - what caught it was reading the delta on a deliberate pin bump. Coverage of the
141
+ corpus is not the same question as coverage of the grammar.
135
142
 
136
143
  ## Correctness / quality parking lot
137
144
 
@@ -6,6 +6,45 @@ All notable changes are documented here. Format based on
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.5.0] - 2026-09-02
10
+
11
+ ### Added
12
+ - **Advisory for a `sub` that identifies the repository and nothing else.** `include_claim_keys:
13
+ ["repo"]` mints a subject of exactly `repo:ORG/REPO`, with no `ref`, `environment` or event
14
+ segment. An IAM `StringEquals` condition on that value is an exact match holding no wildcard, and
15
+ it still admits every branch, tag, environment and `pull_request` run of the repository -
16
+ including a `pull_request` run on an unmerged branch. The over-permission is in what the subject
17
+ **omits**, so a review that scans conditions for `*` finds nothing to object to. subcheck now
18
+ notes the shape whenever it decodes one, and says what actually narrows it: adding claim keys
19
+ back to the subject, not tightening the condition's pattern. Advisory only, like every other
20
+ note - it never changes the verdict. Documented in the README's subject-customization section.
21
+ Found by consuming the corpus: this is upstream's
22
+ `gh-aws-repo-only-customized-sub-admits-everything`, which arrived with the 0.5.2 pin below.
23
+
24
+ ### Changed
25
+ - Pinned corpus bumped `subvectors==0.3.0` -> `0.5.2`, **and this one did carry a re-derivation**,
26
+ unlike the two bumps before it. Measured rather than assumed - comparing every `issuer: github`
27
+ subject string across the span shows **none removed and none changed**, and two added:
28
+ - `repo:octo-org/octo-repo:environment:Sandbox` (0.5.0) is a new *value* of the `environment:`
29
+ form the fixture already covers, so it needed nothing.
30
+ - `repo:octo-org/octo-repo` (0.5.2) is a new **form**: a subject with no `ref`, `environment` or
31
+ event segment at all. It exercises the optional-context branch of the subject grammar, which no
32
+ vendored subject reached before, so the fixture's own `_source` promise - "refresh from upstream
33
+ when subvectors adds subject forms" - is what fires here. Re-derived from `vectors/` rather than
34
+ copied: the fixture is now 10 subjects, and the new entry pins `context` as **absent**, since
35
+ what this subject omits is the whole point of it upstream.
36
+
37
+ All three drift directions green against the new pin (10 vendored, 23 upstream; provenance,
38
+ coverage and mis-parse clean), 120 tests pass.
39
+
40
+ What the releases in the span carry, since the pin now covers them: 0.4.x put the whole AWS
41
+ tranche on committed transcripts (11 `observed` vectors, each linking the raw request and
42
+ response) and recorded that AWS's `iam:CreateRole` guardrail validates only the FIRST value of a
43
+ `sub` condition's value list. 0.5.0 adds the `ForAllValues:`/`ForAnyValue:` set-operator tranche
44
+ and a `condition.qualifier` schema property. 0.5.1 corrected and commit-pinned the corpus's
45
+ Checkov citations - worth having under the pin, because the upstream PR this project's findings
46
+ fed into invites a maintainer to follow those links.
47
+
9
48
  ## [0.4.2] - 2026-09-01
10
49
 
11
50
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: subcheck
3
- Version: 0.4.2
3
+ Version: 0.5.0
4
4
  Summary: Decode GitHub Actions OIDC token claims and validate them against an expected-claims policy - a CI gate against over-broad cloud trust.
5
5
  Project-URL: Homepage, https://github.com/Dashtid/subcheck
6
6
  Project-URL: Related, https://github.com/Dashtid/subvectors
@@ -26,7 +26,7 @@ Requires-Dist: mypy>=1.8; extra == 'dev'
26
26
  Requires-Dist: pytest-cov>=4; extra == 'dev'
27
27
  Requires-Dist: pytest>=7; extra == 'dev'
28
28
  Requires-Dist: ruff>=0.4; extra == 'dev'
29
- Requires-Dist: subvectors==0.3.0; (python_version >= '3.11') and extra == 'dev'
29
+ Requires-Dist: subvectors==0.5.2; (python_version >= '3.11') and extra == 'dev'
30
30
  Requires-Dist: types-pyyaml>=6; extra == 'dev'
31
31
  Description-Content-Type: text/markdown
32
32
 
@@ -252,6 +252,14 @@ GitHub can also fold `job_workflow_ref` into `sub` itself via subject customizat
252
252
  `sub` **replaces** the default `repo:ORG/REPO:...` grammar rather than extending it — cloud trust
253
253
  conditions written for the default format stop matching, wildcards included.
254
254
 
255
+ The same mechanism has a sharper edge in the other direction. `include_claim_keys: ["repo"]` mints a
256
+ `sub` of exactly `repo:ORG/REPO`, with no `ref`, `environment` or event segment at all. An IAM
257
+ `StringEquals` condition on that value is an exact match containing no wildcard — and it still admits
258
+ every branch, every tag, every environment and every `pull_request` run of the repository, including
259
+ one on an unmerged branch. The over-permission is in what the subject **omits**, so a review that
260
+ scans conditions for `*` sees nothing wrong. subcheck notes this shape whenever it decodes one, and
261
+ narrowing it means adding claim keys back to the subject rather than tightening the pattern.
262
+
255
263
  ## Token lifetime notes
256
264
 
257
265
  If the claims carry `exp`, `nbf`, or `iat`, subcheck comments on them — as **notes, never failures**.
@@ -220,6 +220,14 @@ GitHub can also fold `job_workflow_ref` into `sub` itself via subject customizat
220
220
  `sub` **replaces** the default `repo:ORG/REPO:...` grammar rather than extending it — cloud trust
221
221
  conditions written for the default format stop matching, wildcards included.
222
222
 
223
+ The same mechanism has a sharper edge in the other direction. `include_claim_keys: ["repo"]` mints a
224
+ `sub` of exactly `repo:ORG/REPO`, with no `ref`, `environment` or event segment at all. An IAM
225
+ `StringEquals` condition on that value is an exact match containing no wildcard — and it still admits
226
+ every branch, every tag, every environment and every `pull_request` run of the repository, including
227
+ one on an unmerged branch. The over-permission is in what the subject **omits**, so a review that
228
+ scans conditions for `*` sees nothing wrong. subcheck notes this shape whenever it decodes one, and
229
+ narrowing it means adding claim keys back to the subject rather than tightening the pattern.
230
+
223
231
  ## Token lifetime notes
224
232
 
225
233
  If the claims carry `exp`, `nbf`, or `iat`, subcheck comments on them — as **notes, never failures**.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "subcheck"
7
- version = "0.4.2"
7
+ version = "0.5.0"
8
8
  description = "Decode GitHub Actions OIDC token claims and validate them against an expected-claims policy - a CI gate against over-broad cloud trust."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -38,7 +38,7 @@ dev = [
38
38
  "types-PyYAML>=6",
39
39
  "ruff>=0.4",
40
40
  "bandit>=1.7",
41
- 'subvectors==0.3.0; python_version >= "3.11"',
41
+ 'subvectors==0.5.2; python_version >= "3.11"',
42
42
  ]
43
43
 
44
44
  [project.urls]
@@ -5,7 +5,7 @@ from .policy import ClaimRule, Policy, load_policy, load_policy_file
5
5
  from .report import build_report, to_json, to_text
6
6
  from .validator import Result, validate
7
7
 
8
- __version__ = "0.4.2"
8
+ __version__ = "0.5.0"
9
9
 
10
10
  __all__ = [
11
11
  "decode_claims",
@@ -130,6 +130,22 @@ def _advisories(claims: dict, results: list[Result]) -> list[str]:
130
130
  "include_claim_keys); trust conditions written for the default "
131
131
  "'repo:ORG/REPO:...' format no longer match this token, wildcards included."
132
132
  )
133
+ elif parsed.get("repository") and "context" not in parsed:
134
+ # 'repo:ORG/REPO' with nothing after it. The default subject always carries a
135
+ # ref, environment or event segment, so this shape comes from subject
136
+ # customization (include_claim_keys: ["repo"]) - GitHub documents it as granting
137
+ # access to all the workflows in a repository, across all branches and tags.
138
+ # Worth a note because the over-permission lives in what the subject OMITS: an
139
+ # exact-match condition on this value carries no wildcard for a reviewer to spot
140
+ # and still admits every branch, tag, environment and pull_request run.
141
+ notes.append(
142
+ "sub carries no ref, environment or event segment - it identifies the "
143
+ "repository and nothing else. Any trust condition matching it admits every "
144
+ "branch, tag, environment and pull_request run of that repository, including "
145
+ "a pull_request run on an unmerged branch, and it does so without a wildcard "
146
+ "for a reviewer to notice. Narrowing means adding claim keys back to the "
147
+ "subject, not tightening the condition's pattern."
148
+ )
133
149
  fmt = parsed.get("format")
134
150
  if fmt is None:
135
151
  return notes
@@ -67,6 +67,13 @@
67
67
  "format": "legacy",
68
68
  "repository": "octo-org/octo-repo",
69
69
  "repository_owner": "octo-org"
70
+ },
71
+ {
72
+ "subject": "repo:octo-org/octo-repo",
73
+ "format": "legacy",
74
+ "repository": "octo-org/octo-repo",
75
+ "repository_owner": "octo-org",
76
+ "context": null
70
77
  }
71
78
  ]
72
79
  }
@@ -79,6 +79,26 @@ def test_customized_sub_warns_that_default_format_conditions_stop_matching():
79
79
  assert "wildcards included" in note
80
80
 
81
81
 
82
+ def test_repo_only_sub_warns_that_it_guards_nothing_below_the_repository():
83
+ # 'repo:ORG/REPO' with no ref, environment or event segment - the
84
+ # include_claim_keys: ["repo"] shape. The over-permission is in what the
85
+ # subject OMITS, so an exact-match condition on it carries no wildcard for a
86
+ # reviewer to spot while admitting every branch, tag and pull_request run.
87
+ claims = {"sub": "repo:acme/payments-api"}
88
+ policy = {"claims": {"sub": {"equals": "repo:acme/payments-api"}}}
89
+ note = " ".join(_report(claims, policy)["notes"])
90
+ assert "no ref, environment or event segment" in note
91
+ assert "pull_request run on an unmerged branch" in note
92
+
93
+
94
+ def test_repo_only_warning_does_not_fire_on_a_normal_subject():
95
+ # The note must key on an ABSENT context, not merely on a short subject: a
96
+ # ref-pinned sub is the ordinary case and deserves no scary advisory.
97
+ claims = {"sub": "repo:acme/payments-api:ref:refs/heads/main"}
98
+ note = " ".join(_report(claims, {"claims": {"sub": {"matches": "^repo:acme/"}}})["notes"])
99
+ assert "no ref, environment or event segment" not in note
100
+
101
+
82
102
  def test_unparseable_sub_yields_no_format_notes():
83
103
  # A sub that is not a GitHub subject at all (another issuer's format) must
84
104
  # not produce migration advice about a format it does not have.
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes