cve-core

Core microservice for managing CVE (Common Vulnerabilities and Exposures) data within the bunch of CVE services, see cve-services. Mainly responsible for storing CVE records and CVSS scores.

Configuration

All settings are loaded from environment variables (or a .env file).

Variable	Default	Description
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
POSTGRES_USER	—	DB username (required)
POSTGRES_PASSWORD	—	DB password (required)
POSTGRES_DB	vulnerabilities	Database name
GRPC_HOST	[::]	gRPC bind address
GRPC_PORT	50051	gRPC port
GRPC_MAX_WORKERS	10	Thread pool size
LOG_LEVEL	INFO	Logging level
ENVIRONMENT	development	development / staging / production / test
DB_ECHO	false	Echo SQL queries to logs

---

Getting Started

0. Before start here

Follow the instructions in main project description.

1. Install uv (Python package manager)

# macOS / Linux
curl -Ls https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install dependencies

uv sync --all-extras

3. Run database migrations

Alembic is already configured in this repo (alembic/ folder with env.py and migrations). Just apply the existing migrations:

alembic upgrade head

4. Start the service

uv run python -m src.main 

The gRPC server will start on [::]:50051 by default.

---

Running Tests

Integration tests require a running PostgreSQL instance (see above).

# Direct DB test (no gRPC server needed)
uv run python -m tests.integration_tests.add_CVEs_test
uv run python -m tests.integration_tests.list_CVEs_test

# End-to-end gRPC test (requires running server)
uv run python -m tests.integration_tests.grpc_client_test

---

Database Schema

Four tables managed via Alembic migrations:

Table	Description
cves	Main CVE records (cve_id, status, title, description, dates)
cve_affected	Affected vendors and products linked to a CVE (vendor, product — TEXT)
cve_risks	CVSS risk scores linked to a CVE (cvss_version, value)
providers	Data source registry (name, url)
cve_providers	Many-to-many join table between cves and providers

---

gRPC API

Proto source: https://github.com/dillsh/cve-gRPC/tree/develop

RegisterCVE

Insert or update CVE entries in the database.

Request: AddEntriesRequest

Field	Type	Required	Description
cves	repeated CVE	Yes	List of CVE entries to register or update

Response: AddEntriesResponse — empty on success.

---

ListCVEs

Return CVEs whose date_updated falls within the specified range.

Request: ListCVEsRequest

Field	Type	Required	Description
start_time	Timestamp	Yes	Lower bound on date_updated
end_time	Timestamp	No	Upper bound on date_updated

Response: ListCVEsResponse

Field	Type	Description
cves	repeated CVE	Matching CVE entries

---

CVE message structure

Field	Type	Required	Description
cve_id	string	Yes	CVE identifier, e.g. CVE-2024-1234
status	string	Yes	CVE state, e.g. PUBLISHED, RESERVED
title	string	No	Short summary
description	string	No	Full description
date_reserved	Timestamp	Yes	Date the CVE ID was reserved
date_published	Timestamp	No	Publication date
date_updated	Timestamp	No	Last update date
affected	repeated Affected	No	Affected vendor/product pairs
risks	repeated Risk	No	CVSS scores
providers	repeated Provider	No	Data providers

Affected: vendor (string), product (string)

Risk: cvss_version (enum: V20 V30 V31 V40), value (float, 0.0–10.0)

Provider: name (string), url (string)

---

Tech Stack

Component	Technology
Language	Python 3.12
gRPC framework	grpcio >= 1.78.0
Database	PostgreSQL
ORM	SQLAlchemy 2.0 (async)
DB driver	asyncpg
Migrations	Alembic
Config	pydantic-settings
Serialization	protobuf ~6.33
Linting	ruff
Type checking	mypy
Testing	pytest, pytest-asyncio

---