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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.