Offline & Air-Gapped Scanning

Why Offline Scanning?

Some environments cannot make outbound network requests — air-gapped networks, restricted CI runners, or simply slow connections. Vibgrate supports fully offline operation.

How It Works

Normally, Vibgrate queries npm/NuGet registries to determine the latest versions of your dependencies. In offline mode, it uses a pre-downloaded manifest file instead.

Setup

Step 1: Download the manifest

On a machine with internet access:

curl -L -o latest-packages.zip https://github.com/vibgrate/manifests/latest-packages.zip

Step 2: Transfer to air-gapped environment

Copy latest-packages.zip to your target machine via USB, secure file transfer, or include it in your container image.

Step 3: Run offline scan

vg scan --offline --package-manifest ./latest-packages.zip

Flags

Combining with Other Options

# Offline scan with SARIF output and quality gate
vg scan \
  --offline \
  --package-manifest ./latest-packages.zip \
  --format sarif \
  --out vibgrate.sarif \
  --fail-on error

Container-Based Workflow

Include the manifest in your Docker build:

FROM node:22-slim
COPY latest-packages.zip /opt/vibgrate/
RUN npx @vibgrate/cli scan /app \
  --offline \
  --package-manifest /opt/vibgrate/latest-packages.zip

Keeping Manifests Fresh

Schedule a recurring download of the manifest bundle (e.g. weekly cron job) on a machine with internet access, then distribute it to your air-gapped environments.

Manifest shape

The file is JSON, or a ZIP whose root contains package-versions.json, manifest.json, or index.json. A ZIP is unpacked with the unzip command. The JSON is one object. Ecosystem keys are npm, nuget, pypi, maven, rubygems, swift, go, cargo, composer, pub, hex, docker, helm, and terraform. runtimes is an optional catalog of runtime versions. Each ecosystem value is an object keyed by package name. NuGet names are matched case-insensitively.

An entry may include latest (newest version used for drift), versions (versions a declared range may resolve against), and vulns (advisories --vulns reads offline). A vulns entry needs an id. ranges match from introduced up to, and not including, fixed. severity is low, moderate, high, critical, or unknown.

vg scan has no separate advisory-file flag. Offline advisories are the vulns arrays in this manifest.

{
  "npm": {
    "left-pad": {
      "latest": "1.3.0",
      "versions": ["1.3.0"],
      "vulns": [
        {
          "id": "GHSA-example",
          "severity": "high",
          "ranges": [{ "introduced": "0", "fixed": "1.3.1" }]
        }
      ]
    }
  }
}

Offline vulnerabilities

vg scan --vulns --offline --package-manifest ./package-versions.json

Missing or invalid manifest

A missing, unreadable, or invalid --package-manifest stops the command before the scan. The exit code is 1. Stdout is empty, and no scan artifact is written.

A missing file prints:

error: Package manifest not found: /abs/path/missing.json. Pass a readable JSON or ZIP package-version manifest to --package-manifest.

A file that is not a package-version manifest prints:

error: Package manifest is not usable: /abs/path/bad.json. Expected a JSON object of package versions, or a ZIP containing package-versions.json, manifest.json, or index.json.

What offline mode does not do

--offline does not contact package registries. It does not query the OSV database. It does not upload results, including when --push is set or VIBGRATE_DSN is present. It does not call an EPSS or KEV service. A package the manifest does not list is not requested from a registry.

Determinism

The same tree and the same manifest produce the same findings order and the same advisory ids. Vulnerability findings are ordered by ecosystem, then package name, then installed version, then by severity and advisory id.

Limitations

• Offline drift scores are as current as the manifest file. An older manifest can undercount drift.
• Uploading to Vibgrate Cloud (vg push, --push) does not run while --offline is set.