pkgradar-cli

PkgRadar's CI gate and static package scanner as a single binary, plus the GitHub Actions composite that wraps it.

pkgradar gate --lockfile package-lock.json --fail-on high

This repo is the entire installable surface area for the gate. Fork, vendor, audit, or run it as-is — there's no closed-source path to the binary you run.

Install

Prebuilt binaries

Each release tag (v0.1.0+) attaches binaries for:

• pkgradar-x86_64-unknown-linux-gnu.tar.gz
• pkgradar-aarch64-unknown-linux-gnu.tar.gz
• pkgradar-x86_64-apple-darwin.tar.gz
• pkgradar-aarch64-apple-darwin.tar.gz

TAG=$(curl -sSfL https://api.github.com/repos/PkgRadar/pkgradar-cli/releases/latest \
  | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": "([^"]+)".*/\1/')
ARCH=$(uname -m); OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case "$OS-$ARCH" in
  linux-x86_64)   ASSET="pkgradar-x86_64-unknown-linux-gnu.tar.gz" ;;
  linux-aarch64)  ASSET="pkgradar-aarch64-unknown-linux-gnu.tar.gz" ;;
  darwin-x86_64)  ASSET="pkgradar-x86_64-apple-darwin.tar.gz" ;;
  darwin-arm64)   ASSET="pkgradar-aarch64-apple-darwin.tar.gz" ;;
esac
curl -sSfL "https://github.com/PkgRadar/pkgradar-cli/releases/download/${TAG}/${ASSET}" \
  | tar -xz
sudo install -m 0755 pkgradar /usr/local/bin/

From crates.io

cargo install pkgradar --locked

From source

git clone https://github.com/PkgRadar/pkgradar-cli
cd pkgradar-cli
cargo install --path . --locked

GitHub Actions

The composite action lives at the root of this repo, so you can use it directly without specifying a subpath:

- uses: PkgRadar/pkgradar-cli@v1
  with:
    token: ${{ secrets.PKGRADAR_TOKEN }}
    fail-on: high
    # lockfile: pnpm-lock.yaml   # optional override; auto-detects otherwise

The action prefers a prebuilt binary from this repo's releases for fast cold-start (~10s) and falls back to cargo install when the runner platform isn't in the release matrix.

GitLab CI

A ready-made template is hosted on pkgradar.com:

include:
  - remote: 'https://pkgradar.com/templates/pkgradar.gitlab-ci.yml'

pkgradar-gate:
  extends: .pkgradar-base
  stage: test
  variables:
    PKGRADAR_FAIL_ON: high

PKGRADAR_TOKEN must be set in Settings → CI/CD → Variables.

Configure

export PKGRADAR_TOKEN="rps_..."
export PKGRADAR_BASE_URL="https://pkgradar.com"   # optional

Or commit a .pkgradar.yml at the root of your repo:

fail_on: high
timeout_ms: 30000
fail_open: true
allowlist:
  - "@types/node@22.5.4"   # reviewed and approved internally
watchlist:
  - "react@18.3.1"

CLI flags override the config file on conflict.

Commands

pkgradar gate

Asks the gate endpoint whether each spec should be blocked. Exits non-zero when any spec breaches --fail-on. Combine with --lockfile to batch every transitive in one call.

pkgradar gate lodash@4.17.21 left-pad@1.3.0 --fail-on high
pkgradar gate --lockfile pnpm-lock.yaml --fail-on review

pkgradar scan

Returns the full scan report rather than the gate decision. Use this when you want to see why a release would be blocked.

pkgradar scan @scope/name@1.2.3 --format json | jq '.[0].findings'
pkgradar scan --lockfile yarn.lock --format json

pkgradar version

Prints the binary version and the resolved API endpoint.

Lockfile support

The parser deduplicates by (name, version) and skips non-registry refs (file:, link:, workspace:, git+, github:).

Fail-open behaviour

Network or transport-level errors (timeout, 5xx, DNS) print a warning and exit 0 by default — security tooling shouldn't take down a deploy pipeline because PkgRadar had a 30-second blip. Set fail_open: false in .pkgradar.yml (or pass --no-fail-open) once your gate cadence is stable.

Exit codes

Building locally

cargo build --release
./target/release/pkgradar --help
cargo test --release

The binary is statically linked against rustls-tls-native-roots, so it picks up the host's CA bundle and doesn't link OpenSSL at runtime.

License

Apache-2.0. See LICENSE.