# ProdSec RPM Catalog

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

Builds an RPM catalog from the Hummingbird Pulp repos and publishes it to the
metadata distribution for ProdSec. Also includes a monitoring companion that
prints the last publication timestamp.

## Features

- **DNF-Based Repo Query**: Reads package metadata from all 5 Hummingbird repos
  (source, x86_64, aarch64, ppc64le, s390x) using the DNF API
- **Pulp REST API Upload**: Creates artifacts, file content, publications, and
  updates the distribution in a single automated workflow
- **Artifact Deduplication**: Skips upload when content SHA-256 matches an
  existing artifact
- **Async Task Polling**: Handles Pulp's asynchronous tasks with configurable
  timeout (10 minutes)
- **Sentry Error Reporting**: Errors are reported to Sentry when `SENTRY_DSN`
  is set
- **Monitoring Check**: Companion module prints the publication timestamp for
  automated freshness monitoring

## Prerequisites

- Python 3.11 or later
- `dnf` system library (available on Fedora/RHEL)
- Network access to `packages.redhat.com` (repo metadata)
- Pulp API access with client certificate or username/password auth
- A file repository and distribution named `metadata` in the
  `public-hummingbird` Pulp domain

## Usage

### Build and Publish Catalog

```bash
python3 -m hummingbird_tools.prodsec_catalog
```

No arguments. All configuration is via environment variables.

### Check Last Publication Time

```bash
python3 -m hummingbird_tools.prodsec_catalog_check
```

Prints the timestamp of the most recent catalog publication in local timezone.
Uses the same authentication as the catalog builder.

## Configuration

### Authentication

Client certificate auth (preferred for CronJob):

| Variable                           | Description                              |
|------------------------------------|------------------------------------------|
| `HUMMINGBIRD_PULP_BOT_CERTIFICATE` | Path to client certificate PEM file      |
| `HUMMINGBIRD_PULP_BOT_KEY`         | Path to private key PEM file (optional)  |
| `HUMMINGBIRD_PULP_BOT_PASSWORD`    | Optional passphrase for the key          |

Basic auth (alternative for local use):

| Variable        | Description          |
|-----------------|----------------------|
| `PULP_USERNAME` | Pulp API username    |
| `PULP_PASSWORD` | Pulp API password    |

Credentials can also be configured in `~/.config/pulp/cli.toml` (same format
as the pulp CLI). Set `PULP_CONFIG` to override the config file path (useful
in containers where the home directory may vary).

### Pulp API

| Variable        | Description                                                      |
|-----------------|------------------------------------------------------------------|
| `PULP_BASE_URL` | Pulp API base URL (or read from `cli.toml`)                      |
| `PULP_CONFIG`   | Path to pulp CLI config file (default `~/.config/pulp/cli.toml`) |

### Error Reporting

| Variable     | Description                            |
|--------------|----------------------------------------|
| `SENTRY_DSN` | Optional Sentry DSN for error tracking |

## CronJob Schedule

Deployed via Kubernetes CronJob in `kubernetes/hummingbird-status/`:

| CronJob          | Schedule    | Environment | Command                                              |
|------------------|-------------|-------------|------------------------------------------------------|
| prodsec-catalog  | `0 4 * * *` | production  | `python3 -m hummingbird_tools.prodsec_catalog`       |

## Catalog Format

The catalog is a tab-separated file with one RPM per line:

```text
{name}-{version}-{release}.{arch}.rpm\t{repo}\t{build_timestamp}
```

Example:

```text
nginx-1.28.0-1.hum1.x86_64.rpm  x86_64  2026-01-15 14:30:00
kernel-6.12.5-1.hum1.src.rpm    source  2026-01-10 08:00:00
```

Published at:
`https://packages.redhat.com/api/pulp-content/public-hummingbird/metadata/hummingbird-rpm-catalog.txt`

## Development

See the main [README][readme] for development workflows.

```bash
make hummingbird-tools/setup  # Install dependencies
make check                     # Lint code (ruff)
make test                      # Run unit tests
```

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[readme]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/README.md
[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE