Scribe GitHub Action for `valint slsa`

valint slsa is used to generate SLSA Provenance type evidence. The Provenance generation includes options to collect and embedd different data items into the Provenance document.

Further documentation GitHub integration

SLSA Action

This action allows users to generate and manage evidence collection process.

SLSA provenance 1.0 evidence support.
Generates detailed SLSA Provenance documents for images, directories, files and git repositories targets.
Store and manage evidence on Scribe service.
Attach evidence to any OCI registry.
Generate evidence directly from your private OCI registry.
Customizable SLSA Provenance:
- Adding by-products files.
- Custom invocation, external params and other fields.
Signing - Generate In-Toto Attestation.
Support Sigstore keyless verifying as well as Github workload identity.
Attach GitHub workflows environment context (git url , commit, workflow, job, run id ..).

Containerized actions limit's the ability to generate evidence on a target located outside the working directory (directory or git targets).
To overcome the limitation install tool directly - installer

Input arguments

  target:
    description: Target object name format=[<image:tag>, <dir path>, <git url>]
    required: true
  all-env:
    description: Attach all environment variables
  build-type:
    description: Set build type
  builder-id:
    description: Set builder id
  by-product:
    description: Attach by product path
  components:
    description: Select by products components groups, options=[metadata layers packages syft files dep commits]
  external:
    description: Add build external parameters
  finished-on:
    description: Set metadata finished time (YYYY-MM-DDThh:mm:ssZ)
  force:
    description: Force overwrite cache
  format:
    description: Evidence format, options=[statement attest]
  invocation:
    description: Set metadata invocation ID
  predicate:
    description: Import predicate path
  started-on:
    description: Set metadata started time (YYYY-MM-DDThh:mm:ssZ)
  statement:
    description: Import statement path
  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
  deliverable:
    description: Mark as deliverable, options=[true, false]
  depth:
    description: Git clone depth
  disable-crl:
    description: Disable certificate revocation verificatoin
  env:
    description: Environment keys to include in evidence
  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
  platform:
    description: Select target platform, examples=windows/armv6, arm64 ..)
  predicate-type:
    description: Custom Predicate type (generic evidence format)
  product-key:
    description: Product Key
  product-version:
    description: Product Version
  rule-args:
    description: Policy arguments
  scribe-auth-audience:
    description: Scribe auth audience
  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

Output arguments

  OUTPUT_PATH:
    description: 'evidence output file path'

Usage

Containerized action can be used on Linux runners as following

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@v1.4.1
  with:
    target: 'busybox:latest'

Composite Action can be used on Linux or Windows runners as following

- name: Generate cyclonedx json SBOM
  uses: scribe-security/action-slsa-cli@v1.4.1
  with:
    target: 'hello-world:latest'

Use master instead of tag to automatically pull latest version.

Configuration

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

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 statements SLSA Provenance (unsigned evidence)
In-toto attestations 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 signing and verification.

See details In-toto spec

By default Github actions use sigstore-github flow, Github provided workload identities, this will allow using the workflow identity (token-id permissions is required).

Storing Keys in GitHub Secrets

Github exposes secrets to the pipeline using environment variables, you may provide these environments as secrets 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-slsa@master
        with:
          target: busybox:latest
          format: attest
        env:
          SIGNER_KEY: ${{ secrets.SIGNER_KEY }}
          SIGNER_CERT: ${{ secrets.SIGNER_CERT }}
          COMPANY_CA:  ${{ secrets.COMPANY_CA }}

        uses: scribe-security/action-verify@master
        with:
          target: busybox:latest
          input-format: attest
        env:
          SIGNER_CERT: ${{ secrets.SIGNER_CERT }}
          COMPANY_CA:  ${{ secrets.COMPANY_CA }}

Target types - `[target]`

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.

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

Evidence Stores

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

Scribe evidence store allows you store evidence using scribe Service.

Related Flags:

Note the flag set:
scribe-client-id
scribe-client-secret
scribe-enable

Before you begin

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 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 actions as shown in the example bellow

Usage

name:  scribe_github_workflow

on: 
  push:
    tags:
      - "*"

jobs:
  scribe-sign-verify:
    runs-on: ubuntu-latest
    steps:

      - uses: scribe-security/action-slsa@master
        with:
          target: [target]
          format: [statement, attest]
          scribe-enable: true
          scribe-client-id: ${{ secrets.clientid }}
          scribe-client-secret: ${{ secrets.clientsecret }}

      - uses: scribe-security/action-verify@master
        with:
          target: [target]
          input-format: [statement-slsa, attest-slsa]
          scribe-enable: true
          scribe-client-id: ${{ secrets.clientid }}
          scribe-client-secret: ${{ secrets.clientsecret }}

Alternative evidence stores

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.

Before you begin

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.

Usage

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-slsa@master
        with:
          target: [target]
          format: [statement attest predicate] (default [statement])
          oci: true
          oci-repo: [oci_repo]

      - name:  Verify policy step
        uses: scribe-security/action-verify@master
        with:
          target: [target]
          input-format: [statement attest predicate] (default [statement])
          oci: true
          oci-repo: [oci_repo]

Running action as non root user

By default, the action runs in its own pid namespace as the root user. You can change the user by setting specific USERID and USERNAME environment variables.

- name: Generate cyclonedx json SBOM
  uses: scribe-security/action-bom@master
  with:
    target: 'busybox:latest'
    format: json
  env:
    USERID: 1001
    USERNAME: runner

Non root user with HIGH UID/GID

By default, the action runs in its own pid namespace as the root user. If the user uses a high UID or GID, you must specify all the following environment variables. You can change the user by setting specific `USERID` and `USERNAME` variables. Additionally, you may group the process by setting specific `GROUPID` and `GROUP` variables.

- name: Generate cyclonedx json SBOM
  uses: scribe-security/action-bom@master
  with:
    target: 'busybox:latest'
    format: json
  env:
    USERID: 888000888
    USERNAME: my_user
    GROUPID: 777000777
    GROUP: my_group

```

Platform-Specific Image Handling

The Valint tool is compatible with both Linux and Windows images. Set the desired platform using the 'platform' field in your configuration:

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    target: hello-world:latest
    platform: linux/amd64

Docker is configured by default to pull images matching the runner's platform. For analyzing images across different platforms, you need to pull the image from the registry and specify the platform.

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    target: registry:hello-world:latest
    platform: windows/amd64

Windows Runner Compatibility

On Windows Github runners, containerized actions are currently not supported. It's recommended to use CLI actions in such cases.

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa-cli@master
  with:
    target: hello-world:latest

Basic examples

Public registry image

Create SLSA for remote busybox:latest image.

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    target: 'busybox:latest'
    format: statement

Docker built image

Create SLSA for image built by local docker image_name:latest.

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    type: docker
    target: 'image_name:latest'
    format: json
    force: true

Private registry image

Create SLSA for image hosted by a private registry.

DOCKER_CONFIG environment will allow the containerized action to access the private registry.

env:
  DOCKER_CONFIG: $HOME/.docker
steps:
  - name: Login to GitHub Container Registry
    uses: docker/login-action@v2
    with:
      registry: ${{ env.REGISTRY_URL }}
      username: ${{ secrets.REGISTRY_USERNAME }}
      password: ${{ secrets.REGISTRY_TOKEN }}

  - name: Generate SLSA provenance
    uses: scribe-security/action-slsa@master
    with:
      target: 'scribesecurity.jfrog.io/scribe-docker-local/example:latest'
      force: true

Custom metadata

Custom metadata added to SLSA.

- name: Generate SLSA provenance - add metadata - labels, envs
  id: valint_labels
  uses: scribe-security/action-slsa@master
  with:
      target: 'busybox:latest'
      force: true
      env: test_env
      label: test_label
  env:
    test_env: test_env_value

Save as artifact

Using GitHub's built-in action output argument OUTPUT_PATH you can access the generated SLSA and store it as an artifact.

Use action output-file: <my_custom_path> input argument to set a custom output path.

- name: Generate SLSA provenance
  id: valint_json
  uses: scribe-security/action-slsa@master
  with:
    target: 'busybox:latest'
    output-file: my_slsa.json

- uses: actions/upload-artifact@v2
  with:
    name: scribe-slsa
    path: ${{ steps.valint_json.outputs.OUTPUT_PATH }}

- uses: actions/upload-artifact@v2
  with:
    name: scribe-evidence
    path: scribe/

Save provenance statement as artifact

Using action OUTPUT_PATH output argument you can access the generated SLSA provenance statement and store it as an artifact.

Use action output-file: <my_custom_path> input argument to set a custom output path.

- name: Generate SLSA provenance statement
  id: valint_slsa_statement
  uses: scribe-security/action-slsa@master
  with:
    target: 'busybox:latest'
    format: statement-slsa

- uses: actions/upload-artifact@v2
  with:
    name: provenance
    path: ${{ steps.valint_slsa_statement.outputs.OUTPUT_PATH }}

Docker archive image

Create SLSA for local docker save ... output.

- name: Build and save local docker archive
  uses: docker/build-push-action@v2
  with:
    context: .
    file: .GitHub/workflows/fixtures/Dockerfile_stub
    tags: scribesecurity.jfrog.io/scribe-docker-local/example:latest
    outputs: type=docker,dest=stub_local.tar

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    type: docker-archive
    target: '/GitHub/workspace/stub_local.tar'

OCI archive image

Create SLSA for the local oci archive.

- name: Build and save local oci archive
  uses: docker/build-push-action@v2
  with:
    context: .
    file: .GitHub/workflows/fixtures/Dockerfile_stub
    tags: scribesecurity.jfrog.io/scribe-docker-local/example:latest
    outputs: type=oci,dest=stub_oci_local.tar

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    type: oci-archive
    target: '/GitHub/workspace/stub_oci_local.tar'

Directory target

Create SLSA for a local directory.

- name: Create dir
  run: |
    mkdir testdir
    echo "test" > testdir/test.txt

- name: valint attest dir
  id: valint_attest_dir
  uses: scribe-security/action-slsa@master
  with:
    type: dir
    target: 'testdir'

Git target

Create SLSA for mongo-express remote git repository.

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    type: git
    target: 'https://github.com/mongo-express/mongo-express.git'
    format: json

Create SLSA for my_repo local git repository.

- uses: actions/checkout@v3
  with:
    fetch-depth: 0
    path: my_repo

- name: Generate SLSA provenance
  uses: scribe-security/action-slsa@master
  with:
    type: git
    target: 'my_repo'
    format: json

Attest target

Create and sign SLSA targets.
By default the sigstore-github flow is used, GitHub workload identity and Sigstore (Fulcio, Rekor).

Default attestation config Required id-token permission access.

job_example:
  runs-on: ubuntu-latest
  permissions:
    id-token: write
  steps:
    - name: valint attest
      uses: scribe-security/action-slsa@master
      with:
          target: 'busybox:latest'
          format: attest

Attest target (SLSA depricated)

Create and sign SLSA targets.
By default the sigstore-github flow is used, GitHub workload identity and Sigstore (Fulcio, Rekor).

Default attestation config Required id-token permission access.

job_example:
  runs-on: ubuntu-latest
  permissions:
    id-token: write
  steps:
    - name: valint attest
    uses: scribe-security/action-slsa@master
    with:
        target: 'busybox:latest'
        format: attest-slsa

Verify target

Verify targets against a signed attestation.

Default attestation config: sigstore-github - sigstore (Fulcio, Rekor).
valint will look for both a bom or slsa attestation to verify against.

- name: valint verify
  uses: scribe-security/action-verify@master
  with:
    target: 'busybox:latest'

Verify target

Verify targets against a signed attestation.

Default attestation config: sigstore-github - sigstore (Fulcio, Rekor).
Tool will look for slsa or slsa attestation to verify against.

- name: valint verify
  uses: scribe-security/action-verify@master
  with:
    target: 'busybox:latest'
    input-format: attest-slsa

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
        id: valint_attest
        uses: scribe-security/action-slsa@master
        with:
           target: 'busybox:latest'
           format: attest
           force: true

      - name: valint verify
        id: valint_verify
        uses: scribe-security/action-verify@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 depricated)

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-slsa@master
        with:
           target: 'busybox:latest'
           format: attest-slsa
           force: true

      - name: valint verify attest slsa
        id: valint_verify
        uses: scribe-security/action-verify@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 SLSA)

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-slsa@master
        with:
           type: dir
           target: '/GitHub/workspace/'
           format: attest
           force: true

      - name: valint verify workdir
        id: valint_verify_dir
        uses: scribe-security/action-verify@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 SLSA)

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-slsa@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@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

Store any evidence on any OCI registry.
Support storage for all targets and both SLSA and SLSA evidence formats.

Use input variable format to select between supported formats.
Write permission to oci-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-slsa@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@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

.gitignore

Recommended to add output directory value to your .gitignore file. By default add **/scribe to your .gitignore.

SLSA Action​

Input arguments​

Output arguments​

Usage​

Configuration​

Attestations​

Storing Keys in GitHub Secrets​

Target types - [target]​

Format​

Evidence Stores​

Scribe Evidence store​

Before you begin​

Usage​

Alternative evidence stores​

Before you begin​

Usage​

Running action as non root user​

Platform-Specific Image Handling​

Windows Runner Compatibility​

Basic examples​

.gitignore​

Other Actions​

SLSA Action

Input arguments

Output arguments

Usage

Configuration

Attestations

Storing Keys in GitHub Secrets

Target types - `[target]`

Format

Evidence Stores

Scribe Evidence store

Before you begin

Usage

Alternative evidence stores

Before you begin

Usage

Running action as non root user

Platform-Specific Image Handling

Windows Runner Compatibility

Basic examples

.gitignore

Other Actions