Repository navigation
Contributing
Issues and pull requests are welcome. cvescope stays standard-library only, read-only, and never scans: contributions need to keep all three.
Most missed or wrong matches come from a product being spelled differently in CVE records than
in what a collector reports. The tables live in
cvescope/collectors/packages.py:
-
PACKAGES: distro and FreeBSD package names → display name and aliases -
APPS: app names (Home Assistant add-ons, containers) -
NMAP: nmap-sVproduct names -
SOURCE_OF: binary → source package, for dpkg lists without${source:Package}
Collector-specific maps sit next to their collectors: IMAGES in containers.py, PROGRAMS in
software.py, WHATWEB in webscan.py.
To find the right spelling, look at the CVE's affected entries with cvescope show CVE-..., or
query the database:
SELECT vendor, product, count(*) FROM cve_product WHERE product LIKE '%gitea%' GROUP BY 1, 2;A collector is a function that takes its config block and returns items:
from . import item
def mything(e: dict) -> list[dict]:
version = ... # read it: an API, a command, a file
return [item("MyThing (host)", "vendor", "product", version, aliases=["vendor:product"])]Register it in _registry() in cvescope/collectors/__init__.py, document it in the README and
config.example.toml, and add a test. Rules:
- Read-only calls only. No writes, no config changes, no probing.
- Secrets through
secret(e, "token")(which handlestoken_file/token_env). Never log them. - HTTPS to appliances through
net.PinnedClientso certificate pinning applies. - Distro packages: set
backports=True, anddistro,sourceandpackage_versionwhen you know them, so the Debian/Ubuntu trackers can decide.
Odd version strings in CVE records go in cvescope/versions.py (eval_entry, _text_ranges,
desc_max), each with a case in tests/test_versions.py.
python -m unittest discover -s testsCI runs them on Linux, Windows and macOS with Python 3.11 to 3.13.
- Don't include real hostnames, IPs, inventories or scan output in code, tests or screenshots.
examples/demo.tomlis the made-up network to use. - One change per PR, with a test.