Skip to content

Commit a2dd65c

Browse files
woodruffwwoodruffw
authored
CLI: sigstore verify github (#381)
* _cli: skeleton for `sigstore verify github` Signed-off-by: William Woodruff <[email protected]> * _cli: reorg options, devolve into more groups Signed-off-by: William Woodruff <[email protected]> * _cli: more factoring out, basic GH functionality Signed-off-by: William Woodruff <[email protected]> * README, Makefile: `sigstore verify github --help` Signed-off-by: William Woodruff <[email protected]> * README: more docs Signed-off-by: William Woodruff <[email protected]> * sigstore, README: remove `--cert-email` Long deprecated. Signed-off-by: William Woodruff <[email protected]> * _cli: tweak "helpful" error messages Now that we manage keys with TUF, the most likely error here is misconfiguration: someone asking us to verify a sig/cert that was issued against a different instance of Fulcio than we're verifying with. Signed-off-by: William Woodruff <[email protected]> * _cli, README: tweak `sigstore verify github` flags Signed-off-by: William Woodruff <[email protected]> * CHANGELOG: record changes Signed-off-by: William Woodruff <[email protected]> * CHANGELOG, cli: record more changes Signed-off-by: William Woodruff <[email protected]> * _cli: add notes to help text Signed-off-by: William Woodruff <[email protected]> * README: update `--help` text Signed-off-by: William Woodruff <[email protected]> * _cli: fix fallback behavior Signed-off-by: William Woodruff <[email protected]> * _cli: lintage Signed-off-by: William Woodruff <[email protected]> Signed-off-by: William Woodruff <[email protected]>
1 parent 51b2279 commit a2dd65c

File tree

4 files changed

+423
-101
lines changed

4 files changed

+423
-101
lines changed

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,16 @@ All versions prior to 0.9.0 are untracked.
3030
version of `sigstore-python`
3131
([#383](https://github.com/sigstore/sigstore-python/pull/383))
3232

33+
* The per-subcommand options `--rekor-url` and `--rekor-root-pubkey` have been
34+
moved to the top-level `sigstore` command. Their subcommand forms are unchanged
35+
and will continue to work, but will be marked deprecated in a future stable
36+
version of `sigstore-python`
37+
([#381](https://github.com/sigstore/sigstore-python/pull/383))
38+
39+
* `sigstore verify github` has been added, allowing for verification of
40+
GitHub-specific claims within given certificate(s)
41+
([#381](https://github.com/sigstore/sigstore-python/pull/381))
42+
3343
### Changed
3444

3545
* The default behavior of `SIGSTORE_LOGLEVEL` has changed; the logger

‎Makefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,16 @@ check-readme:
127127
$(MAKE) -s run ARGS="verify identity --help" \
128128
)
129129

130+
# sigstore verify github --help
131+
@diff \
132+
<( \
133+
awk '/@begin-sigstore-verify-github-help@/{f=1;next} /@end-sigstore-verify-github-help@/{f=0} f' \
134+
< README.md | sed '1d;$$d' \
135+
) \
136+
<( \
137+
$(MAKE) -s run ARGS="verify github --help" \
138+
)
139+
130140

131141
.PHONY: edit
132142
edit:

‎README.md‎

Lines changed: 105 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,8 @@ Top-level:
7171

7272
<!-- @begin-sigstore-help@ -->
7373
```
74-
usage: sigstore [-h] [-V] [-v] [--staging]
74+
usage: sigstore [-h] [-V] [-v] [--staging] [--rekor-url URL]
75+
[--rekor-root-pubkey FILE]
7576
{sign,verify,get-identity-token} ...
7677

7778
a tool for signing and verifying Python package distributions
@@ -88,6 +89,11 @@ optional arguments:
8889
Sigstore instance options:
8990
--staging Use sigstore's staging instances, instead of the
9091
default production instances (default: False)
92+
--rekor-url URL The Rekor instance to use (conflicts with --staging)
93+
(default: https://rekor.sigstore.dev)
94+
--rekor-root-pubkey FILE
95+
A PEM-encoded root public key for Rekor itself
96+
(conflicts with --staging) (default: None)
9197
```
9298
<!-- @end-sigstore-help@ -->
9399
@@ -146,11 +152,15 @@ Sigstore instance options:
146152
default production instances. This option will be
147153
deprecated in favor of the global `--staging` option
148154
in a future release. (default: False)
149-
--rekor-url URL The Rekor instance to use (conflicts with --staging)
150-
(default: https://rekor.sigstore.dev)
155+
--rekor-url URL The Rekor instance to use (conflicts with --staging).
156+
This option will be deprecated in favor of the global
157+
`--rekor-url` option in a future release. (default:
158+
None)
151159
--rekor-root-pubkey FILE
152160
A PEM-encoded root public key for Rekor itself
153-
(conflicts with --staging) (default: None)
161+
(conflicts with --staging). This option will be
162+
deprecated in favor of the global `--rekor-root-
163+
pubkey` option in a future release. (default: None)
154164
--fulcio-url URL The Fulcio instance to use (conflicts with --staging)
155165
(default: https://fulcio.sigstore.dev)
156166
--ctfe FILE A PEM-encoded public key for the CT log (conflicts
@@ -160,7 +170,7 @@ Sigstore instance options:
160170
161171
### Verifying
162172
163-
#### Identities
173+
#### Generic identities
164174
165175
This is the most common verification done with `sigstore`, and therefore
166176
the one you probably want: you can use it to verify that a signature was
@@ -170,17 +180,13 @@ to by a particular OIDC provider (like `https://github.com/login/oauth`).
170180
<!-- @begin-sigstore-verify-identity-help@ -->
171181
```
172182
usage: sigstore verify identity [-h] [--certificate FILE] [--signature FILE]
173-
[--rekor-bundle FILE]
183+
[--rekor-bundle FILE] --cert-identity IDENTITY
184+
[--require-rekor-offline] --cert-oidc-issuer
185+
URL [--staging] [--rekor-url URL]
186+
[--rekor-root-pubkey FILE]
174187
[--certificate-chain FILE]
175-
[--cert-email EMAIL] --cert-identity IDENTITY
176-
--cert-oidc-issuer URL
177-
[--require-rekor-offline] [--staging]
178-
[--rekor-url URL] [--rekor-root-pubkey FILE]
179188
FILE [FILE ...]
180189

181-
positional arguments:
182-
FILE The file to verify
183-
184190
optional arguments:
185191
-h, --help show this help message and exit
186192

@@ -192,41 +198,114 @@ Verification inputs:
192198
multiple inputs (default: None)
193199
--rekor-bundle FILE The offline Rekor bundle to verify with; not used with
194200
multiple inputs (default: None)
201+
FILE The file to verify
195202

196-
Extended verification options:
197-
--certificate-chain FILE
198-
Path to a list of CA certificates in PEM format which
199-
will be needed when building the certificate chain for
200-
the signing certificate (default: None)
201-
--cert-email EMAIL Deprecated; causes an error. Use --cert-identity
202-
instead (default: None)
203+
Verification options:
203204
--cert-identity IDENTITY
204205
The identity to check for in the certificate's Subject
205206
Alternative Name (default: None)
206-
--cert-oidc-issuer URL
207-
The OIDC issuer URL to check for in the certificate's
208-
OIDC issuer extension (default: None)
209207
--require-rekor-offline
210208
Require offline Rekor verification with a bundle;
211209
implied by --rekor-bundle (default: False)
210+
--cert-oidc-issuer URL
211+
The OIDC issuer URL to check for in the certificate's
212+
OIDC issuer extension (default: None)
212213

213214
Sigstore instance options:
214215
--staging Use sigstore's staging instances, instead of the
215216
default production instances. This option will be
216217
deprecated in favor of the global `--staging` option
217218
in a future release. (default: False)
218-
--rekor-url URL The Rekor instance to use (conflicts with --staging)
219-
(default: https://rekor.sigstore.dev)
219+
--rekor-url URL The Rekor instance to use (conflicts with --staging).
220+
This option will be deprecated in favor of the global
221+
`--rekor-url` option in a future release. (default:
222+
None)
220223
--rekor-root-pubkey FILE
221224
A PEM-encoded root public key for Rekor itself
222-
(conflicts with --staging) (default: None)
225+
(conflicts with --staging). This option will be
226+
deprecated in favor of the global `--rekor-root-
227+
pubkey` option in a future release. (default: None)
228+
--certificate-chain FILE
229+
Path to a list of CA certificates in PEM format which
230+
will be needed when building the certificate chain for
231+
the Fulcio signing certificate (default: None)
223232
```
224233
<!-- @end-sigstore-verify-identity-help@ -->
225234
226235
For backwards compatibility, `sigstore verify [args ...]` is equivalent to
227236
`sigstore verify identity [args ...]`, but the latter form is **strongly**
228237
preferred.
229238
239+
#### Signatures from GitHub Actions
240+
241+
If your signatures are coming from GitHub Actions (e.g., a workflow
242+
that uses its [ambient credentials](#signing-with-ambient-credentials)),
243+
then you can use the `sigstore verify github` subcommand to verify
244+
claims more precisely than `sigstore verify identity` allows:
245+
246+
<!-- @begin-sigstore-verify-github-help@ -->
247+
```
248+
usage: sigstore verify github [-h] [--certificate FILE] [--signature FILE]
249+
[--rekor-bundle FILE] --cert-identity IDENTITY
250+
[--require-rekor-offline] [--trigger EVENT]
251+
[--sha SHA] [--name NAME] [--repository REPO]
252+
[--ref REF] [--staging] [--rekor-url URL]
253+
[--rekor-root-pubkey FILE]
254+
[--certificate-chain FILE]
255+
FILE [FILE ...]
256+
257+
optional arguments:
258+
-h, --help show this help message and exit
259+
260+
Verification inputs:
261+
--certificate FILE, --cert FILE
262+
The PEM-encoded certificate to verify against; not
263+
used with multiple inputs (default: None)
264+
--signature FILE The signature to verify against; not used with
265+
multiple inputs (default: None)
266+
--rekor-bundle FILE The offline Rekor bundle to verify with; not used with
267+
multiple inputs (default: None)
268+
FILE The file to verify
269+
270+
Verification options:
271+
--cert-identity IDENTITY
272+
The identity to check for in the certificate's Subject
273+
Alternative Name (default: None)
274+
--require-rekor-offline
275+
Require offline Rekor verification with a bundle;
276+
implied by --rekor-bundle (default: False)
277+
--trigger EVENT The GitHub Actions event name that triggered the
278+
workflow (default: None)
279+
--sha SHA The `git` commit SHA that the workflow run was invoked
280+
with (default: None)
281+
--name NAME The name of the workflow that was triggered (default:
282+
None)
283+
--repository REPO The repository slug that the workflow was triggered
284+
under (default: None)
285+
--ref REF The `git` ref that the workflow was invoked with
286+
(default: None)
287+
288+
Sigstore instance options:
289+
--staging Use sigstore's staging instances, instead of the
290+
default production instances. This option will be
291+
deprecated in favor of the global `--staging` option
292+
in a future release. (default: False)
293+
--rekor-url URL The Rekor instance to use (conflicts with --staging).
294+
This option will be deprecated in favor of the global
295+
`--rekor-url` option in a future release. (default:
296+
None)
297+
--rekor-root-pubkey FILE
298+
A PEM-encoded root public key for Rekor itself
299+
(conflicts with --staging). This option will be
300+
deprecated in favor of the global `--rekor-root-
301+
pubkey` option in a future release. (default: None)
302+
--certificate-chain FILE
303+
Path to a list of CA certificates in PEM format which
304+
will be needed when building the certificate chain for
305+
the Fulcio signing certificate (default: None)
306+
```
307+
<!-- @end-sigstore-verify-github-help@ -->
308+
230309
## Example uses
231310
232311
`sigstore` supports a wide variety of workflows and usages. Some common ones are

0 commit comments

Comments
 (0)