oss-risk-guard

Risk Guard

Open source risk analysis and scoring for software dependencies.

Website: risk-guard.github.io/oss-risk-guard

Risk Guard walks a local git repository, builds an SBOM (software bill of materials), runs a graph of scoring checks — rules that flag supply-chain risk such as missing licenses, install scripts, or abandoned upstreams — against the source and its direct dependencies, and emits a single SARIF report (the code-scanning format GitHub and GitLab render inline). Use it locally to spot risky dependencies before you adopt them, or in CI to gate pull requests.

Supported ecosystems: npm, pypi, rubygems.

Risk Guard runs entirely on your machine. It fetches only public package metadata, artifacts, and source repositories from the registries and forges it analyzes — it never uploads your code or dependency list to any Risk Guard server.

Install

Pick whichever fits your machine. Each gives you a risk-guard binary.

Install script (Linux / macOS)

Download the latest prebuilt binary in one command:

curl -fsSL https://risk-guard.github.io/oss-risk-guard/get.sh | sh

It detects your OS/arch, downloads the matching release archive, verifies its checksum, and installs to /usr/local/bin (or ~/.local/bin if that isn't writable). Customize with:

# Pin a version
curl -fsSL https://risk-guard.github.io/oss-risk-guard/get.sh | sh -s -- v0.0.2

# Install somewhere else
curl -fsSL https://risk-guard.github.io/oss-risk-guard/get.sh | RISK_GUARD_INSTALL_DIR="$HOME/bin" sh

On an architecture without a prebuilt binary, the script points you at the go install method below.

Prebuilt binary

Download an archive for your platform from the GitHub Releases page, unpack it, and put risk-guard on your PATH. Builds are published for Linux (amd64, arm64, armv7), macOS (amd64, arm64), and Windows (amd64, arm64), each with a checksums-*.txt for verification.

tar xzf risk-guard-<version>-linux-amd64.tar.gz
sudo mv risk-guard /usr/local/bin/
risk-guard --version

Go install

If you have Go 1.25.1+ installed, install straight from source — no clone needed:

go install github.com/Risk-Guard/oss-risk-guard/cmd/risk-guard@latest

This drops a risk-guard binary in $(go env GOPATH)/bin (usually ~/go/bin). Make sure that directory is on your PATH.

Build from source

git clone https://github.com/Risk-Guard/oss-risk-guard.git
cd oss-risk-guard
go build -o risk-guard ./cmd/risk-guard

Usage

Run the full pipeline against an on-disk git repository — score the local source, build an SBOM, audit each direct dependency, and write one merged SARIF report:

risk-guard .

The single argument is a path to an existing git repository. By default the report is written to ./risk-guard-report.sarif.

risk-guard /path/to/repo --sarif report.sarif      # choose the output file
risk-guard . --sbom-format cyclonedx --sbom-out sbom.cdx.json
risk-guard . --jobs 8                               # audit more packages in parallel
risk-guard . --continue-on-error=false              # fail instead of emitting partial SARIF

Run risk-guard --help (or risk-guard <command> --help) for the full flag list.

Example output

The SARIF report renders inline in GitHub/GitLab. Locally, risk-guard audit view risk-guard-report.sarif prints a summary like:

⚠️ 20 warning · 🔵 4 acknowledged · ⬜ 9 ignored

Subcommands

The root command runs the complete pipeline. These subcommands expose individual stages:

Common flags

These persistent flags apply to every command:

Use in CI

GitHub Actions

Use the Risk Guard Action. Findings appear in the Security tab and inline on pull requests.

jobs:
  risk-guard:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v6
      - uses: Risk-Guard/action@v1

GitLab CI/CD

Use the Risk Guard component. Findings show in the merge request widget (all tiers) and the Security tab (Ultimate).

include:
  - component: $CI_SERVER_FQDN/risk-guard/components/scan@1.0.3

Other CI, or running the CLI directly

Run the pipeline and let the exit code gate the build:

risk-guard . --github                              # GitHub Actions annotations + SARIF
risk-guard . --gitlab gl-code-quality-report.json  # GitLab Code Quality report + SARIF

• The exit code is non-zero when there are blocking findings and the effective workflow mode is active. Modes no-fail, silent, and disabled never fail the build.
• --mode overrides workflow.mode from .risk-guard.yml for a single run, e.g. --mode no-fail to observe findings without breaking the build.

Upload risk-guard-report.sarif to GitHub code scanning, or expose the GitLab Code Quality report as an artifact, to render findings inline:

risk-guard:
  script:
    - risk-guard . --gitlab gl-code-quality-report.json
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

Configuration

Risk Guard reads two optional files from the repository root:

• .risk-guard.yml — workflow config: scoring mode, the policy that decides which findings block vs. warn vs. ignore, acknowledged exceptions, and overrides.
• .riskguardignore — gitignore-style patterns excluding paths from scanning.

risk-guard init generates a starter .risk-guard.yml from a first scan. See docs/configuration.md for the annotated schema.

Development

Requires Go 1.25.1+. Run the CLI without building a binary:

go run ./cmd/risk-guard .                    # full pipeline against the current repo
go run ./cmd/risk-guard audit source .       # source-only scan
go run ./cmd/risk-guard --help

Tests and the build:

go test ./...
go build ./...

Linting uses golangci-lint with the config in .golangci.yml:

golangci-lint fmt    # apply gofumpt + goimports formatting
golangci-lint run    # lint

License

MIT — see LICENSE.