pinprick-action

Run pinprick from GitHub Actions.

pinprick audits GitHub Actions supply chain security by finding runtime fetch patterns that bypass pinning, checking action references, and reporting results through an explainable, open scoring rubric.

This wrapper installs pinprick from GitHub releases and always verifies the downloaded archive's sha256 digest. For attested engine releases it also checks that provenance was issued by pinprick's release workflow, subject to the fail-open and strict modes described below, before extracting the binary.

Quickstart

Usage with GitHub Advanced Security

This is the default mode. The action emits SARIF and uploads findings to GitHub code scanning so they appear in the repository's Security tab.

In this mode, the action does not fail the workflow when pinprick reports findings unless fail-on-findings: true is set. Use GitHub rulesets if you want code scanning alerts to block merges.

Run SARIF upload on trusted events such as push or workflow_dispatch. Pull requests from forks receive a read-only token, so SARIF upload can fail there; use console mode for pull request feedback.

name: GitHub Actions supply chain audit

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions: {}

jobs:
  pinprick:
    runs-on: ubuntu-24.04
    permissions:
      security-events: write
      contents: read # needed for checkout and private/internal repositories
      actions: read # needed for private/internal repositories
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Run pinprick
        uses: starhaven-io/pinprick-action@d1ad02330903473ce59ddb88b88ae36f4a4e0bf5 # v0.6.8
        with:
          no-repo-config: true

Usage without GitHub Advanced Security

Set advanced-security: false to print results to the workflow log instead of uploading SARIF. This mode is suitable for pull requests from forks.

name: GitHub Actions supply chain audit

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - "**"

permissions: {}

jobs:
  pinprick:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Run pinprick
        uses: starhaven-io/pinprick-action@d1ad02330903473ce59ddb88b88ae36f4a4e0bf5 # v0.6.8
        with:
          advanced-security: false
          no-repo-config: true

Each example pins pinprick-action to a full commit SHA with the release tag in a trailing comment, not a mutable tag. That is exactly the pinning pinprick itself checks for; bump the SHA when you adopt a newer release.

Fail on findings

- name: Run pinprick
  uses: starhaven-io/pinprick-action@d1ad02330903473ce59ddb88b88ae36f4a4e0bf5 # v0.6.8
  with:
    fail-on-findings: true

Supported runners

Runner	Architecture
ubuntu-24.04, ubuntu-26.04, ubuntu-slim	Linux x64
ubuntu-24.04-arm, ubuntu-26.04-arm	Linux ARM64
macos-15, macos-26, xcode-27	macOS ARM64

Support is limited to the labels above. The xcode-27 preview label reports through a self-test job excluded from the required conclusion check. Both stable and preview tests require provenance verification. Floating *-latest runner aliases are not part of the tested support contract. Everything else is unsupported, including self-hosted runners, containers, and any environment with glibc older than 2.39. pinprick publishes no x86_64 macOS or Windows build.

Inputs

Input	Default	Description
version	0.31.0	pinprick version to install, pinned by default for deterministic runs. Use latest for the newest, or an exact version like v0.31.0.
path	.	Repository path to scan.
advanced-security	true	Emit SARIF and upload it to GitHub code scanning.
sarif-category	pinprick	Code scanning category for the upload. Use a unique value for each invocation in the same workflow.
fail-on-findings	false	Fail the workflow when pinprick reports findings. Internal errors always fail.
strict-provenance	false	Require provenance verification to run: fail instead of warn when the attestation cannot be checked.
no-repo-config	true	Ignore the scanned repository's .pinprick.toml and audit with the global config or defaults, preventing a pull request from suppressing its own findings.

pinprick supports severity filtering through .pinprick.toml, not an audit CLI flag, so this action does not expose a min-severity input.

Set no-repo-config: false only when you deliberately trust and want to apply the scanned repository's policy. On pull request workflows, leaving the secure default in place prevents a contributor-controlled .pinprick.toml from hiding the contributor's workflow findings.

Outputs

Output	Description
exit-code	pinprick audit exit code.
sarif-file	Filepath to usable SARIF results when advanced-security: true and the audit exits 0 or 1.

Each invocation keeps its download and SARIF output in a separate runner temporary directory, so later invocations preserve earlier sarif-file outputs.

Permissions

Start workflows with permissions: {} and grant permissions only at the job that runs pinprick.

Permission	Required when
security-events: write	advanced-security: true uploads SARIF to code scanning.
contents: read	Checking out the repository, and Advanced Security on private/internal repositories.
actions: read	Advanced Security on private/internal repositories.

The action passes the workflow's GITHUB_TOKEN to pinprick so it can fetch and audit external action source when the job permissions allow it. Without a token, pinprick still scans local workflow run: blocks and local actions.

Provenance verification

Every install requires canonical release metadata, verifies the downloaded archive's sha256 digest, and checks that the binary reports the resolved engine version. For attested releases, it then asks gh attestation verify to require an attestation from starhaven-io/pinprick's release workflow on main, signed on a GitHub-hosted runner.

Verification fails open by default: when gh is missing or too old, or no GitHub token is available, the action warns and continues on the strength of the checksum and version checks alone. An exact engine release that predates attestations retains this compatibility behavior, but version: latest is never allowed to resolve to such a release. Set strict-provenance: true to require that attestation verification actually ran, turning every unverifiable condition into a hard failure:

- name: Run pinprick
  uses: starhaven-io/pinprick-action@d1ad02330903473ce59ddb88b88ae36f4a4e0bf5 # v0.6.8
  with:
    strict-provenance: true

Exit Behavior

pinprick uses these exit codes:

Code	Meaning	Action behavior
0	Clean	Succeeds.
1	Findings present	Succeeds by default; fails only with fail-on-findings: true.
2+	Error	Fails.

In Advanced Security mode, SARIF upload happens before optional fail-on-findings failure so findings are still available in code scanning.

Versioning

Each release of this action pins a specific pinprick version through the version default, so a workflow pinned to a given action ref installs the same pinprick version on every run. Each download is verified as described above. To move to a newer pinprick, bump the action to a release whose default targets it, or set version yourself (including latest, if you accept non-deterministic installs).

There is deliberately no floating major tag such as @v1: a mutable tag resolved at run time is exactly the pattern pinprick audits workflows for. Pin a full commit SHA with the release tag in a trailing comment, as every example above does, and bump it deliberately when adopting a new release.

License

This action wrapper is licensed under the MIT License. See LICENSE.

The pinprick engine downloaded and run by this action is a separate project licensed under the GNU Affero General Public License v3.0 only. Using this wrapper does not relicense pinprick or change pinprick's license terms.

Acknowledgements

This action's composite structure was inspired by zizmor-action (MIT, © William Woodruff).