vulnerability

vulnerability

An API for collecting, storing, and utilizing CVE-based vulnerability information. This software provides fast access to CVE data. In addition to CVE, it also supports other vulnerability data such as KEV and EPSS. If you find NVD API performance unstable, please try this OSS as an alternative solution.

Architecture

This software consists of the following components:

• API: REST API server
• DB: Store vulnerability data
• DataSource: External data source (NVD, EPSS, KEV...)
• vulnctl: Command line tool for importing data

                                                            vulnctl
         HTTP    ┌────────────┐            ┌────────────┐  (command)  ┌──────────────┐
Client ————————▶ │    API     │ - - - - —▶ │     DB     │ ◀────────── │  DataSource  │
                 └────────────┘            └────────────┘             └──────────────┘

Quick Start

You can run the following commands.

Run containers

# Run API, DB
docker compose -f quickstart.yml up -d

Import data

# Import recently CVE, EPSS, KEV data
docker run --rm \
  --network risken-network \
  ghcr.io/ca-risken/vulnerability/cli:latest \
    vulnctl import

Test API

Now, you can test the API by the following command. For more details, please refer to API Document.

Get Vulnerability

# Get vulnerability by CVE ID
curl -i -X GET \
  http://localhost:8090/api/v1/vulnerability/CVE-2024-50450

List Vulnerability

# `wordpress` vulnerabilities with high or critical severity
curl -i -X GET \
  'http://localhost:8090/api/v1/vulnerability?cpe_target_sw=wordpress&base_severity=HIGH,CRITICAL&limit=3'

# vulnerabilities with description containing `Inject*` pattern matching
curl -i -X GET \
  'http://localhost:8090/api/v1/vulnerability?description=Inject*&sort=published_date&order=desc&limit=3'

List Product Vulnerability

# `openstack/swift` vulnerabilities with version `1.4.6`
curl -i -X GET \
  'http://localhost:8090/api/v1/vulnerability/product?cpe_vendor=openstack&cpe_product=swift&version=1.4.6'

Clean up

docker compose -f quickstart.yml down

Optional

Import CVE data by year

If you want to import CVE data by year, you can use the following command.

# Import CVE by year (optional)
make exec-import-year YEAR=2024
make exec-import-year YEAR=2023
make exec-import-year YEAR=2022
make exec-import-year YEAR=2021
make exec-import-year YEAR=2020

API Key

If you want to restrict access to the API, you can set the API key in the API_KEYS environment variable.

# Set your `API_KEYS`
# e.g.) API_KEYS=your-api-key1,your-api-key2
cp .env.example .env
vi .env

# Run API
make up

# Test API
curl -i -X GET \
  -H "X-API-Key: your-api-key1" \
  http://localhost:8090/api/v1/healthz

Metabase

If you want to use Metabase, you can use the following command.

# If you run with quickstart.yml, you should stop it before running Metabase.
docker compose -f quickstart.yml down

# Run with Metabase container
make up

# Open metabase console on your browser
make db-metabase

Add MySQL Database to Metabase

After starting Metabase, follow these steps to add the vulnerability database:

1. Access Metabase at http://localhost:3333
2. Complete the initial setup if this is your first time
3. Click on "Settings" (gear icon) in the top right
4. Go to "Admin settings" -> "Databases" -> "Add database"
5. Select "MySQL" as the database type
6. Enter the following connection details:
   • Display name: vulnerability (or any name you prefer)
   • Host: vulnerability-db
   • Port: 3306
   • Database name: vulnerability
   • Username: hoge
   • Password: moge
7. Click "Save" to add the database
8. Metabase will test the connection and sync the database schema

Now you can create dashboards and run queries against the vulnerability database.

Note: Use vulnerability-db as the hostname since both Metabase and MySQL are running in the same Docker network.

Trouble shooting

Import CVE data error

Sometimes, you may encounter an error when importing CVE data. For example, you may get the broken file error.

Recovery

The CVE data is updated every 2 hours, you need to check the CVE data is updated.

• Updated every 2 hours:
  • Recent CVE Data
  • Modified CVE Data
• Updated every day:
  • Yearly CVE Data

Metabase error

If you cannot open Metabase console, you can check the following points.

• Docker container is running?
• Metabase container is ready? (You can check it by docker compose logs)

Note: Metabase may take several minutes to initialize on first startup. If it's still not accessible after waiting 5-10 minutes, please check:

• Container logs for any errors: docker compose logs vulnerability-metabase
• Container status: docker ps
• Memory usage: docker stats