Introduction

OPPSY is an open-source vulnerability management platform. It watches your project’s dependency lock files, continuously checks them against the OSV database, and notifies you whenever a vulnerability is found or updated. The goal is simple: keep your team informed about security issues in the libraries you depend on, without requiring manual effort.

Core concepts

There are three things you work with in OPPSY:

Workspace — a logical container for a project. Each workspace holds the dependency manifests you want to monitor and the notification channels that should receive alerts for that project.

Manifest — a dependency lock file uploaded into a workspace. OPPSY parses it, identifies every package it declares, and matches those packages against the OSV vulnerability database. You can upload as many manifests as you like into a single workspace — useful when a project spans multiple language ecosystems.

Notification channel — a configured destination that receives vulnerability alerts. A channel can be a webhook endpoint, a Discord channel, or an email address. Channels are created independently and then linked to one or more workspaces.

How it works

1. Create a workspace for your project.
2. Upload one or more dependency lock files into that workspace.
3. Create a notification channel and link it to the workspace.
4. OPPSY scans the manifests, matches packages against OSV, and delivers alerts to your channel.
5. In the background, OPPSY keeps the OSV database in sync. When a new vulnerability is published or an existing one is updated, any affected workspaces are notified automatically.

Manifest upload

A manifest is a dependency lock file attached to a workspace. Once uploaded, OPPSY parses it, identifies every package it declares, and runs a vulnerability scan against the OSV database.

Install oppsy-cli

From prebuilt binaries (recommended)

Pre-built binaries for Linux, macOS, and Windows are available on the GitHub Releases page.

The quickest way to install is with the generated installer script:

curl -fsSL https://github.com/oppsy-dev/oppsy-dev/releases/latest/download/install.sh | sh

This installs oppsy-cli to ~/.local/bin by default. To choose a different directory:

curl -fsSL https://github.com/oppsy-dev/oppsy-dev/releases/latest/download/install.sh | sh -s -- -b /usr/local/bin

From source (requires Go 1.24+)

go install github.com/oppsy-dev/oppsy-dev/oppsy-cli@latest

Publish a manifest

oppsy-cli publish \
  --host-url     http://localhost:3030/api \
  --workspace-id <workspace-id> \
  --lockfile     ./Cargo.lock \
  --name         my-service \
  --tag          v0.1.0

Build and run OPPSY

Run Docker

docker run --name oppsy -p 3030:3030 -v oppsy-data:/data ghcr.io/oppsy-dev/oppsy:latest

Mount a volume at /data so the SQLite database persists across restarts. The service will be available at http://localhost:3030.

Build from source

Dagger runs the build pipelines inside containers — no local Rust or Node toolchain required beyond having the Dagger CLI installed.

First-time setup (generates SDK bindings and project files):

dagger develop

Builds the full image (Rust binary + frontend assets + Atlas migrations) and loads it directly into Docker:

dagger call oppsy-build --src=. export-image --name oppsy:latest

Then run it:

docker run -p 3030:3030 -v oppsy-data:/data oppsy:latest

Service configuration

All configuration is read from environment variables at startup. There are no config files — every option has a sensible default, so the service runs without any environment variables set.

Naming convention

Every variable is prefixed with OPPSY_SERVICE_. The rest of the name is the field name in uppercase. For example, the bind_address field is configured via OPPSY_SERVICE_BIND_ADDRESS.

Reference

OPPSY_SERVICE_BIND_ADDRESS

Type: socket address (<ip>:<port>)
Default: 0.0.0.0:3030

The network address the HTTP server binds to. Accepts any valid socket address.

OPPSY_SERVICE_BIND_ADDRESS=127.0.0.1:8080

OPPSY_SERVICE_LOG_FORMAT

Type: enum
Default: human_readable
Values: human_readable, json

Controls how log output is formatted. Use json when shipping logs to a structured log aggregator (Datadog, Loki, etc.).

OPPSY_SERVICE_LOG_FORMAT=json

OPPSY_SERVICE_LOG_LEVEL

Type: enum
Default: INFO
Values: TRACE, DEBUG, INFO, WARN, ERROR

Minimum severity level for emitted log lines. Values are case-sensitive and must be uppercase.

OPPSY_SERVICE_LOG_LEVEL=DEBUG

OPPSY_SERVICE_API_URL_PREFIX

Type: string
Default: /api

The path prefix under which all REST API routes are mounted. Change this if you need to namespace the API behind a reverse proxy path.

OPPSY_SERVICE_API_URL_PREFIX=/v1

OPPSY_SERVICE_CORE_DB_URL

Type: SQLite URL
Default: sqlite://oppsy.db

Connection URL for the SQLite database that stores workspaces, manifests, and notification channel records. The path in the URL is resolved relative to the working directory.

OPPSY_SERVICE_CORE_DB_URL=sqlite:///data/oppsy.db

When running in Docker, mount a volume at /data and point this (and the path settings below) at it so data persists across container restarts.

OPPSY_SERVICE_MANIFEST_DB_PATH

Type: filesystem path
Default: ./manifest_db

Directory where the raw content of uploaded manifest files (lock files) is stored. The directory is created if it does not exist.

OPPSY_SERVICE_MANIFEST_DB_PATH=/data/manifest_db

OPPSY_SERVICE_OSV_DB_PATH

Type: filesystem path
Default: ./osv_db

Directory where downloaded OSV vulnerability archives are cached on disk. At startup and on each sync cycle, OPPSY fetches updated archives from the OSV GCS bucket into this directory.

OPPSY_SERVICE_OSV_DB_PATH=/data/osv_db

OPPSY_SERVICE_OSV_SYNC_INTERVAL

Type: integer (minutes)
Default: 15

How often the background task re-downloads OSV vulnerability data and re-evaluates all tracked manifests. The OSV team publishes updates with at most 15 minutes of latency, so values below 15 provide no benefit.

OPPSY_SERVICE_OSV_SYNC_INTERVAL=30

OPPSY_SERVICE_OSV_ECOSYSTEMS

Type: comma-separated list of ecosystem names
Default: (empty — all ecosystems)

Restricts which OSV ecosystem archives are downloaded and indexed. When left empty (the default), OPPSY downloads data for every ecosystem published in the OSV GCS bucket. Setting an explicit list reduces disk usage and sync time at the cost of narrower vulnerability coverage.

Values must exactly match the canonical OSV ecosystem names (case-sensitive):

OPPSY_SERVICE_OSV_ECOSYSTEMS=crates.io,npm,Go,PyPI,Maven

OPPSY_SERVICE_FRONTEND_PATH

Type: filesystem path
Default: ./frontend

Directory containing the pre-built React SPA assets (index.html, JS bundles, etc.). The backend serves these files at / and falls back to index.html for any path not matched by an API route, enabling client-side routing.

In the official Docker image this is baked in at build time and does not need to be changed.

OPPSY_SERVICE_FRONTEND_PATH=/app/frontend

OPPSY_SERVICE_SMTP_URL

Type: URL (smtp://...)
Default: (unset — email notifications disabled)

SMTP connection URL used to send email vulnerability notifications. When this variable is not set, the email notification backend is not initialised and email channels cannot be used.

Format: smtp://username:password@host:port

OPPSY_SERVICE_SMTP_URL=smtp://alerts:secret@mail.example.com:587

API Reference