Metadata-Version: 2.4
Name: rodmena-provenance
Version: 0.1.1
Summary: Reports a Linux or FreeBSD host's operating-system packages to provenance every day
License-Expression: Apache-2.0
Project-URL: Provenance, https://provenance.rodmena.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: POSIX :: BSD :: FreeBSD
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# rodmena-provenance

`rp` reports a host's operating-system packages to [provenance](https://provenance.rodmena.com) 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](https://ci.rodmena.co.uk) 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.
