sidebar_label | title | sidebar_position | toc_min_heading_level | toc_max_heading_level |
---|---|---|---|---|
Verify |
Scribe GitHub Action for `valint verify` |
3 |
2 |
5 |
Scribe offers GitHub Actions for embedding evidence collecting and validated integrity of your supply chain.
Use valint verify
to verify evidence (attestations) and policies.
Further documentation GitHub integration.
The command allows users to verify any target against its evidence.
- Verify image, directory, file or git targets.
- Verify evidence policy compliance across the supply chain.
- Pull evidence from scribe service.
- Download and search evidence in all enabled stores.
- Support Sigstore keyless verifying as well as GitHub workload identity.
target:
description: Target object name format=[<image:tag>, <dir path>, <git url>]
required: true
type:
description: Target source type scheme=[docker,docker-archive, oci-archive, dir, registry, git, generic]
deprecationMessage: Please use target fields, formated [type]:[target]:[tag]
required: false
scribe-audience:
description: Scribe auth audience
deprecationMessage: Please use scribe-auth-audience instead
required: false
attestation:
description: Attestation for target
common-name:
description: Default policy allowed common names
email:
description: Default policy allowed emails
force:
description: Force skip cache
input-format:
description: Evidence format, options=[attest-cyclonedx-json attest-slsa statement-slsa statement-cyclonedx-json statement-generic attest-generic]
uri:
description: Default policy allowed uris
allow-expired:
description: Allow expired certs
attest-config:
description: Attestation config path
attest-default:
description: Attestation default config, options=[sigstore sigstore-github x509 x509-env]
backoff:
description: Backoff duration
ca:
description: x509 CA Chain path
cache-enable:
description: Enable local cache
cert:
description: x509 Cert path
config:
description: Configuration file path
context-dir:
description: Context dir
crl:
description: x509 CRL path
crl-full-chain:
description: Enable Full chain CRL verfication
disable-crl:
description: Disable certificate revocation verificatoin
env:
description: Environment keys to include in sbom
filter-regex:
description: Filter out files by regex
filter-scope:
description: Filter packages by scope
git-branch:
description: Git branch in the repository
git-commit:
description: Git commit hash in the repository
git-tag:
description: Git tag in the repository
key:
description: x509 Private key path
label:
description: Add Custom labels
level:
description: Log depth level, options=[panic fatal error warning info debug trace]
log-context:
description: Attach context to all logs
log-file:
description: Output log to file
oci:
description: Enable OCI store
oci-repo:
description: Select OCI custom attestation repo
output-directory:
description: Output directory path
default: ./scribe/valint
output-file:
description: Output file name
pipeline-name:
description: Pipeline name
policy-args:
description: Policy arguments
predicate-type:
description: Custom Predicate type (generic evidence format)
product-key:
description: Product Key
product-version:
description: Product Version
scribe-auth-audience:
description: Scribe auth audience
scribe-client-id:
description: Scribe Client ID
scribe-client-secret:
description: Scribe Client Secret
scribe-enable:
description: Enable scribe client
scribe-login-url:
description: Scribe login url
scribe-url:
description: Scribe API Url
structured:
description: Enable structured logger
timeout:
description: Timeout duration
verbose:
description: Log verbosity level [-v,--verbose=1] = info, [-vv,--verbose=2] = debug
- name: valint verify
id: valint_verify
uses: scribe-security/[email protected]
with:
target: 'busybox:latest'
Use
master
instead of tag to automatically pull latest version.
If you prefer using a custom configuration file instead of specifying arguments directly, you have two choices. You can either place the configuration file in the default path, which is .valint.yaml
, or you can specify a custom path using the config
argument.
For a comprehensive overview of the configuration file's structure and available options, please refer to the CLI configuration documentation.
Attestations allow you to sign and verify your targets.
Attestations allow you to connect PKI-based identities to your evidence and policy management.
Supported outputs:
- In-toto predicate - CycloneDX SBOM, SLSA Provenance (unsigned evidence)
- In-toto statements - CycloneDX SBOM, SLSA Provenance (unsigned evidence)
- In-toto attestations -CycloneDX SBOM, SLSA Provenance (signed evidence)
Select default configuration using --attest.default
flag.
Select a custom configuration by providing cocosign
field in the configuration or custom path using --attest.config
.
Scribe uses the cocosign library we developed to deal with digital signatures for signing and verification.
GitHub exposes secrets from its vault using environment variables, you may provide these environments as secret to Valint.
Paths names prefixed with
env://[NAME]
are read from the environment matching the name.
GitHub Secret Vault
X509 Signer enables the utilization of environments for supplying key, certificate, and CA files in order to sign and verify attestations. It is commonly employed in conjunction with Secret Vaults, where secrets are exposed through environments.
path names prefixed with
env://[NAME]
are extracted from the environment corresponding to the specified name.
For example the following configuration and Job.
configuration File, .valint.yaml
attest:
default: "" # Set custom configuration
cocosign:
signer:
x509:
enable: true
private: env://SIGNER_KEY
cert: env://SIGNER_CERT
ca: env://COMPANY_CA
verifier:
x509:
enable: true
cert: env://SIGNER_CERT
ca: env://COMPANY_CA
Job example
name: github_vault_workflow
on:
push:
tags:
- "*"
jobs:
scribe-sign-verify
runs-on: ubuntu-latest
steps:
uses: scribe-security/action-bom-cli@master
with:
target: busybox:latest
format: attest
env:
SIGNER_KEY: ${{ secrets.SIGNER_KEY }}
SIGNER_CERT: ${{ secrets.SIGNER_KEY }}
COMPANY_CA: ${{ secrets.COMPANY_CA }}
uses: scribe-security/action-verify-cli@master
with:
target: busybox:latest
input-format: attest
env:
SIGNER_CERT: ${{ secrets.SIGNER_KEY }}
COMPANY_CA: ${{ secrets.COMPANY_CA }}
Target types are types of artifacts produced and consumed by your supply chain. Using supported targets, you can collect evidence and verify compliance on a range of artifacts.
Fields specified as [target] support the following format.
[scheme]:[name]:[tag]
Backwards compatibility: It is still possible to use the
type: [scheme]
,target: [name]:[tag]
format.
Sources | target-type | scheme | Description | example |
---|---|---|---|---|
Docker Daemon | image | docker | use the Docker daemon | docker:busybox:latest |
OCI registry | image | registry | use the docker registry directly | registry:busybox:latest |
Docker archive | image | docker-archive | use a tarball from disk for archives created from "docker save" | image |
OCI archive | image | oci-archive | tarball from disk for OCI archives | oci-archive:path/to/yourimage.tar |
Remote git | git | git | remote repository git | git:https://github.com/yourrepository.git |
Local git | git | git | local repository git | git:path/to/yourrepository |
Directory | dir | dir | directory path on disk | dir:path/to/yourproject |
File | file | file | file path on disk | file:path/to/yourproject/file |
Each storer can be used to store, find and download evidence, unifying all the supply chain evidence into a system is an important part to be able to query any subset for policy validation.
Type | Description | requirement |
---|---|---|
scribe | Evidence is stored on scribe service | scribe credentials |
OCI | Evidence is stored on a remote OCI registry | access to a OCI registry |
Scribe evidence store allows you store evidence using scribe Service.
Related Flags:
Note the flag set:
scribe-client-id
scribe-client-secret
scribe-enable
Integrating Scribe Hub with your environment requires the following credentials that are found in the Integrations page. (In your Scribe Hub go to integrations)
- Client ID
- Client Secret
-
Add the credentials according to the GitHub instructions. Based on the code example below, be sure to call the secrets clientid for the client_id, and clientsecret for the client_secret.
-
Use the Scribe custom pipe as shown in the example bellow
name: scribe_github_workflow
on:
push:
tags:
- "*"
jobs:
scribe-sign-verify
runs-on: ubuntu-latest
steps:
uses: scribe-security/action-bom-cli@master
with:
target: [target]
format: [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
scribe-enable: true
scribe-client-id: ${{ secrets.clientid }}
scribe-client-secret: ${{ secrets.clientsecret }}
uses: scribe-security/action-verify-cli@master
with:
target: [target]
input-format: [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
scribe-enable: true
scribe-client-id: ${{ secrets.clientid }}
scribe-client-secret: ${{ secrets.clientsecret }}
You can store the Provenance Document in alternative evidence stores. You can learn more about them here.
You can learn more about alternative stores here.
OCI Evidence store
Valint supports both storage and verification flows for `attestations` and `statement` objects utilizing OCI registry as an evidence store.Using OCI registry as an evidence store allows you to upload, download and verify evidence across your supply chain in a seamless manner.
Related flags:
oci
Enable OCI store.oci-repo
- Evidence store location.
Evidence can be stored in any accusable registry.
- Write access is required for upload (generate).
- Read access is required for download (verify).
You must first login with the required access privileges to your registry before calling Valint.
For example, using docker login
command or docker/login-action
action.
name: scribe_github_workflow
on:
push:
tags:
- "*"
jobs:
scribe-sign-verify
runs-on: ubuntu-latest
steps:
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ${{ env.my_registry }}
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Generate evidence step
uses: scribe-security/action-bom-cli@master
with:
target: [target]
format: [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
oci: true
oci-repo: [oci_repo]
- name: Verify policy step
uses: scribe-security/action-verify-cli@master
with:
target: [target]
input-format: [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
oci: true
oci-repo: [oci_repo]
By default action runs in its own pid namespace as the root user.
You change users you can use the USERID
and USERNAME
env
- name: Generate cyclonedx json SBOM
uses: scribe-security/action-bom-cli@master
with:
target: 'busybox:latest'
format: json
env:
USERID: 1001
USERNAME: runner
Verify target (SBOM)
Verify targets against a signed attestation.
Default attestation config: sigstore-github
- Sigstore (Fulcio, Rekor).
Valint will look for either an SBOM or SLSA attestation to verify against.
- name: valint verify
uses: scribe-security/action-verify-cli@master
with:
target: 'busybox:latest'
Verify target (SLSA)
Verify targets against a signed attestation.
Default attestation config: sigstore-github
- Sigstore (Fulcio, Rekor).
Valint will look for either an SBOM or SLSA attestation to verify against.
- name: valint verify
uses: scribe-security/action-verify-cli@master
with:
target: 'busybox:latest'
input-format: attest-slsa
Verify target (Generic)
Verify targets against a signed attestation.
Default attestation config: sigstore-github
- Sigstore (Fulcio, Rekor).
Valint will look for either an SBOM or SLSA attestation to verify against.
- name: valint verify
uses: scribe-security/action-verify-cli@master
with:
target: 'busybox:latest'
input-format: attest-generic
Verify Policy flow - image target (Signed SBOM)
Full job example of a image signing and verifying flow.
valint-busybox-test:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
id-token: write
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: valint attest
id: valint_attest
uses: scribe-security/action-bom-cli@master
with:
target: 'busybox:latest'
format: attest
force: true
- name: valint verify
id: valint_verify
uses: scribe-security/action-verify-cli@master
with:
target: 'busybox:latest'
- uses: actions/upload-artifact@v2
with:
name: valint-busybox-test
path: scribe/valint
Verify Policy flow - image target (Signed SLSA)
Full job example of a image signing and verifying flow.
valint-busybox-test:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
id-token: write
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: valint attest slsa
id: valint_attest
uses: scribe-security/action-bom-cli@master
with:
target: 'busybox:latest'
format: attest-slsa
force: true
- name: valint verify attest slsa
id: valint_verify
uses: scribe-security/action-verify-cli@master
with:
target: 'busybox:latest'
input-format: attest-slsa
- uses: actions/upload-artifact@v2
with:
name: valint-busybox-test
path: scribe/valint
Verify Policy flow - Directory target (Signed SBOM)
Full job example of a directory signing and verifying flow.
valint-dir-test:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
id-token: write
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: valint attest workdir
id: valint_attest_dir
uses: scribe-security/action-bom-cli@master
with:
type: dir
target: '/GitHub/workspace/'
format: attest
force: true
- name: valint verify workdir
id: valint_verify_dir
uses: scribe-security/action-verify-cli@master
with:
type: dir
target: '/GitHub/workspace/'
- uses: actions/upload-artifact@v2
with:
name: valint-workdir-evidence
path: |
scribe/valint
Verify Policy flow - Git repository target (Signed SBOM)
Full job example of a git repository signing and verifying flow.
Support for both local (path) and remote git (URL) repositories.
valint-dir-test:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
id-token: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: valint attest local repo
id: valint_attest_dir
uses: scribe-security/action-bom-cli@master
with:
type: git
target: '/GitHub/workspace/my_repo'
format: attest
force: true
- name: valint verify local repo
id: valint_verify_dir
uses: scribe-security/action-verify-cli@master
with:
type: git
target: '/GitHub/workspace/my_repo'
- uses: actions/upload-artifact@v3
with:
name: valint-git-evidence
path: |
scribe/valint
Attest and verify evidence on OCI (SBOM, SLSA)
Store any evidence on any OCI registry.
Support storage for all targets and both SBOM and SLSA evidence formats.
Use input variable
format
to select between supported formats.
Write permission tooci-repo
is required.
valint-dir-test:
runs-on: ubuntu-latest
permissions:
id-token: write
env:
DOCKER_CONFIG: $HOME/.docker
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ${{ env.REGISTRY_URL }}
username: ${{ secrets.REGISTRY_USERNAME }}
password: ${{ secrets.REGISTRY_TOKEN }}
- uses: scribe-security/action-bom-cli@master
id: valint_attest
with:
target: busybox:latest
force: true
format: attest
oci: true
oci-repo: ${{ env.REGISTRY_URL }}/attestations
Following actions can be used to verify a target over the OCI store.
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ${{ env.REGISTRY_URL }}
username: ${{ secrets.REGISTRY_USERNAME }}
password: ${{ secrets.REGISTRY_TOKEN }}
- uses: scribe-security/action-verify-cli@master
id: valint_attest
with:
target: busybox:latest
input-format: attest
oci: true
oci-repo: ${{ env.REGISTRY_URL }}/attestations
Read permission to
oci-repo
is required.
Install Valint (tool)
Install Valint as a tool:
- name: install valint
uses: scribe-security/action-installer@master
- name: valint run
run: |
valint --version
valint bom busybox:latest
It's recommended to add an output directory value to your .gitignore file.
By default add **/scribe
to your .gitignore
.