Cargo Scanner

Cargo Scanner scans inbound artifacts before you unpack or ship them. It wraps Grype, Trivy, and Syft behind one CLI so you can check downloaded files, build outputs, archives, containers, and local package artifacts with the same workflow.

Who It Is For

• People who want to scan files already on their machine, especially downloads and unpacked build artifacts.
• Developers who want one command for vulnerability reports and SBOMs.
• CI jobs that need a containerized scanner runtime.
• Teams that already use Grype, Trivy, or Syft but want a consistent local UX.

Fastest Start

curl -fsSL https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.sh | sh
cargo-scanner doctor --fix
cargo-scanner scan

Prefer direct commands:

cargo-scanner scan .
cargo-scanner ./artifact.jar -F high

Running cargo-scanner opens a small dashboard. Running cargo-scanner scan without a target starts a short conversation that asks only the questions needed for that scan: target, optional recursive mode for folders, result type, and output. Choosing a custom target asks for one direct path input with tab path completion. Grype and Trivy ask vulnerability-focused questions such as fail threshold and report format. Syft switches to SBOM-focused questions. The target step defaults to the current folder and only asks for a path when you want to scan somewhere else.

Install

Install the latest release with checksum verification:

curl -fsSL https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.sh | sh

Windows PowerShell:

iwr https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.ps1 -UseBasicParsing | iex

Install a specific release:

CARGO_SCANNER_VERSION=vX.Y.Z sh -c "$(curl -fsSL https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.sh)"

Windows PowerShell:

$env:CARGO_SCANNER_VERSION = "vX.Y.Z"; iwr https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.ps1 -UseBasicParsing | iex

Install with Go:

go install github.com/opencomputinggarage/cargo-scanner/cmd/cargo-scanner@latest

After installing, future binary updates can be applied in place:

cargo-scanner update --check
cargo-scanner update

Download archives directly from the latest release for macOS, Linux, and Windows.

Homebrew users can build from this repo:

brew install --HEAD ./Formula/cargo-scanner.rb

First Run

For personal machines, use the managed runtime. Cargo Scanner installs scanner CLIs under ~/.cargo-scanner/tools/bin and keeps their cache under ~/.cargo-scanner/cache.

cargo-scanner init
cargo-scanner doctor --fix
cargo-scanner doctor

init writes .cargo-scanner.yaml. doctor --fix installs missing managed tools and pulls the default Docker runtime image when Docker is available. In a terminal, long-running repair steps show a live progress panel with the current action, elapsed time, completed steps, and Docker pull logs.

Everyday Scans

Start with the conversational scan:

cargo-scanner scan

The first wizard step scans the current folder by default. Choose Choose file or folder when you want to type a different path; press tab to complete a suggested file or folder. After choosing the result type, the wizard asks different follow-up questions for vulnerability scans and SBOM generation.

Scan one artifact:

cargo-scanner ./artifact.jar
cargo-scanner scan ./artifact.jar

Scan a directory recursively:

cargo-scanner ./artifacts -R

Fail when high or critical findings exist:

cargo-scanner ./artifact.tgz --fail-on high

Use a specific scanner:

cargo-scanner ./artifact.jar -s trivy
cargo-scanner ./artifact.jar -s grype

Write a JSON report:

cargo-scanner ./artifact.jar -j -o report.json

Write SARIF for GitHub code scanning:

cargo-scanner ./artifact.jar --format sarif --output results.sarif

In a terminal, scans show the current file and progress. Use --tui=false to disable the live progress UI.

Text results render as an interactive terminal viewer with summary metrics and a selectable findings table. Use up and down to select a finding, enter to show finding details, esc to close details, and o to open the finding URL when one is available.

SBOM

Generate a CycloneDX SBOM with Syft:

cargo-scanner sbom ./artifact.jar
cargo-scanner sbom ./artifact.jar --sbom-output sbom.cdx.json

Terminal output opens an SBOM viewer with a summary and selectable component table. Use up and down to select a component, enter to show component details, and esc to close details.

Write a normalized JSON report around the SBOM operation:

cargo-scanner sbom ./artifact.jar --json --output sbom-report.json

Runtime Choices

• managed: best default for personal machines. Cargo Scanner downloads and manages scanner binaries for you.
• docker: best for CI and isolated runs.
• native: use scanner CLIs already installed on PATH.
• auto: prefer a locally available Docker image, then managed tools, then native tools.

Examples:

cargo-scanner ./artifact.jar --runtime managed
cargo-scanner ./artifact.jar --runtime native
cargo-scanner ./artifact.jar --runtime docker --docker-image ghcr.io/opencomputinggarage/cargo-scanner-runtime:latest

Managed Tools

Most users only need:

cargo-scanner doctor --fix
cargo-scanner tools list

Advanced tool management:

cargo-scanner tools install all
cargo-scanner tools install grype@0.115.0
cargo-scanner tools update all
cargo-scanner tools update-db trivy
cargo-scanner tools uninstall trivy

Each managed install downloads the upstream release archive and checksum file, verifies SHA256, installs the binary, and writes a provenance manifest next to the binary. In a terminal, install and update commands show the current release, download, checksum, extraction, and install step.

Set a different managed home:

export CARGO_SCANNER_HOME="$HOME/.cache/cargo-scanner"

Updating Cargo Scanner

Most users only need:

cargo-scanner update --check
cargo-scanner update

Advanced:

cargo-scanner update --version v0.1.11

The updater downloads the release archive and checksums.txt from GitHub Releases, verifies SHA256, extracts the binary, and replaces the current executable. If the installed binary is owned by root, rerun with sudo or use the install script.

Use --force to reinstall the selected version and --repo owner/repo when testing a fork.

Docker And CI

Pull the bundled runtime image:

cargo-scanner runtime pull --docker-image ghcr.io/opencomputinggarage/cargo-scanner-runtime:latest

Runtime pulls show Docker output inside a live log panel when stderr is a TTY.

Use Cargo Scanner with Docker runtime:

cargo-scanner ./artifact.jar --runtime docker --docker-image ghcr.io/opencomputinggarage/cargo-scanner-runtime:latest

Run scanner CLIs directly in CI:

docker run --rm \
  -v "$PWD:/work:ro" \
  ghcr.io/opencomputinggarage/cargo-scanner-runtime:latest \
  grype dir:/work -o json

GitHub Actions example:

name: Cargo Scanner

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://raw.githubusercontent.com/opencomputinggarage/cargo-scanner/main/scripts/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: cargo-scanner doctor --fix
      - run: cargo-scanner . --recursive --fail-on high

Shell Completion

cargo-scanner completion zsh > /usr/local/share/zsh/site-functions/_cargo-scanner
cargo-scanner completion bash > ~/.cargo-scanner-completion.bash
cargo-scanner completion fish > ~/.config/fish/completions/cargo-scanner.fish
cargo-scanner completion powershell > cargo-scanner.ps1

Development

This repository uses mise to pin local tool versions. Go, Node.js, and pnpm are defined in .mise.toml.

mise install
mise run verify

Useful tasks:

mise run test
mise run build
mise run site-install
mise run site-build
mise run site-dev

The GitHub Pages site lives under site/ and uses React, Vite, and pnpm:

cd site
pnpm install
pnpm dev
pnpm build

When changing user-facing commands, options, TUI flows, installer behavior, or update behavior, update the docs in the same change. See docs/documentation.md.

Troubleshooting

Check the environment:

cargo-scanner doctor

Install missing managed tools:

cargo-scanner doctor --fix

If Docker is not available, use managed tools:

cargo-scanner ./artifact.jar --runtime managed

If Docker credential helpers hang while pulling from GHCR, try a clean Docker config:

DOCKER_CONFIG="$(mktemp -d)" docker pull ghcr.io/opencomputinggarage/cargo-scanner-runtime:latest

If Trivy is slow on the first run, prefetch its database:

cargo-scanner tools update-db trivy

Disable styled output:

NO_COLOR=1 cargo-scanner ./artifact.jar
CARGO_SCANNER_PLAIN=1 cargo-scanner doctor

Useful Commands

cargo-scanner version
cargo-scanner tui
cargo-scanner init --force
cargo-scanner doctor --fix
cargo-scanner cache path
cargo-scanner cache clean
cargo-scanner tools path
cargo-scanner tools list
cargo-scanner update --check
cargo-scanner update

Open Source Shoutouts

Cargo Scanner exists because excellent open source projects already do the hard security work. Special thanks to:

• Grype and Syft from Anchore for vulnerability scanning and SBOM generation.
• Trivy from Aqua Security for vulnerability scanning, SBOMs, and security databases.
• Charm for the terminal UX libraries behind the interactive flows: Bubble Tea, Bubbles, Lip Gloss, Huh, and Glamour.
• GoReleaser for dependable multi-platform release automation.
• The Go, React, Vite, and pnpm communities for the runtime and documentation tooling used around the project.

Thank you to the maintainers and contributors who make these tools available.

License

Cargo Scanner is licensed under the Apache License, Version 2.0. See LICENSE.