Command Line Interface#

This section describes the various commands available.

All commands below are run from the Vulnerability-Lookup project directory using poetry run.

Core#

Start all the services#

$ poetry run start

Stop all the services#

$ poetry run stop

Start/stop the backend (Valkey and Kvrocks)#

$ poetry run run_backend --start
$ poetry run run_backend --stop

Start/stop all enabled feeders#

$ poetry run feeders_manager --start
$ poetry run feeders_manager --stop

Start only the website#

$ poetry run start_website

Restart only the website#

$ poetry run restart_website

Dump a source in a JSON file#

$ poetry run dump --feed nvd

Bootstrap from Vulnerability-Lookup dumps#

Download the NDJSON files published by a trusted Vulnerability-Lookup instance (for example, the CIRCL dump directory), then import the directory into a fresh instance while Kvrocks is running:

$ poetry run import_dump /path/to/dumps
$ poetry run index_vulnerabilities

The filename (without .ndjson) becomes the source name. Existing vulnerability documents are never overwritten by default — a skipped document only gains metadata and source-index membership it does not have yet, so the command is safe to resume and re-running it never re-triggers notifications. Pass --replace to replace existing documents. Collaborative SQL exports (comments, bundles, sightings, and KEV entries) are ignored, documents whose shape is not recognized are counted and reported without aborting the file, and a failing file does not block the remaining dumps.

Dumps produced by the current dump command annotate each line with the physical storage key and index score (vulnerability-lookup:id and vulnerability-lookup:score), which the importer uses to rebuild storage faithfully. Older dumps without these annotations still import, with the identifier derived from the document content and the file’s modification time used as the index score — freshness-based features (recent listings, since= queries) will then treat those documents as modified at import time.

After bootstrapping, enable and run the normal feeders to receive regular updates. Dumps are intended for one-time initial bootstrap, not periodic synchronization: do not schedule recurring dump downloads and imports (a daily cron, for instance). Without --replace an import never updates a document that already exists, so a polled corpus silently goes stale — and repeatedly fetching full dumps shifts significant bandwidth costs onto the publisher, who may rate-limit or block clients seen doing it. The feeders and the API’s since= parameter exist precisely so nobody has to re-download the whole dataset.

Run an individual feeder manually#

$ poetry run nvd_importer
$ poetry run cvelist_importer
$ poetry run github_importer

See pyproject.toml under [project.scripts] for the full list of available feeder commands.

Update the documentation#

$ cd docs; poetry run make html

Web service#

This section describes the main commands related to the web service. All Flask commands are prefixed with poetry run flask --app website.app.

Database#

Init the database:

$ poetry run flask --app website.app db_init

Backup the PostgreSQL database (also runs automatically during poetry run update):

$ poetry run flask --app website.app db_backup

Generate a database models diagram:

$ poetry run flask --app website.app db_diagram

User management#

Create a user:

$ poetry run flask --app website.app create_user --login <login> --email <email> --password <password>

Create an admin:

$ poetry run flask --app website.app create_admin --login <login> --email <email> --password <password>

List all users:

$ poetry run flask --app website.app user_list

Delete a user:

$ poetry run flask --app website.app user_delete --login <login>

Retrieve a user’s API key:

$ poetry run flask --app website.app user_get_api_key --login <login>

Data management#

Update MISP warning lists (the administrator will be prompted to run this during updates):

$ poetry run flask --app website.app update_warninglists

Update the local copy of the GCVE registry (can be scheduled via cron):

$ poetry run flask --app website.app update_gcve_registry

Import OSI-approved licenses:

$ poetry run flask --app website.app import_osi_approved_licenses

Import source code languages:

$ poetry run flask --app website.app import_languages

Clean sightings by source or pattern:

$ poetry run flask --app website.app clean_sightings

Backfill sightings from existing data:

$ poetry run flask --app website.app backfill_sightings

Creates sightings retroactively from all existing comments (seen), bundles (seen, one per vulnerability), and KEV entries (exploited). Each sighting inherits the creation_timestamp of its source object. The command is idempotent: running it multiple times will not create duplicates, as it skips any entry whose source URL already exists in the database.

Background services#

Launch the email notification service:

$ poetry run flask --app website.app notify_users

Launch the synchronization service (see Synchronization service for details):

$ poetry run flask --app website.app sync

Command Line Interface

Contents