Argus

A few minutes

Quick start

Argus is built to run as a scheduled job in your CI pipeline, primarily GitLab CI. This page runs it once by hand so you can see what it does, then points you at the CI setup that is its real home.

Prerequisites

Argus is a single prebuilt binary. You do not need Go or any build toolchain to run it. It shells out to your package manager to resolve and validate patches, so wherever it runs (your CI job’s image, or your workstation for this walkthrough) it needs:

  • Maven on the PATH and a JDK, matching whatever your project already builds with. In CI, that means running Argus in the same image your build uses.
  • A GitLab token in GITLAB_PRIVATE_TOKEN, with permission to push branches and open merge requests. Only needed when publishing; argus scan works without one.

Network requirements

Check this before your first run. CI runners are often behind restrictive egress rules, and a blocked endpoint usually shows up as a long hang and then a timeout, not a clear error. Every run needs outbound HTTPS (port 443) from the runner to three places:

  • api.osv.dev: the advisory database Argus matches your dependencies against by default. An advisory OSV has not mapped yet can be declared in config.yml.
  • Maven Central (repo.maven.apache.org) or your internal mirror, reached by the Maven build Argus invokes. Your settings.xml mirrors and proxies are honoured.
  • Your GitLab host, where merge requests are opened and, with the gitlab advisory source, where findings are read.

Behind an egress proxy, set the standard HTTPS_PROXY / NO_PROXY variables. The full endpoint list, proxy behaviour, and air-gap guidance are on the Network access page; hand it to your platform team for allowlisting.

Download Argus

Grab the prebuilt binary for your platform. No compiling is involved. The one-liner below installs the Linux amd64 build; use the buttons for another architecture, or to fetch the diagnostic skill, the CI/CD component, or the Grafana dashboards. See Installation for the full walkthrough, or any release for its downloads.

Download binary
Linux · amd64Linux · arm64macOS · arm64
Diagnostic skillCI/CD componentGrafana dashboards

Then make it executable and put it on your PATH:

terminal
VERSION=4.2.1
curl -fsSL -o argus \
  "https://argus-assets.typecheck.io/v${VERSION}/argus-${VERSION}-linux-amd64"
chmod +x argus && sudo mv argus /usr/local/bin/argus

argus version

Run the pipeline

argus run is the one command you need, and it is the same command whether you type it in a terminal or a CI job executes it on a schedule. It resolves the dependency graph, queries OSV, plans a fix for each advisory, validates the candidate with Maven, and opens a GitLab merge request. It then reconciles any of its own merge requests that are now stale. Give it a token and the project to publish into:

terminal
export GITLAB_PRIVATE_TOKEN=glpat-your-token-here

argus run \
  --pom pom.xml \
  --gitlab-url https://gitlab.example.com \
  --project-id 4567

What just happened

Argus carried the project from “unknown” to “merge request raised” in a single pass: it resolved your dependency graph, matched every component against OSV, chose a fix on the strategy ladder, edited pom.xml with byte-level patches that touched nothing else, proved the result still builds, and opened a labelled merge request for review. The first run does a real Maven build to produce the SBOM, so expect it to take as long as your normal build. Advisory data is then cached under .argus-cache/ for 24 hours, and persisting that directory between CI runs keeps later runs fast.

Looking before you leap

If you would rather see what Argus finds before it publishes anything, the development command scan writes a report and changes nothing:

terminal
# Optional: generate a report only, publish nothing
argus scan --pom pom.xml --report report.json

Where to go next