Skip to content

Contributing

magikh0e edited this page Nov 17, 2026 · 1 revision

Contributing

Issues and pull requests are welcome. cvescope stays standard-library only, read-only, and never scans: contributions need to keep all three.

Aliases (the most useful fix)

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 -sV product 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 new collector

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 handles token_file / token_env). Never log them.
  • HTTPS to appliances through net.PinnedClient so certificate pinning applies.
  • Distro packages: set backports=True, and distro, source and package_version when you know them, so the Debian/Ubuntu trackers can decide.

Version formats

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.

Running the tests

python -m unittest discover -s tests

CI runs them on Linux, Windows and macOS with Python 3.11 to 3.13.

Before you open a PR

  • Don't include real hostnames, IPs, inventories or scan output in code, tests or screenshots. examples/demo.toml is the made-up network to use.
  • One change per PR, with a test.

Clone this wiki locally