diff --git a/README.md b/README.md index 47c78da..d648c7b 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,133 @@ -# Witness Run Wrapper Action +# Witness Wrapper Action -A lightweight GitHub Action that reuses the Witness run action's wrapper flow so you can capture attestation for steps that run other actions or ad-hoc commands. +A lightweight GitHub Action that wraps other actions or commands to capture attestations with [Witness](https://github.com/in-toto/witness). Pre-configured with TestifySec Platform defaults for zero-config Sigstore signing and timestamping. -This repository pulls the wrapper-related pieces from the `feature/complete-rewrite-squashed` branch of [`testifysec/witness-run-action`](https://github.com/testifysec/witness-run-action) and keeps the Witness integration intact. The result is a slimmer action dedicated to wrapping other actions while still downloading Witness, constructing the correct CLI arguments, and handling environment propagation. +## Quick Start -## Usage +With the new defaults, you only need to provide your step name, command, and API token: ```yaml jobs: build: runs-on: ubuntu-latest + permissions: + id-token: write # Required for OIDC authentication with Fulcio + contents: read steps: - - uses: actions/checkout@v4 - - name: Wrap a downstream action - uses: colek42/witness-run-wrapper-action@main + - uses: testifysec/witness-wrapper@main with: - step: wrap-npm-test - action-ref: actions/setup-node@v4 - witness_version: 0.8.1 - attestations: "environment git github" + step: build + command: npm run build + env: + ARCHIVISTA_HEADERS: 'Authorization: Token ${{ secrets.TESTIFYSEC_API_TOKEN }}' ``` -Inputs mirror the original Witness run action so you can continue to configure attestors, Archivista, signer settings, and other Witness flags. Either `action-ref` or `command` must be provided (use `docker://` references when you need both). +That's it! The action automatically: +- Signs attestations using TestifySec's Fulcio CA (keyless signing via OIDC) +- Timestamps with TestifySec's TSA for long-term verification +- Uploads attestations to TestifySec's Archivista -## Development +## Wrapping Other Actions + +You can wrap existing GitHub Actions to capture attestations for their execution: + +```yaml +- uses: testifysec/witness-wrapper@main + with: + step: checkout + action-ref: actions/checkout@v4 + attestations: 'git github environment' + env: + ARCHIVISTA_HEADERS: 'Authorization: Token ${{ secrets.TESTIFYSEC_API_TOKEN }}' + +- uses: testifysec/witness-wrapper@main + with: + step: setup-node + action-ref: actions/setup-node@v4 + env: + ARCHIVISTA_HEADERS: 'Authorization: Token ${{ secrets.TESTIFYSEC_API_TOKEN }}' +``` + +## Platform Defaults + +This action is pre-configured with TestifySec Platform URLs: + +| Setting | Default Value | +|---------|---------------| +| `archivista-server` | `https://gateway.platform.testifysec.com` | +| `fulcio` | `https://fulcio.platform.testifysec.com` | +| `fulcio-oidc-issuer` | `https://token.actions.githubusercontent.com` | +| `fulcio-oidc-client-id` | `sigstore` | +| `timestamp-servers` | `https://tsa.platform.testifysec.com/api/v1/timestamp` | +| `enable-sigstore` | `true` | +| `enable-archivista` | `true` | + +## Custom Configuration + +Override any defaults as needed: + +```yaml +- uses: testifysec/witness-wrapper@main + with: + step: build + command: make build + # Override defaults for self-hosted infrastructure + archivista-server: 'https://archivista.mycompany.com' + fulcio: 'https://fulcio.mycompany.com' + timestamp-servers: 'https://tsa.mycompany.com/api/v1/timestamp' + env: + ARCHIVISTA_HEADERS: 'Authorization: Token ${{ secrets.TESTIFYSEC_API_TOKEN }}' +``` + +## Inputs -- Install dependencies with `npm install` -- Build the bundled action with `npm run build` -- Run locally via `node index.js` (ensuring required inputs are set in the environment) +### Required + +| Input | Description | +|-------|-------------| +| `step` | Name of the step being run | +| `command` or `action-ref` | Command to run, or reference to a GitHub Action (format: `owner/repo@ref`) | + +### Common Options + +| Input | Description | Default | +|-------|-------------|---------| +| `attestations` | Attestations to record | `environment git github` | +| `witness_version` | Version of Witness CLI | Latest | +| `outfile` | File to write signed data | - | +| `workingdir` | Working directory for commands | - | + +### Sigstore Options + +| Input | Description | Default | +|-------|-------------|---------| +| `enable-sigstore` | Enable Sigstore signing | `true` | +| `fulcio` | Fulcio CA address | `https://fulcio.platform.testifysec.com` | +| `fulcio-oidc-issuer` | OIDC issuer URL | `https://token.actions.githubusercontent.com` | +| `fulcio-oidc-client-id` | OIDC client ID | `sigstore` | +| `timestamp-servers` | TSA server URL | `https://tsa.platform.testifysec.com/api/v1/timestamp` | + +### Archivista Options + +| Input | Description | Default | +|-------|-------------|---------| +| `enable-archivista` | Enable Archivista storage | `true` | +| `archivista-server` | Archivista server URL | `https://gateway.platform.testifysec.com` | + +See [action.yml](action.yml) for the complete list of inputs including KMS, Vault, and SPIFFE signer options. + +## Permissions + +For OIDC authentication with Fulcio, your workflow needs the `id-token: write` permission: + +```yaml +permissions: + id-token: write + contents: read +``` + +## Development -After making changes, commit and push to publish a new version tag for GitHub Actions consumers. +- Install dependencies: `npm install` +- Build the bundled action: `npm run build` +- Run locally: `node index.js` (with required inputs set in environment) diff --git a/action.yml b/action.yml index 0e11ab8..576bc50 100644 --- a/action.yml +++ b/action.yml @@ -44,7 +44,7 @@ inputs: archivista-server: description: "URL of the Archivista server to store or retrieve attestations" required: false - default: "https://archivista.testifysec.io" + default: "https://gateway.platform.testifysec.com" # Attestor settings attestor-link-export: @@ -78,12 +78,15 @@ inputs: fulcio: description: "Fulcio address to sign with" required: false + default: "https://fulcio.platform.testifysec.com" fulcio-oidc-client-id: description: "OIDC client ID to use for authentication" required: false + default: "sigstore" fulcio-oidc-issuer: description: "OIDC issuer to use for authentication" required: false + default: "https://token.actions.githubusercontent.com" fulcio-oidc-redirect-url: description: "OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'" required: false @@ -177,6 +180,7 @@ inputs: timestamp-servers: description: "Timestamp Authority Servers to use when signing envelope" required: false + default: "https://tsa.platform.testifysec.com/api/v1/timestamp" # Hash settings hashes: diff --git a/dist/action.yml b/dist/action.yml index 0e11ab8..576bc50 100644 --- a/dist/action.yml +++ b/dist/action.yml @@ -44,7 +44,7 @@ inputs: archivista-server: description: "URL of the Archivista server to store or retrieve attestations" required: false - default: "https://archivista.testifysec.io" + default: "https://gateway.platform.testifysec.com" # Attestor settings attestor-link-export: @@ -78,12 +78,15 @@ inputs: fulcio: description: "Fulcio address to sign with" required: false + default: "https://fulcio.platform.testifysec.com" fulcio-oidc-client-id: description: "OIDC client ID to use for authentication" required: false + default: "sigstore" fulcio-oidc-issuer: description: "OIDC issuer to use for authentication" required: false + default: "https://token.actions.githubusercontent.com" fulcio-oidc-redirect-url: description: "OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'" required: false @@ -177,6 +180,7 @@ inputs: timestamp-servers: description: "Timestamp Authority Servers to use when signing envelope" required: false + default: "https://tsa.platform.testifysec.com/api/v1/timestamp" # Hash settings hashes: