tutorial

Monitoring OSV-Scanner with Vigilmon

OSV-Scanner checks your dependencies against Google's OSV vulnerability database — here's how to monitor its API server, OSV database connectivity, scan pipeline health, database freshness, and CI/CD integration with Vigilmon.

OSV-Scanner is an open source vulnerability scanner from Google that checks project dependencies against the Open Source Vulnerabilities (OSV) database — a comprehensive, community-curated database covering npm, PyPI, Go, Maven, Cargo, RubyGems, NuGet, and more. It reads lockfiles (package-lock.json, requirements.txt, go.sum, Cargo.lock) and SBOMs to identify known vulnerabilities with CVSS scores, fix versions, and exploit availability. In server mode, OSV-Scanner runs as a REST API (Go binary on port 3000) that CI/CD pipelines query to get vulnerability reports without running the scanner binary in each pipeline. If the server or its OSV database feed goes stale, your dependency scanning coverage silently degrades while your team believes it is protected. Vigilmon keeps the entire OSV-Scanner infrastructure under continuous observation.

What You'll Set Up

  • HTTP uptime monitor for the OSV-Scanner API server (port 3000)
  • OSV database connectivity monitor (OSV.dev API)
  • Cron heartbeat for scan pipeline execution health
  • Database freshness check via heartbeat
  • SSL certificate expiry alerts for the API server
  • Alert channels with appropriate thresholds

Prerequisites

  • OSV-Scanner deployed in server mode on port 3000 (or CLI mode with a scheduled scan wrapper)
  • Access to osv.dev API or a local mirror of the OSV database
  • A free Vigilmon account

Step 1: Monitor the OSV-Scanner API Server (Port 3000)

When OSV-Scanner runs in server mode, it exposes a REST API that CI/CD pipelines use to submit scan requests and retrieve vulnerability reports. If the server goes down, pipelines fall back to running the scanner binary locally (if configured) or fail silently — developers may merge vulnerable dependencies without any warning.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: https://osv-scanner.yourdomain.com/health (or http://your-server-ip:3000/health).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Monitor SSL certificate and set Alert when certificate expires in less than 21 days.
  7. Click Save.

If OSV-Scanner server mode does not expose a /health endpoint, monitor the API root:

  1. URL: http://your-server-ip:3000/
  2. Expected HTTP status: 200 or 404 — any response confirms the server is alive.

Step 2: Monitor OSV Database Connectivity

OSV-Scanner queries the OSV.dev API for up-to-date vulnerability data. If the OSV API is unreachable — due to network issues, DNS failures, or upstream outages — scans may return incomplete results or fail entirely. CI/CD pipelines that rely on complete vulnerability data may silently pass unsafe dependencies.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://api.osv.dev/v1/query
  3. Method: POST
  4. Expected HTTP status: 200 or 400 — a 400 on an empty POST body confirms the API is processing requests; a 502/503/timeout means connectivity is broken.
  5. Check interval: 5 minutes
  6. Click Save.

Alternatively, monitor TCP connectivity to the OSV API:

  1. Click Add Monitor → TCP Port.
  2. Host: api.osv.dev
  3. Port: 443
  4. Check interval: 5 minutes
  5. Click Save.

Step 3: Heartbeat Monitor for Scan Pipeline Health

A running API server does not guarantee that scans are executing successfully. A heartbeat monitor confirms the full pipeline — scan request submission, dependency resolution, OSV database lookup, and result return — is working end-to-end.

  1. Click Add Monitor → Cron Heartbeat.
  2. Set the expected interval to 30 minutes.
  3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).
  4. Create a canary scan script that runs OSV-Scanner against a known lockfile and pings the heartbeat on success:
#!/bin/bash
# /opt/osv-scanner/canary-scan.sh

# Create a minimal canary lockfile with a known-safe package
cat > /tmp/canary-package-lock.json << 'EOF'
{
  "name": "canary",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {}
}
EOF

# Run OSV-Scanner against the canary lockfile
osv-scanner --lockfile /tmp/canary-package-lock.json \
  --json > /tmp/canary-result.json 2>&1

EXIT_CODE=$?

# Exit code 0 = no vulnerabilities found (expected for empty lockfile)
if [ "$EXIT_CODE" -eq "0" ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

rm -f /tmp/canary-package-lock.json /tmp/canary-result.json

Schedule it:

*/30 * * * * /opt/osv-scanner/canary-scan.sh

If no heartbeat arrives, it means scan execution is broken — not just that the API server is down.

Step 4: Heartbeat Monitor for OSV Database Freshness

OSV-Scanner can use a local offline copy of the OSV database for faster scans without per-query API latency. This local database must be updated regularly (typically daily) to stay current with newly disclosed vulnerabilities. A stale database means new CVEs are invisible to your scanning pipeline.

  1. Click Add Monitor → Cron Heartbeat.
  2. Set the expected interval to 25 hours — the database update should run daily; alert if it has not run in more than 25 hours.
  3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/def456).
  4. Add the heartbeat ping to your database update script:
#!/bin/bash
# /opt/osv-scanner/update-db.sh

# Download the latest OSV database
osv-scanner --download-db /var/lib/osv-scanner/db

if [ "$?" -eq "0" ]; then
  # Signal successful database refresh to Vigilmon
  curl -s https://vigilmon.online/heartbeat/def456
  echo "$(date): OSV database updated successfully" >> /var/log/osv-scanner/update.log
else
  echo "$(date): OSV database update FAILED" >> /var/log/osv-scanner/update.log
fi

Schedule via cron:

0 2 * * * /opt/osv-scanner/update-db.sh

If the database update job fails silently (disk full, network error, upstream outage), Vigilmon alerts after 25 hours — before a new critical CVE goes undetected for multiple days.

Step 5: Monitor CI/CD Integration Health

OSV-Scanner's value comes primarily from catching vulnerabilities before they merge. If the CI/CD integration breaks — the scan step exits with the wrong code, GitHub Actions drops the workflow, or the scanner binary is missing — developers merge vulnerable dependencies with no warning.

Add a monitor on the CI/CD pipeline status endpoint if your platform supports it:

For a self-hosted GitLab instance:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://gitlab.yourdomain.com/-/health
  3. Expected HTTP status: 200
  4. Check interval: 2 minutes
  5. Click Save.

For GitHub-hosted CI (Actions), monitor your repository's pipeline health indirectly via the OSV-Scanner canary heartbeat in Step 3 — if the heartbeat stops, investigate whether the CI trigger is broken.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
  2. For the OSV-Scanner API server monitor, set Consecutive failures before alert to 2 — brief restarts during upgrades cause single-probe failures.
  3. For the OSV database API monitor, set Consecutive failures to 3 — the external API may have transient blips that self-resolve within minutes.
  4. For scan pipeline and database freshness heartbeats, Vigilmon alerts automatically when no ping arrives within the expected window.
  5. For the SSL certificate monitor, set alerts to 21 days before expiry.

Lockfile Parser Health Check

OSV-Scanner supports many lockfile formats across polyglot monorepos. Parser failures for one ecosystem silently reduce coverage without an obvious error. Add ecosystem-specific canary lockfiles to your canary scan script (Step 3) to confirm each parser is working:

#!/bin/bash
# Test multiple lockfile formats

FAILED=0

for LOCKFILE in \
  /opt/osv-scanner/canary/package-lock.json \
  /opt/osv-scanner/canary/requirements.txt \
  /opt/osv-scanner/canary/go.sum \
  /opt/osv-scanner/canary/Cargo.lock
do
  osv-scanner --lockfile "$LOCKFILE" --json > /dev/null 2>&1
  if [ "$?" -ne "0" ] && [ "$?" -ne "1" ]; then
    # Exit code 2+ indicates a parse or runtime error (not just "vulnerabilities found")
    echo "Parser failed for: $LOCKFILE" >&2
    FAILED=1
  fi
done

if [ "$FAILED" -eq "0" ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

Summary

| Monitor | Target | What It Catches | |---|---|---| | API server | :3000/health | Server crash, scans not accepted | | OSV API connectivity | api.osv.dev:443 | Vulnerability data unreachable | | Scan pipeline heartbeat | Heartbeat URL | End-to-end scan execution broken | | Database freshness heartbeat | Heartbeat URL | Offline OSV database stale >24h | | CI/CD platform | GitLab health or GitHub API | Pipeline trigger broken | | SSL certificate | API server domain | TLS expiry on scanning endpoint |

OSV-Scanner protects your supply chain by matching your dependencies against known CVEs — but only if the scanner, its database, and the CI/CD integration are all healthy. With Vigilmon watching the API server, OSV database connectivity, scan execution pipeline, and database freshness, you get alerted before a stale database or broken pipeline lets vulnerable dependencies slip through undetected.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles