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.
- {subcheck-0.4.2 → subcheck-0.5.0}/BACKLOG.md +9 -2
- {subcheck-0.4.2 → subcheck-0.5.0}/CHANGELOG.md +39 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/PKG-INFO +10 -2
- {subcheck-0.4.2 → subcheck-0.5.0}/README.md +8 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/pyproject.toml +2 -2
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/__init__.py +1 -1
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/report.py +16 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/fixtures/github_subjects.json +7 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_report.py +20 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.gitattributes +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.github/dependabot.yml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/ci.yml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/fixture-drift.yml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.github/workflows/release.yml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/.gitignore +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/ARCHITECTURE.md +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/CONTRIBUTING.md +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/LICENSE +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/action.yml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-immutable.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-main.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-pull-request.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/claims-reusable-workflow.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy-immutable.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy-reusable-workflow.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy.json +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/examples/policy.yaml +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/scripts/check_fixture_drift.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/__main__.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/cli.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/decoder.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/policy.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/py.typed +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/src/subcheck/validator.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/conftest.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_claims_shape.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_cli.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_cli_inputs.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_decoder.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_decoder_vectors.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_fixture_provenance.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_policy_shape.py +0 -0
- {subcheck-0.4.2 → subcheck-0.5.0}/tests/test_time_notes.py +0 -0
- {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
|
-
(
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
41
|
+
'subvectors==0.5.2; python_version >= "3.11"',
|
|
42
42
|
]
|
|
43
43
|
|
|
44
44
|
[project.urls]
|
|
@@ -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
|
|
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
|
|
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
|