Concelier Apple Security Update Connector — Operations Runbook

Audience: Stella Ops operators running the Concelier Apple security updates connector.

This runbook covers staging and production rollout for the Apple security updates connector (source:vndr-apple:*), including observability checks and fixture maintenance.

1. Prerequisites

concelier:
  sources:
    apple:
      softwareLookupUri: "https://support.apple.com/en-us/100100"
      advisoryBaseUri: "https://support.apple.com/"
      localeSegment: "en-us"
      maxAdvisoriesPerFetch: 25
      initialBackfill: "120.00:00:00"
      modifiedTolerance: "02:00:00"
      failureBackoff: "00:05:00"

softwareLookupUri and advisoryBaseUri must stay absolute and aligned with the HTTP allow-list; Concelier automatically adds both hosts to the connector HttpClient.

The Apple connector intentionally rejects https://gdmf.apple.com/v2/pmv. That endpoint is Apple release metadata (PublicAssetSets, AssetSets, PublicBackgroundSecurityImprovements), not a security-advisory index. A fetch cycle that receives that JSON shape fails with the unsupported-shape diagnostic gdmf_release_metadata_json instead of reporting a successful empty run.

2. Staging Smoke Test

  1. Deploy the configuration and restart the Concelier workers to ensure the Apple connector options are bound.
  2. Trigger a full connector cycle:
    • CLI: run stella db fetch --source vndr-apple --stage fetch, then --stage parse, then --stage map.
    • REST: POST /jobs/run { "kind": "source:vndr-apple:fetch", "chain": ["source:vndr-apple:parse", "source:vndr-apple:map"] }
  3. Validate metrics exported under meter StellaOps.Concelier.Connector.Vndr.Apple:
    • apple.fetch.items (documents fetched)
    • apple.fetch.failures
    • apple.fetch.unchanged
    • apple.index.rows_dropped with reasons such as no_published_cve, no_link, bad_date, invalid_detail_uri, duplicate_article, trust_filter, and old_by_window
    • apple.index.unsupported_shapes with shapes such as gdmf_release_metadata_json, html_list_shape, or html_unexpected_table_shape
    • apple.parse.failures
    • apple.map.affected.count (histogram of affected package counts)
  4. Cross-check the shared HTTP counters:
    • concelier.source.http.requests_total{concelier_source="vndr-apple"} should increase for both index and detail phases.
    • concelier.source.http.failures_total{concelier_source="vndr-apple"} should remain flat (0) during a healthy run.
  5. Inspect the info logs:
    • Apple index loop ... rowsSeen=X indexEntries=Y keptAfterFilters=Z selected=N droppedNoPublishedCve=D droppedOldByWindow=W
    • Apple advisory parse complete ... aliases=... affected=...
    • Mapped Apple advisory ... pendingMappings=0
  6. Confirm PostgreSQL state (schema vuln):
    • raw_documents table contains the HT article HTML with metadata (apple.articleId, apple.postingDate).
    • dtos table has schemaVersion="apple.security.update.v1".
    • advisories table includes keys HTxxxxxx with normalized SemVer rules.
    • source_states entry for apple shows a recent cursor.lastPosted.

3. Production Monitoring

4. Fixture Maintenance

Regression fixtures live under src/Concelier/__Tests/StellaOps.Concelier.Connector.Vndr.Apple.Tests/Apple/Fixtures. Refresh them whenever Apple reshapes the HT layout or when new platforms appear.

  1. Run the helper script matching your platform:
    • Bash: ./scripts/update-apple-fixtures.sh
    • PowerShell: ./scripts/update-apple-fixtures.ps1
  2. Each script exports UPDATE_APPLE_FIXTURES=1, updates the WSLENV passthrough, and touches .update-apple-fixtures so WSL+VS Code test runs observe the flag. The subsequent test execution fetches the live HT articles listed in AppleFixtureManager, sanitises the HTML, and rewrites the .expected.json DTO snapshots.
  3. Review the diff for localisation or nav noise. Once satisfied, re-run the tests without the env var (dotnet test src/Concelier/__Tests/StellaOps.Concelier.Connector.Vndr.Apple.Tests/StellaOps.Concelier.Connector.Vndr.Apple.Tests.csproj) to verify determinism.
  4. Commit fixture updates together with any parser/mapping changes that motivated them.

5. Known Issues & Follow-up Tasks