stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/excititor/operations/ubuntu-csaf.md
master cef4cb2c5a Add support for ГОСТ Р 34.10 digital signatures 
- Implemented the GostKeyValue class for handling public key parameters in ГОСТ Р 34.10 digital signatures.
- Created the GostSignedXml class to manage XML signatures using ГОСТ 34.10, including methods for computing and checking signatures.
- Developed the GostSignedXmlImpl class to encapsulate the signature computation logic and public key retrieval.
- Added specific key value classes for ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012/256, and ГОСТ Р 34.10-2012/512 to support different signature algorithms.
- Ensured compatibility with existing XML signature standards while integrating ГОСТ cryptography.
2025-11-09 21:59:57 +02:00

4.5 KiB
Raw Blame History

Ubuntu CSAF connector runbook

Updated 2025-11-09 alongside sprint 110/120 trust-provenance work.

Purpose

  • Ingest Ubuntu USN/CSAF statements via the restart-only connector (StellaOps.Excititor.Connectors.Ubuntu.CSAF).
  • Preserve Aggregation-Only Contract guarantees while surfacing issuance provenance (vex.provenance.*) for VEX Lens and Policy Engine.
  • Allow operators to tune trust weighting (tiers, fingerprints, cosign issuers) without recompiling the connector.

Configuration keys

Key Default Notes
Excititor:Connectors:Ubuntu:IndexUri https://ubuntu.com/security/csaf/index.json Ubuntu CSAF index. Override only when mirroring the feed.
...:Channels ["stable"] List of channel names to poll. Order preserved for deterministic cursoring.
...:MetadataCacheDuration 4h How long to cache catalog metadata before re-fetching.
...:PreferOfflineSnapshot / OfflineSnapshotPath / PersistOfflineSnapshot false / null / true Enable when running from Offline Kit bundles. Snapshot path must be reachable/read-only under sealed deployments.
...:TrustWeight 0.75 Baseline trust weight (0–1). Lens multiplies this by freshness/justification modifiers.
...:TrustTier "distro" Friendly tier label surfaced via vex.provenance.trust.tier (e.g., distro-trusted, community).
...:CosignIssuer / CosignIdentityPattern null Supply when Ubuntu publishes cosign attestations (issuer URL and identity regex). Required together.
...:PgpFingerprints [] Ordered list of trusted PGP fingerprints. Emitted verbatim as vex.provenance.pgp.fingerprints.

Example appsettings.json

{
  "Excititor": {
    "Connectors": {
      "Ubuntu": {
        "IndexUri": "https://mirror.example.com/security/csaf/index.json",
        "Channels": ["stable", "esm-apps"],
        "TrustWeight": 0.82,
        "TrustTier": "distro-trusted",
        "CosignIssuer": "https://issuer.ubuntu.com",
        "CosignIdentityPattern": "spiffe://ubuntu/vex/*",
        "PgpFingerprints": [
          "0123456789ABCDEF0123456789ABCDEF01234567",
          "89ABCDEF0123456789ABCDEF0123456789ABCDEF"
        ],
        "PreferOfflineSnapshot": true,
        "OfflineSnapshotPath": "/opt/stella/offline/ubuntu/index.json"
      }
    }
  }
}

Environment variable cheatsheet

Excititor__Connectors__Ubuntu__TrustWeight=0.9
Excititor__Connectors__Ubuntu__TrustTier=distro-critical
Excititor__Connectors__Ubuntu__PgpFingerprints__0=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Excititor__Connectors__Ubuntu__PgpFingerprints__1=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
Excititor__Connectors__Ubuntu__CosignIssuer=https://issuer.ubuntu.com
Excititor__Connectors__Ubuntu__CosignIdentityPattern=spiffe://ubuntu/vex/*

Operational checklist

  1. Before enabling – import the Ubuntu PGP bundle (Offline Kit provides certificates/ubuntu-vex.gpg) and set the fingerprints so provenance metadata stays deterministic.
  2. Validate provenance output – run dotnet test src/Excititor/__Tests/StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests --filter FetchAsync_IngestsNewDocument to ensure the connector emits the vex.provenance.* fields expected by VEX Lens.
  3. Monitor Lens weights – Grafana panels VEX Lens / Trust Inputs show the weight/tier captured per provider. Ubuntu rows should reflect the configured TrustWeight and fingerprints.
  4. Rotate fingerprints – update PgpFingerprints when Canonical rotates signing keys. Apply the change, restart Excititor workers, verify the provenance metadata, then trigger a targeted Lens recompute for Ubuntu issuers.
  5. Offline mode – populate OfflineSnapshotPath via Offline Kit bundles before toggling PreferOfflineSnapshot. Keep snapshots in the sealed /opt/stella/offline hierarchy for auditability.

Troubleshooting

  • Connector refuses to start – check logs for InvalidOperationException referencing CosignIssuer/CosignIdentityPattern or missing snapshot path; the validator enforces complete pairs and on-disk paths.
  • Lens still sees default weights – confirm the Excititor deployment picked up the new settings (view /excititor/health JSON → connectors.providers[].options). Lens only overrides when the provenance payload includes vex.provenance.trust.* fields.
  • PGP mismatch alerts – if Lens reports fingerprint mismatches, ensure the list ordering matches Canonical’s published order; duplicates are trimmed, so provide each fingerprint once.