Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 118 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 5 additions & 1 deletion action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
6 changes: 5 additions & 1 deletion dist/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down