Skip to main content

rodmena-provenance

rp reports a host's operating-system packages to provenance once a day. It runs on the host itself, builds a CycloneDX 1.6 SBOM from the package database, records the release and its deployment on the host's asset, and asks provenance to scan it. On FreeBSD it also sends pkg audit output to provenance's advisory-reports route, because OSV has no FreeBSD data.

Application packages are out of scope. Those are reported by the CI pipeline that builds each application.

Supported systems

System Collector Tested on
Ubuntu 24.04, 26.04 dpkg-query and apt-cache policy the RODMENA fleet
FreeBSD 15.1 pkg query, pkg audit, freebsd-version the RODMENA fleet

Other dpkg systems are refused, because the package naming rules are Ubuntu's. rpm and apk are not written yet. A new collector is a shell script in rodmena_provenance/collectors/ that prints the same line prefixes, plus a module that turns them into components.

Python 3.12 or later. No dependencies outside the standard library.

Install

python3 -m venv /opt/rodmena-provenance        # /usr/local/rodmena-provenance on FreeBSD
/opt/rodmena-provenance/bin/pip install rodmena-provenance==0.1.1
printf '%s\n' "$KEY" | sudo /opt/rodmena-provenance/bin/rp enroll --product host-<name> --asset <asset uuid> --key-stdin
sudo -u _rprov /opt/rodmena-provenance/bin/rp doctor
sudo /opt/rodmena-provenance/bin/rp schedule

rp enroll creates the system user _rprov and writes the config and the key file. The key file is mode 0400 and owned by _rprov. Enroll also lets _rprov write to node_exporter's textfile directory through the group textfile-writers. It keeps the directory's owner, sets the group and mode 1775, then checks that every account that already writes files there can still create one. If any of them cannot, it puts the old group and mode back and stops.

rp schedule installs two systemd timers on Linux, or /usr/local/etc/cron.d/rodmena-provenance on FreeBSD. The daily run starts between 04:00 and 05:59 UTC at a minute taken from the host name, and a retry follows 150 minutes later. On FreeBSD a slot between 04:15 and 05:30 moves to 05:45 on Saturdays, out of the way of the weekly package upgrade. The retry does nothing if the day's run already succeeded.

Commands

rp report              collect, publish, scan; exits non-zero if any step fails
rp report --dry-run    collect and print the version and purls without sending anything
rp status              the live release on this host's asset and when it was last scanned
rp findings            open-exposure findings for this host
rp doctor [--offline]  config, key file mode, tools, API reach, clock, and a vuln.xml fetch on FreeBSD

A release is created only when the package list changes. Its version is <os version>-<first 12 hex of the sha256 of the sorted purls>. An unchanged release is scanned again once its last scan is more than 20 hours old. A run fails unless provenance returns scanner_verified: true.

Config

/etc/rodmena-provenance/config.toml (FreeBSD: /usr/local/etc/rodmena-provenance/config.toml):

product = "host-pg-nano-04"
asset = "<asset uuid>"
base_url = "https://provenance.rodmena.com/api/v1"
key_file = "/etc/rodmena-provenance/key"
state_dir = "/var/lib/rodmena-provenance"
textfile_dir = "/var/lib/prometheus/node-exporter"
vuxml_fetch = true
vuxml_path = "/var/lib/rodmena-provenance/vuln.xml"
scan_wait_max_seconds = 900
rescan_hours = 20

Only product and asset are required. An unknown key is an error.

Metrics

rodmena_provenance_rp.prom in the textfile directory, each gauge labelled with product:

Gauge Meaning
rodmena_provenance_last_attempt_start_timestamp_seconds when the last run started
rodmena_provenance_last_attempt_end_timestamp_seconds when it ended, successful or not
rodmena_provenance_last_run_ok 1 if it completed, 0 if it failed or was stopped by SIGTERM
rodmena_provenance_last_success_timestamp_seconds when a run last completed
rodmena_provenance_last_scanned_at_seconds provenance's last scan of the live release
rodmena_provenance_components_not_checked components that scan could not check
rodmena_provenance_vuxml_fetch_timestamp_seconds FreeBSD: last vuln.xml fetch
rodmena_provenance_vuxml_date_seconds FreeBSD: date of the vuln.xml audited against
rodmena_provenance_checked_until_seconds FreeBSD: provenance's checked_until for the advisory report

A run killed with SIGKILL leaves a start time later than the end time, which is what the RpRunHung alert looks for.

Development

Tests run in RODMENA CI on Python 3.12 and 3.14: python3 -m unittest discover -s tests -t .. CI also builds the wheel and sdist, installs the wheel into a clean venv and runs it. Publishing to PyPI is done from a host, never from CI.

Apache-2.0.

Metadata

Release files for rodmena-provenance 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rodmena-provenance 0.1.1
File Size Uploaded Provenance Actions
rodmena_provenance-0.1.1.tar.gz 42.9 kB Without provenance Details for rodmena_provenance-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rodmena-provenance 0.1.1
File Interpreter ABI Platform Actions
rodmena_provenance-0.1.1-py3-none-any.whl Python 3 none any Details for rodmena_provenance-0.1.1-py3-none-any.whl

Total release size: 74.4 kB

Release files / rodmena_provenance-0.1.1.tar.gz

Download URL rodmena_provenance-0.1.1.tar.gz
Size 42.9 kB
Tags Source
SHA-256 checksum
How to use checksums
dae7e14106ca120b69398e06bde97aefc637cac511f02333345d1a4049ba1d46
BLAKE2b-256 checksum
How to use checksums
db516d9816d8634a245f62bf811760e53bdceac1cb45ce599a6ea8979d37748e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / rodmena_provenance-0.1.1-py3-none-any.whl

Download URL rodmena_provenance-0.1.1-py3-none-any.whl
Size 31.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
05b3a08e46e125937206ec9fb0914418f125baf35fe3ec87ea7b8664990113e3
BLAKE2b-256 checksum
How to use checksums
05356453d0aa8fbcd0cf136d0807624785a23bd2b75e52a44271560f8e5a1a4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for rodmena-provenance 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page