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/venv   # /usr/local/rodmena-provenance/venv on FreeBSD
/opt/rodmena-provenance/venv/bin/pip install rodmena-provenance==0.1.2
printf '%s\n' "$KEY" | sudo /opt/rodmena-provenance/venv/bin/rp enroll --product host-<name> --asset <asset uuid> --key-stdin
sudo -u _rprov /opt/rodmena-provenance/venv/bin/rp doctor
sudo /opt/rodmena-provenance/venv/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.2

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.2
File Size Uploaded Provenance Actions
rodmena_provenance-0.1.2.tar.gz 43.6 kB Without provenance Details for rodmena_provenance-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 75.4 kB

Release files / rodmena_provenance-0.1.2.tar.gz

Download URL rodmena_provenance-0.1.2.tar.gz
Size 43.6 kB
Tags Source
SHA-256 checksum
How to use checksums
bbf32d20a0e1e3ccadf2c0d05edd9a97a0935cd80cf37bf271cc12658236cc53
BLAKE2b-256 checksum
How to use checksums
05a91986424b449b5263bfea4ee2719828767b86a4dd2a661b1ad82485c36ec2
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.2-py3-none-any.whl

Download URL rodmena_provenance-0.1.2-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
805687f300959bb573fe11fcf20eb8b326c3bafa3f5d39cc1b488a488bee3a0f
BLAKE2b-256 checksum
How to use checksums
cf0c17242497f80c296985e2ec819b8885dad5bbd78d05f0809961aa15747576
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.2

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.2 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