CLI Tool

CLI Tool

This tool requires an account with Ossprey, and an API key, visit  ossprey.com  to sign up for free
The Ossprey CLI (ossprey) is a command-line scanner for the Ossprey supply-chain malware platform. It catalogues your project's dependencies into an custom SBOM (software bill of materials) format, submits it to the Ossprey API, and fails the build if any of those packages are known to contain malware. It parses the manifests of JS/python projects, and resolves transient dependencies with no installation.
The CLI supports:
  • Scanning a project's dependencies via the scan command
  • Ad-hoc checking of dependencies via the check command
  • JS/Python package manager pass through, check packages before installation ossprey npm i <package>etc.
The CLI ships as a single self-contained binary via  GitHub Releases . There is no pip, npm or Homebrew package. It currently covers Python and JavaScript projects.


Installation

Prebuilt binaries are published for Linux, macOS and Windows (amd64 and arm64). No interpreter or runtime is required. If you need help, please  raise an issue  on GitHub.

One-liner (Linux / macOS)

curl -fsSL https://github.com/ossprey/ossprey-cli/releases/latest/download/install.sh | sudo sh
The script detects your OS and architecture, downloads the matching binary, verifies its sha256 checksum, and installs it to /usr/local/bin/ossprey.
Before installing, check out the full contents of the script  here 
Override the defaults with environment variables to pin to a version:
# Pin a specific version
curl -fsSL https://github.com/ossprey/ossprey-cli/releases/latest/download/install.sh \
  | OSSPREY_VERSION=v0.1.0 sudo -E sh

# Install to a user-writable dir (no sudo)
curl -fsSL https://github.com/ossprey/ossprey-cli/releases/latest/download/install.sh \
  | OSSPREY_INSTALL_DIR=$HOME/.local/bin sh

Manual download

Grab the binary directly from the  releases page :
  • ossprey-linux-amd64 — Linux x86_64
  • ossprey-linux-arm64 — Linux arm64
  • ossprey-darwin-amd64 — macOS Intel
  • ossprey-darwin-arm64 — macOS Apple Silicon
  • ossprey-windows-amd64.exe — Windows x86_64
  • ossprey-windows-arm64.exe — Windows arm64
chmod +x the binary and drop it on your PATH. Each asset ships with a .sha256 sidecar for verification. Pin a specific tag by replacing latest/download with download/<tag> in the URL.

From source

git clone https://github.com/ossprey/ossprey-cli.git
cd ossprey-cli
make tidy   # first time
make build  # produces bin/ossprey
Requires Go 1.25 or above.
Once installed, verify it is working:
ossprey --version
ossprey --help


Auto scan dependencies before installation

Ossprey CLI ships with pass through support for common package managers for JS and python ecosystems. We support, npm, pip, poetry, uv, and yarn. Configuring your .bashrc or .zshrc withalias npm="ossprey npm" will allow ossprey CLI to be invoked before the NPM command. This will intercept package installations, and scan them. If we detect malware, we block the installation.

Authentication

The CLI requires an API key to submit scans to the Ossprey service. The key is read from the following sources, in order:
    --api-key flag
    OSSPREY_API_KEY environment variable (recommended for CI/CD)
The --local, --dry-run-safe and --dry-run-malicious modes do not talk to the API and do not need a key.
For details on generating and managing your API key, see the  API Keys  page in the dashboard.


scan — scan a project

Catalogue a directory and check it for malware.
ossprey scan [path] [flags]
path defaults to the current directory.
Flags:
  • -o , --output — write the OSSBOM JSON to a file, in addition to running the scan.
  • -v , --verbose — verbose logging.
  • --local — catalogue only: dump the OSSBOM to stdout and exit. No API submission, no verdict, no key required.
  • --dry-run-safe — skip API submission and emit an empty vulnerability list. No key required.
  • --dry-run-malicious — skip API submission and inject a test vulnerability against the first component. Useful for testing alerting and CI/CD failure behaviour. No key required.
  • --url — override the Ossprey API URL (default https://api.ossprey.com ).
  • --api-key — provide the API key on the command line instead of an environment variable.
  • --version — print the CLI version.

Usage examples

Scan the current directory:
export OSSPREY_API_KEY=sk_live_...
ossprey scan .
Scan a specific directory:
ossprey scan ./my-project --api-key YOUR_KEY
Dry run to test your setup (no API key needed):
ossprey scan ./my-project --dry-run-safe -v
Catalogue only, write the OSSBOM to a file:
ossprey scan . --local -o sbom-output.json


check — scan named packages

Scan one or more packages by name, without a project on disk.
ossprey check --eco-system pypi requests@2.31.0
ossprey check -e npm lodash@4.17.21 react@18.2.0
When a version is omitted, the latest published version is resolved from the registry (PyPI or npm) and checked. Both the name@version and pip's name==version forms are accepted.
Flags:
  • -e , --eco-system — package ecosystem, pypi or npm (required).
  • --url — override the Ossprey API URL.
  • --api-key — API key (or environment variable).
  • --dry-run-safe / --dry-run-malicious — same behaviour as for scan .
Exit codes match scan: 1 on a malware verdict or error, 0 otherwise.


Package-manager forwarder

Wrap an install so packages are checked before they hit your machine. If any package is flagged, the install is blocked (exit 1) and the real package manager is never invoked; otherwise the command is forwarded unchanged.
ossprey npm install foo@1.2.3 bar@2.0.0
ossprey yarn add foo@1.2.3
ossprey pip install foo==1.2.3
ossprey poetry add foo
ossprey uv pip install foo==1.2.3
Supported managers: npm, yarn, pip, poetry, uv. Non-install subcommands (npm run, pip list, …) are forwarded straight through with no check.
There are two modes, picked automatically:
  • Named packages (e.g. ossprey npm install foo bar ) — every package named on the command line is checked. Flags, local paths, archives and VCS/URL targets are passed through; only real registry packages are checked. Transitive dependencies are not resolved here — run ossprey scan after install for full-tree coverage.
  • Manifest install (e.g. bare ossprey npm install , npm ci , poetry install , uv sync , or pip install -r requirements.txt ) — no packages are named, so the forwarder scans the current directory and checks every declared dependency before forwarding. It does not fall through unchecked.
The forwarder disables flag parsing so every argument reaches the real manager, so it is configured only through the environment:
  • OSSPREY_API_KEY — API key.
  • OSSPREY_API_URL — override the API URL (default https://api.ossprey.com ).


Supported ecosystems

Python and JavaScript, via static catalogers. The CLI never executes your package manager. If your repo has only a manifest and no lockfile, expect direct dependencies only — supply a lockfile for full transitive coverage.
  • Python — requirements.txt , Pipfile.lock , poetry.lock , uv.lock , pdm.lock , setup.py , pyproject.toml , wheel / egg metadata.
  • JavaScript — package.json , package-lock.json , yarn.lock , pnpm-lock.yaml .


Exit codes

The CLI uses exit codes to communicate scan outcomes, which is important for CI/CD integration:
  • Exit 0 — no malware found, a --local dump, or the scan was skipped by the API (e.g. quota exhausted).
  • Exit 1 — malware was found, or the scan itself failed (bad path, catalog error, API/network error, missing key).
To distinguish "clean" from "errored" in CI, check stderr or parse the OSSBOM emitted via -o.


Output

ossprey scan prints No malware found on success, or one Error: WARNING: <pkg>:<ver> contains malware. Remediate this immediately line per finding on failure.
Pass -o sbom.json to also write the full OSSBOM JSON (components and vulnerabilities) to disk, or --local to emit it to stdout instead of calling the API.


CI/CD integration

GitHub Actions

The Ossprey CLI works as a step in any GitHub Actions workflow. Here is an example that scans your repository on every pull request:
name: Ossprey Scan
on:
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Ossprey
        run: curl -fsSL https://github.com/ossprey/ossprey-cli/releases/<VERSION>/download/install.sh | sudo sh

      - name: Run Ossprey scan
        env:
          OSSPREY_API_KEY: ${{ secrets.OSSPREY_API_KEY }}
        run: ossprey scan .
The CLI exits non-zero on a malware verdict, which fails the workflow.
Store your API key as a  GitHub Actions secret  called OSSPREY_API_KEY. Never hard-code your key in a workflow file.

Other CI/CD systems

The CLI is a single static binary with no runtime dependencies, so it works in any environment. Install it via the one-liner or a pre-downloaded binary, set OSSPREY_API_KEY, and run ossprey scan . as a build step.