Skip to content

Configuration

magikh0e edited this page Nov 17, 2026 · 5 revisions

Configuration

One TOML file. Everything has a default except the inventory. The annotated example ships with the package: cvescope init copies it, or read cvescope/config.example.toml.

Secrets never go in the file

Every credential is read from a file holding just the secret, or from an environment variable:

token_file = "~/.secrets/pve-token"   # or token_env = "PVE_TOKEN"
password_file = "~/.secrets/pihole"   # or password_env
apikey_file = "~/.secrets/unifi-key"
key_file = "~/.secrets/opn-key"       # with secret_file

Putting token = "..." inline is refused on purpose. cvescope never prints secrets, never stores them in its database, and never shows them on the page.

Certificate pinning for self-signed gear

Appliances like Proxmox, OPNsense, UniFi and Pi-hole usually have self-signed certificates. Pin each one once:

cvescope pin 192.168.1.10:8006
# pin_sha256 = "8a1f..."   compare this with the fingerprint in the device's own UI
pin_sha256 = "8a1f..."

The pin is checked before any credential is sent. A device with a proper certificate can use verify_tls = true instead. With neither, cvescope refuses to connect. allow_insecure = true exists, but don't use it with credentials.

When a device renews its certificate, the pin stops matching and that collector reports certificate pin mismatch. Re-run cvescope pin, check the new fingerprint, update the config.

Sections

data_dir = ""                 # default: user data dir (see Installation)

[tiers]
epss_watch_pct = 0.90         # EPSS percentile that lifts a match into "watch"
epss_jump = 0.25              # alert when a matched CVE's EPSS percentile rises this much

[sources]                     # all on by default
cvelist = true
kev = true
epss = true
metasploit = true
nuclei = true
exploitdb = true
github_poc = true             # needs git
distro = true                 # Debian/Ubuntu trackers, only for releases you run
distro_releases = []          # e.g. ["debian:12"] to fetch one no host reports

[[sources.local_archive]]     # optional: your own exploit / advisory folders
name = "my archive"
path = "~/exploits"
base_url = "https://example.org/exploits/"   # optional, makes the links clickable

[notify]                      # see Tiers and Alerts
min_tier = "act"

[serve]
host = "127.0.0.1"
port = 8096
allowed_hosts = []            # extra Host names if you bind wider (put auth in front!)
stale_after_hours = 12        # banner when the last full sync is older than this
read_only = false             # true: no Acknowledge buttons, every write refused

[nvd]                         # optional, see Data Sources
enabled = false
api_key_env = "NVD_API_KEY"   # optional, or api_key_file
max_per_run = 40

[[inventory]]                 # one block per collector, see Collectors
type = "static"
name = "Nextcloud"
vendor = "nextcloud"
product = "nextcloud server"
version = "30.0.4"

Keys every [[inventory]] block accepts: name, aliases = ["vendor:product", ...], keywords = [...] (used only for old CVEs whose records name no product), and enabled = false.

Scheduling

Run cvescope sync every few hours. --log FILE appends everything a run prints to a file (rotated at 5 MB, errors included with their traceback), which is what you want when nothing is watching the console. It's a global option, so it goes before the command.

Linux / macOS, cron:

0 */3 * * * cvescope --log ~/.local/share/cvescope/sync.log sync

Windows, Task Scheduler. In PowerShell, after pip install .:

$py = (Get-Command pythonw).Source
$a  = New-ScheduledTaskAction -Execute $py -Argument "-m cvescope --log `"$env:LOCALAPPDATA\cvescope\sync.log`" sync"
$t  = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(5) -RepetitionInterval (New-TimeSpan -Hours 3)
$s  = New-ScheduledTaskSettingsSet -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew
Register-ScheduledTask -TaskName cvescope-sync -Action $a -Trigger $t -Settings $s

What those settings buy you:

  • pythonw runs it without a console window popping up every three hours.
  • -StartWhenAvailable catches up on a run the PC slept through.
  • -MultipleInstances IgnoreNew stops a slow run from overlapping the next one.
  • Registered this way, the task runs as you while you're logged in, so it sees your config and any *_env variables your collectors use.

Running from a checkout instead of pip install? Add -WorkingDirectory <repo> to New-ScheduledTaskAction. Using a config outside the default location? Add --config <path> next to --log.

Check on it with Get-ScheduledTaskInfo cvescope-sync (LastTaskResult 0 means success) and the end of the log file.

Knowing the schedule still works

Every full cvescope sync records when it finished and which feeds or collectors failed. The page's header shows "synced N ago", and a banner appears when:

  • the last full sync is older than serve.stale_after_hours (default 12);
  • no full sync has been recorded yet; or
  • a feed or collector failed in the last run (it names which).

cvescope status prints the same. With syncs every 3 hours, the default means four missed runs before it complains.

[serve]
stale_after_hours = 12

Keeping the page private

cvescope serve binds to 127.0.0.1 and rejects requests whose Host header isn't the address it serves on, which blocks DNS-rebinding tricks from other websites. The page is a list of what's vulnerable in your network: if you bind it wider, add the names to allowed_hosts and put real authentication in front of it.

Clone this wiki locally