# Ponvara Every documentation page, concatenated. Canonical site: https://docs.magmamoose.com/ponvara/ --- # Ponvara — Design Source: docs/DESIGN.md URL: https://docs.magmamoose.com/ponvara/DESIGN/ **Status:** Phase 1 complete (REST API slim image with Dependency-Track and GHAS syncs) · **Date:** 2026-08-27 Promote the in-cluster `dt-defectdojo-sync` CronJob (and its SonarQube sibling) into its own repo, container, and Helm chart — a long-lived, tested, versioned backend deployed separately via Flux — and generalize it into a **finding bus**. Scope is deliberately bounded: this does **not** widen [chargate](https://github.com/MagmaMoose/chargate)'s PR-time gate; Ponvara is the continuous/runtime counterpart. --- ## 1. What exists today In the private infra repo (`kubernetes/apps/security-integrations/`): | Resource | What it does | | --- | --- | | `configmap-sync-script.yaml` | ~180-line `sync.py` **embedded in YAML** | | `cronjob-dt-sync.yaml` | Hourly CronJob; runs `sync.py` inside `defectdojo/defectdojo-django:2.58.4` | | `cronjob-sonarqube-sync.yaml` | Sibling, +30m offset, own embedded script | | `configmap-sonarqube-sync.yaml` | The SonarQube script | | `externalsecret-sync.yaml` | `DTRACK_API_KEY`, `SONARQUBE_TOKEN` from OCI Vault | | `externalsecret-github-targets.yaml` | `GITHUB_TARGETS` JSON (server + owners + PAT) from OCI Vault | **`sync.py` does two jobs per Dependency-Track project:** 1. Export findings as **FPF** → DefectDojo **`reimport-scan`** (`auto_create_context`, `close_old_findings`, dedupe). One DefectDojo product per Dependency-Track project. 2. **Zero-touch GitHub issue auto-push**: resolve a repo by matching the Dependency-Track project name to `/` across configured GitHub accounts (github.com first, then GHE), open issues for new **High/Critical** Active findings, and record a `GITHUB_Issue` so re-runs dedupe. **The critical coupling:** it runs *inside the DefectDojo Django image* and uses the **Django ORM** for exactly two things — (a) minting a superuser API token without a password (`Token.objects.get_or_create`), and (b) the GitHub-issue dedupe/query (`Finding.objects.filter(...)`, `GITHUB_Issue.objects.create(...)`). --- ## 2. Why promote it (the problems) - **Code-in-YAML.** No tests, no linting, no type-checking, no CI, painful review and diffs. A security-critical integration deserves the same rigor as chargate. - **Image coupling + version lockstep.** Pinned to `defectdojo-django:2.58.4` so the ORM matches the live DB schema — **every DefectDojo chart upgrade forces a lockstep bump**, and the image is ~1 GB. This is the single biggest fragility. - **ORM coupling to DefectDojo internals.** Importing `dojo.models` / `dojo.github.models` ties the job to DefectDojo's private data model across versions. - **Mixed concerns, no reuse.** DT sync, SonarQube sync, and GitHub push are three copies/variants with no shared library, no versioning, no release artifact. - **Batch-only.** CronJobs can't be triggered on demand, expose no health/metrics, and there's nowhere to add a webhook (e.g. "DT analysis finished → sync now"). The goal is a **long-lived backend, in a repo, with a Helm chart, deployed separately.** That's the right call — and it unlocks a bigger idea below. --- ## 3. The bigger framing: a *finding bus*, not just a DT sync Once it's a real service, generalize it slightly. It becomes the **orchestration + enrichment layer** that sits beside DefectDojo: ```text Dependency-Track ─┐ SonarQube ────────┤ ┌─→ DefectDojo (reimport-scan, dedupe, SLA) DAST (ZAP/Nuclei)─┤──▶ Ponvara ────┤ ──┘ (connectors + └─→ GitHub Issues (zero-touch, High/Crit) scheduler + API) ``` Not everything needs this bus — **Trivy Operator, Prowler, ZAP, Nuclei have native DefectDojo parsers** (see the [security-tooling roadmap](https://github.com/MagmaMoose/security-platform)), so those push straight to DefectDojo. Scheduled DAST is owned by [draventis](https://github.com/MagmaMoose/draventis), which uses those native parsers. The bus earns its keep for exactly the cases the current CronJob handles: - **Movement DefectDojo can't do itself** — Dependency-Track has no "push to DefectDojo"; *something* must pull FPF and reimport. Same for any source lacking a native DefectDojo path. - **Cross-cutting enrichment** — the **zero-touch GitHub-issue auto-push** (repo resolution by name across owners) is logic DefectDojo's per-product GitHub config can't do generically. This is the real value-add and belongs in one place. So: keep it focused (DT + SonarQube + GitHub-issue push at launch), but structure it so a new source is a new connector module. --- ## 4. Target architecture **Language:** Python 3.11+ (the runtime image targets 3.12-slim), packaged with **uv + Ruff + pytest + full type hints** — mirror chargate's conventions exactly (and its `broker/` deploy pattern). **The one design decision that unlocks everything: drop the Django ORM, use the DefectDojo REST API v2.** Replace the two ORM usages: | ORM usage today | REST replacement | | --- | --- | | Mint superuser token via `Token.objects` | **Provision one DefectDojo API token** (a dedicated `ponvara` service user) once, store in OCI Vault. No ORM, no password. | | `Finding.objects.filter(...)` + `GITHUB_Issue.objects.create(...)` for dedupe | Query `GET /api/v2/findings/` (filter by product/severity/active); dedupe by writing a **finding tag** `gh-issue:` (or a note) via `PATCH /api/v2/findings/{id}/`. State lives *in DefectDojo*, so the service stays stateless. | **Result:** run on a **slim `python:3.12-slim` image (~80 MB)**, fully **decoupled from DefectDojo's version**. This alone removes the worst fragility. ### Repo layout ```sh ponvara/ pyproject.toml # uv; deps: httpx, pydantic-settings, apscheduler, # fastapi+uvicorn, PyGithub (or raw httpx), prometheus-client src/ponvara/ config.py # pydantic-settings: sources, schedules, thresholds, secret refs defectdojo.py # REST client: reimport-scan (SINK) [Phase 1] dependencytrack.py # REST client: list projects, export FPF (SOURCE) [Phase 1] github.py # REST client: pull GHAS findings (SOURCE) [Phase 1] sync.py # orchestrator: DT → DefectDojo [Phase 1] sync_github.py # orchestrator: GHAS → DefectDojo [Phase 1] # Future files (Phase 2+): app.py # FastAPI: /healthz /readyz /metrics + POST /sync/{source} scheduler.py # APScheduler: interval jobs per enabled source github_issues.py # zero-touch repo resolve + issue push (SINK) [Phase 2] sonarqube.py # REST client: pull findings (SOURCE) [Phase 4] models.py # typed Finding/Project DTOs charts/ponvara/ # Helm chart (below) tests/ # mirror modules 1:1 (pure connectors, injected HTTP) Dockerfile # slim, non-root, distroless-ish .github/workflows/ # ci.yml (ruff+pytest), release.yml (semantic-release + GHCR image) ``` > **Phase 1 status.** Complete. The repo contains the connector modules (Dependency-Track, > GitHub Advanced Security, DefectDojo), full test coverage (pure connectors, HTTP-mocked), > configuration management, CLI (sync + sync-github commands), and the Helm chart > (CronJob deployments). Dockerfile and GitHub Actions workflows are in place. Phase 2+ > work (GitHub-issue push, long-lived service, generalization) remains future. ### Runtime shape — long-lived Deployment A single **Deployment** (replicas: 1, `Recreate`) running `uvicorn`: - **In-process scheduler** (APScheduler) runs each source on its interval — replaces the two CronJobs, keeps offsets, adds jitter. - **HTTP surface:** `/healthz`, `/readyz`, `/metrics` (Prometheus), and `POST /sync/{source}` for on-demand runs (handy for testing + future DT webhooks). - **`concurrency: Forbid` semantics** via an in-process lock per source. - Emits metrics: `ponvara_sync_findings_total{source}`, `..._github_issues_total`, `..._last_success_timestamp{source}`, `..._errors_total`. > Simpler alternative if a daemon isn't wanted: keep **CronJobs but from our own slim > image** (chart `kind: CronJob`). You still get the repo/tests/CI/decoupling wins; you > lose on-demand triggers + metrics. The Helm chart can support **both** via a > `mode: deployment|cronjob` value. **Recommendation: Deployment** — it's literally the > "long-lived backend" described here, and the incremental ops cost is tiny. ### Helm chart (`charts/ponvara/`) `values.yaml` sketch (the full stub lives in [`charts/ponvara/values.yaml`](https://github.com/MagmaMoose/ponvara/blob/main/charts/ponvara/values.yaml)): ```yaml image: { repository: ghcr.io/magmamoose/ponvara, tag: "" } # Flux ImagePolicy fills tag mode: deployment # or "cronjob" schedule: { dependencyTrack: "0 * * * *", sonarqube: "30 * * * *" } # cron OR interval secs defectDojo: url: http://defectdojo-django.security.svc.cluster.local productType: Dependency-Track sources: dependencyTrack: enabled: true url: http://dependency-track-api-server.security.svc.cluster.local:8080 sonarqube: { enabled: true, url: https://sonarqube.magmamoose.com } github: { minSeverity: High, maxIssuesPerRun: 50 } externalSecrets: # ESO -> OCI Vault (unchanged keys) store: oci-vault keys: { dtrackApiKey: dependency-track-api-key, ddApiToken: ponvara-dd-token, githubTargets: github-issue-targets, sonarToken: defectdojo-api-key } resources: { requests: { cpu: 50m, memory: 128Mi }, limits: { memory: 256Mi } } serviceMonitor: { enabled: true } ingress: { enabled: false } # cloudflared tunnel if the trigger API is exposed podSecurityContext: { runAsNonRoot: true, runAsUser: 10001, seccompProfile: { type: RuntimeDefault } } ``` Templates: `deployment.yaml` **or** `cronjob.yaml` (by `mode`), `service.yaml`, `servicemonitor.yaml`, `externalsecret.yaml`, `serviceaccount.yaml` (`automountServiceAccountToken: false` — it never calls the k8s API), `_helpers.tpl`. Ship the same hardening the SonarQube CronJob already uses (non-root high UID, RO rootfs, seccomp RuntimeDefault, no SA token). ### Deploy via Flux (mirror chargate/broker) - `infra/kubernetes/apps/ponvara/{base,prod}/` with a `HelmRelease` pointing at the chart (or a Flux `Kustomization` if the chart is vendored), an `ImagePolicy` autobumping the tag on each GHCR release, and the `ExternalSecret`s (reuse the existing OCI Vault keys; add one new key: `ponvara-dd-token`). - Retire `kubernetes/apps/security-integrations/` once cut over. ### Image + release (mirror chargate) GHCR image `ghcr.io/magmamoose/ponvara`, built by a `release.yml` that runs python-semantic-release (version-from-commits) and a multi-arch `docker buildx` push — the exact pattern chargate already uses for its `broker` image. Flux's `ImagePolicy` rewrites the chart tag on publish. External GitHub Actions are **SHA-pinned** with a `# vX.Y.Z` comment. --- ## 5. Migration plan (low-risk, phased) | Phase | Change | Status | Risk | Reversible? | | --- | --- | --- | --- | --- | | **0. Lift-and-shift** | New repo; move `sync.py` verbatim; add tests around the pure bits (target parsing, severity floor, issue body). Still the DefectDojo-image CronJob, still deployed from infra. | ✅ DONE | none | trivially | | **1. Slim the image** | Provision a `ponvara` DefectDojo API token (OCI Vault); replace ORM token-mint with it; switch to `python:3.12-slim`. Add GitHub Advanced Security sync (GHAS code scanning, Dependabot, secret scanning). | ✅ DONE | low | keep old CronJob until green | | **2. GitHub-issue push + tag-based dedupe** | Implement zero-touch GitHub-issue push for High/Critical findings (requires DefectDojo findings query + tag-based state in DefectDojo). Now fully version-decoupled from DefectDojo. | 📋 TODO | med (verify tag/note dedupe survives reimport) | run both in parallel one cycle | | **3. Long-lived service** | Convert to the FastAPI+APScheduler Deployment; add `/metrics`, `/sync/{source}`, ServiceMonitor; Helm chart; Flux app dir. Retire the infra CronJobs/ConfigMaps. | 📋 TODO | med | Flux rollback | | **4. Generalize** | Fold SonarQube in as a connector; document how a new source plugs in. Point future non-native sources (e.g. a bespoke DAST result shape) here; leave native-parser tools (Trivy Operator, Prowler, ZAP, Nuclei) pushing straight to DefectDojo. | 📋 TODO | low | per-connector toggle | You can stop after Phase 1 or 2 and already have a tested, reviewable, slim, version-decoupled job — most of the value is there. Phases 3–4 deliver the "long-lived backend" and the reuse. --- ## 6. Open decisions 1. **Name.** `ponvara` (descriptive) — chosen, matching the sibling repos [draventis](https://github.com/MagmaMoose/draventis) and [security-platform](https://github.com/MagmaMoose/security-platform) under the MagmaMoose org. ✅ Resolved. 2. **REST API** (Phase 1 decision) — chosen **yes**. Enables slim image, version-decoupled from DefectDojo. Phase 1 confirmed this works. ✅ Resolved. 3. **Tag/note-based dedupe for GitHub-issue push** (Phase 2) — recommended **yes**. Must validate that **`reimport-scan` preserves finding tags** (if reimport recreates findings, fall back to stable finding hash instead). 4. **Deployment vs CronJob-from-own-image** (Phase 3) — "long-lived backend" → **Deployment**. The chart supports both, so this is reversible. 5. **Dedup state for phase 2+:** Stateless via DefectDojo tags (recommended) vs a tiny CNPG Postgres the service owns (needed only if cross-source correlation/SLA is tracked here later). --- ## 7. First PR (crawl) Create `MagmaMoose/ponvara` (this repo), `uv init`, drop `sync.py` in as `src/ponvara/sync.py`, split the GitHub-target parsing + severity-floor logic into pure functions, add `tests/` for them, wire `ci.yml` (ruff + pytest). Keep the existing infra CronJob running untouched. That's Phase 0 — zero production risk, and it gives every later phase a tested base to refactor against. --- ## Related work - **[MagmaMoose/chargate](https://github.com/MagmaMoose/chargate)** — PR-time SAST/SCA/IaC gate (MegaLinter wrapper with net-new gating). Ponvara mirrors its conventions and `broker/` deploy pattern, and is the continuous/runtime counterpart to chargate's pre-merge gate. - **[MagmaMoose/draventis](https://github.com/MagmaMoose/draventis)** — scheduled DAST (ZAP + Nuclei) → DefectDojo via native parsers. - **[MagmaMoose/security-platform](https://github.com/MagmaMoose/security-platform)** — the program index and security-tooling roadmap. - **DefectDojo** and **Dependency-Track** — self-hosted in the private infra repo; DefectDojo is the system of record, Dependency-Track the SBOM/SCA source this bus was born to feed. --- # Roadmap Source: docs/explanation/roadmap.md URL: https://docs.magmamoose.com/ponvara/explanation/roadmap/ Ponvara's status is claimed here and nowhere else. If a maturity claim appears in another file in this repository, that file is wrong. ## Where it is now Phase 1: Dependency-Track and GitHub Advanced Security syncs to DefectDojo, ported off the Django ORM onto the DefectDojo REST API. Shipping as a Helm chart with two CronJobs (Dependency-Track sync and GitHub Advanced Security sync) plus ExternalSecrets. ## Implemented **Core sync engine:** - Dependency-Track → DefectDojo via REST API (no Django ORM coupling) - GitHub Advanced Security → DefectDojo (code scanning, Dependabot, secret scanning) - Full test suite with mocked HTTP clients - Configuration via environment variables (pydantic-settings) - Helm chart with CronJob templates for both Dependency-Track and GitHub Advanced Security syncs **Next phases (TODO):** - Phase 2: Zero-touch GitHub-issue push for High/Critical findings (tag-based dedup in DefectDojo) - Phase 3: Long-lived FastAPI + APScheduler service with `/metrics`, `/sync/{source}` endpoints - Phase 4: SonarQube connector and generalized source plugin architecture ## Phased migration Low-risk and reversible; each phase leaves the previous one running until it's green. Full detail (risk + reversibility columns) in [`../DESIGN.md`](../DESIGN.md). | Phase | Change | Status | | --- | --- | --- | | **0. Lift-and-shift** | New repo; move `sync.py` verbatim; add tests around the pure bits (target parsing, severity floor, issue body). Still the DefectDojo-image CronJob, still deployed from infra. | ✅ DONE | | **1. Slim the image + GHAS** | Provision a `ponvara` DefectDojo API token (OCI Vault); replace the ORM token-mint with it; switch to `python:3.12-slim`. Add GitHub Advanced Security sync (code scanning, Dependabot, secret scanning). | ✅ DONE | | **2. GitHub-issue push** | Implement zero-touch GitHub-issue push for High/Critical findings. Requires DefectDojo findings query and tag-based state tracking. Now fully version-decoupled. | 📋 TODO | | **3. Long-lived service** | Convert to the FastAPI + APScheduler Deployment; add `/metrics`, `/sync/{source}`, ServiceMonitor; Helm chart; Flux app dir. Retire the infra CronJobs/ConfigMaps. | 📋 TODO | | **4. Generalize** | Fold SonarQube in as a connector; document how a new source plugs in. Point future non-native sources here; leave native-parser tools pushing straight to DefectDojo. | 📋 TODO | You can stop after Phase 1 or 2 and already have a tested, reviewable, slim, version-decoupled job — most of the value is there. Phases 3–4 deliver the long-lived backend and the reuse. ## Open decisions Unresolved questions for future phases. Each should become an ADR with `Status: Proposed` once it has a shape. Tracked in [`../DESIGN.md § Open decisions`](../DESIGN.md#open-decisions): 1. **Tag-based dedup for GitHub push** (Phase 2). Recommended: validate that `reimport-scan` preserves finding tags so GitHub-issue dedup can use them; fall back to finding hash if reimport recreates findings. 2. **Deployment vs CronJob-from-own-image** (Phase 3) — "long-lived backend" points to **Deployment**; the chart supports both. 3. **Dedup state** (Phase 2) — stateless via DefectDojo tags (recommended) vs a tiny service-owned Postgres (only if cross-source correlation/SLA is tracked here). 4. **Scope beyond Phase 1** — confirmed: Phase 2 adds GitHub-issue push; Phase 3 adds long-lived service; Phase 4 adds SonarQube connector and generalization. --- # Ponvara Source: docs/index.md URL: https://docs.magmamoose.com/ponvara/ A **finding bus**: pulls security findings from sources that cannot push to [DefectDojo](https://github.com/DefectDojo/django-DefectDojo) themselves and reimports them. Runs as a CronJob; will be generalized to a long-lived scheduler with zero-touch GitHub-issue push for High and Critical findings (future). It promotes an existing, working-but-fragile in-cluster CronJob (`dt-defectdojo-sync`) into a tested, versioned service, and generalises it so a new source is a new connector module rather than a new CronJob. ## Architecture ```text Dependency-Track ─┐ GitHub Adv. Sec. ─┤ ┌─→ DefectDojo (reimport-scan, dedupe, SLA) SonarQube ────────┤──▶ Ponvara ───────┤ DAST (ZAP/Nuclei)─┤ (connectors) └─→ GitHub Issues (zero-touch, High/Crit — future) ──┘ ``` - **Sources:** Dependency-Track, GitHub Advanced Security, and future connectors pull findings. - **Sink:** DefectDojo (via `reimport-scan`). GitHub Issues push is Phase 2 work. - **Current phase:** CLI with `ponvara sync` and `ponvara sync-github` commands (CronJob-based). Each command runs once and exits, scheduled via Kubernetes CronJob and Helm chart. - **Future phases:** long-lived Deployment with APScheduler, on-demand endpoints, GitHub-issue push. ## Why the REST API, not the Django ORM The legacy job reaches into DefectDojo's **private Django data model** for two things. The first has been replaced; the second is future work: | Django ORM usage | REST replacement | Status | | --- | --- | --- | | Mint a superuser API token via `Token.objects.get_or_create` | Provision **one** DefectDojo API token for a dedicated `ponvara` service user, once, stored in OCI Vault. No ORM, no password. | ✅ Done (Phase 1) | | `Finding.objects.filter(...)` + `GITHUB_Issue.objects.create(...)` for GitHub-issue dedupe | `GET /api/v2/findings/` (filter by product/severity/active); dedupe by writing a **finding tag** `gh-issue:` via `PATCH /api/v2/findings/{id}/`. State lives in DefectDojo, service stays stateless. | 📋 Phase 2 (GitHub-issue push feature) | **Result:** Ponvara runs on a **slim `python:3.12-slim` image (~80 MB)** and is **fully decoupled from DefectDojo's version** — DefectDojo chart upgrades no longer force a lockstep bump. This removes the biggest fragility of the current setup. ## How it fits the security programme Ponvara is the **runtime / continuous** half of the security tooling estate; it complements the others rather than overlapping them: - **[MagmaMoose/chargate](https://github.com/MagmaMoose/chargate)** — the **PR-time** SAST/SCA/IaC gate (a MegaLinter wrapper with net-new gating). Chargate acts *before merge* on a single PR; Ponvara acts *continuously* on deployed/portfolio-wide findings. Chargate already ships full SARIF to DefectDojo and BOMs to Dependency-Track; Ponvara moves what those tools produce onward. - **[MagmaMoose/draventis](https://github.com/MagmaMoose/draventis)** — scheduled DAST (ZAP + Nuclei) → DefectDojo. ZAP/Nuclei have native DefectDojo parsers, so draventis pushes straight to DefectDojo; if a bespoke DAST result shape ever needs orchestration/enrichment, it becomes a Ponvara connector. - **[MagmaMoose/security-platform](https://github.com/MagmaMoose/security-platform)** — the program index and security-tooling roadmap that ties chargate, draventis, Ponvara, DefectDojo, and Dependency-Track together. - **DefectDojo** (self-hosted, private infra repo) — the aggregation/dedupe/SLA system of record. Ponvara is its **feeder** for sources that can't push themselves. - **Dependency-Track** (self-hosted, private infra repo) — the SBOM/SCA source. Dependency-Track has no "push to DefectDojo"; Ponvara pulls its FPF export and reimports it. This is the original job the bus was born from. ## Next - [Design](DESIGN.md) — the full design document - [Roadmap](explanation/roadmap.md) — what is built, what is next, what is undecided