In English. Читати українською.

pycve-agent

Local CVE agent for the PyCVE project. Runs on Ubuntu, Debian, or AlmaLinux, detects its own distribution, release and kernel, downloads the matching ruleset from static HTTP hosting, and checks installed packages and the running kernel against known CVEs locally. Debian-family hosts use dpkg; RHEL-family hosts use a shared RPM backend. On Ubuntu/Debian, rules target source packages (glibc, openssl), so the agent maps them to installed binary packages (libc6, libssl3) and compares the source version. Kernel checks target the running kernel: on Ubuntu its exact track and build version (/proc/version_signature), on Debian the build version from uname -v, so an upgrade without a reboot is still reported.

The agent never builds anything and never reports back — it only consumes the JSON artifacts produced by pycve-server.

Quick start

Requires only Python 3.8+ (3.11+ recommended), HTTP access to a rules directory and, on Ubuntu/Debian, dpkg ≥ 1.16.2 — no venv, no install:

./run-local-agent.sh --rules-base-url https://host/rules

VULNERABLE: CVE-2026-31431 on ubuntu focal: kernel 5.4.0-92 [priority: critical, known exploited]

Exit codes: 0 = OK, 1 = ERROR, 2 = VULNERABLE (low/medium/unknown priority), 3 = VULNERABLE_HIGH, 4 = VULNERABLE_CRITICAL (critical priority, including KEV and manual overrides).

For regular use you can install the package (entrypoint local-agent):

python3 -m venv .venv && . .venv/bin/activate && pip install -e .

Third-party repositories are not covered

OK does not mean that packages from third-party repositories are safe.

Rules describe only the distribution's own packages. The agent does not check packages from third-party repositories (Sury, Percona and others) and gives no warning about them:

• if a package has no rules, the agent reports nothing about it;
• if a package shares its name with a distribution package, its version is compared with the distribution's threshold, so that result cannot be trusted.

See Data Sources for details.

Common modes

local-agent --rules-base-url https://host/rules --fixed-only      # drop advisory matches — typical for alerting
local-agent --rules-base-url https://host/rules --kernel-only     # kernel matches only
local-agent --rules-base-url https://host/rules --packages-only   # package matches only
local-agent --rules-base-url https://host/rules --show-all-cves   # show every match (default: first 5)

Running under cron (logs go to stderr, the result goes to stdout):

*/15 * * * * /opt/pycve-agent/run-local-agent.sh --rules-base-url https://host/rules >> /var/log/pycve-agent.log 2>&1

Binaries

The agent can also be deployed as a self-contained executable — no Python needed on the host. The CLI is identical to local-agent, plus --version reporting the build version:

./pycve-agent-linux-x86_64 --rules-base-url https://host/rules

Two variants are available: standard (glibc ≥ 2.34 — Ubuntu 22.04+, Debian 12+) and legacy (glibc ≥ 2.14 — older systems, including focal and bullseye). On Ubuntu/Debian both variants also need dpkg ≥ 1.16.2: package matching relies on the dpkg-query fields ${source:Package}, ${source:Version} and ${db:Status-Abbrev} (dpkg-query(1)). The Nuitka/Docker build process is documented in packaging/nuitka/README.md.

Documentation

Full documentation lives in this repository's wiki:

• Getting Started — an end-to-end walkthrough: build rules → serve them → get a first agent verdict.
• Agent Reference — the full CLI reference: every flag, every output format, caching, sorting, dry-run checks.
• Operations — production scenarios: cron, cache fallback, known limitations.
• Architecture, Rule Format, Priority — how the system and its artifacts are put together.

Tests

python3 -m unittest discover -s tests -p 'test_*.py'
# or: uv run python3 -m unittest discover -s tests -p 'test_*.py'