Resolve Concelier/Excititor merge conflicts

2025-10-20 14:19:25 +03:00
parent 67d581d2e8 5fd4032c7c
commit 09b6a28172
2687 changed files with 212646 additions and 85913 deletions
--- a/docs/ops/concelier-msrc-operations.md
+++ b/docs/ops/concelier-msrc-operations.md
@@ -0,0 +1,86 @@
+# Concelier MSRC Connector – Azure AD Onboarding Brief
+
+_Drafted: 2025-10-15_
+
+## 1. App registration requirements
+
+- **Tenant**: shared StellaOps production Azure AD.
+- **Application type**: confidential client (web/API) issuing client credentials.
+- **API permissions**: `api://api.msrc.microsoft.com/.default` (Application). Admin consent required once.
+- **Token audience**: `https://api.msrc.microsoft.com/`.
+- **Grant type**: client credentials. Concelier will request tokens via `POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`.
+
+## 2. Secret/credential policy
+
+- Maintain two client secrets (primary + standby) rotating every 90 days.
+- Store secrets in the Concelier secrets vault; Offline Kit deployments must mirror the secret payloads in their encrypted store.
+- Record rotation cadence in Ops runbook and update Concelier configuration (`CONCELIER__SOURCES__VNDR__MSRC__CLIENTSECRET`) ahead of expiry.
+
+## 3. Concelier configuration sample
+
+```yaml
+concelier:
+  sources:
+    vndr.msrc:
+      tenantId: "<azure-tenant-guid>"
+      clientId: "<app-registration-client-id>"
+      clientSecret: "<pull from secret store>"
+      apiVersion: "2024-08-01"
+      locale: "en-US"
+      requestDelay: "00:00:00.250"
+      failureBackoff: "00:05:00"
+      cursorOverlapMinutes: 10
+      downloadCvrf: false  # set true to persist CVRF ZIP alongside JSON detail
+```
+
+## 4. CVRF artefacts
+
+- The MSRC REST payload exposes `cvrfUrl` per advisory. Current connector persists the link as advisory metadata and reference; it does **not** download the ZIP by default.
+- Ops should mirror CVRF ZIPs when preparing Offline Kits so air-gapped deployments can reconcile advisories without direct internet access.
+- Once Offline Kit storage guidelines are finalised, extend the connector configuration with `downloadCvrf: true` to enable automatic attachment retrieval.
+
+### 4.1 State seeding helper
+
+Use `tools/SourceStateSeeder` to queue historical advisories (detail JSON + optional CVRF artefacts) for replay without manual Mongo edits. Example seed file:
+
+```json
+{
+  "source": "vndr.msrc",
+  "cursor": {
+    "lastModifiedCursor": "2024-01-01T00:00:00Z"
+  },
+  "documents": [
+    {
+      "uri": "https://api.msrc.microsoft.com/sug/v2.0/vulnerability/ADV2024-0001",
+      "contentFile": "./seeds/adv2024-0001.json",
+      "contentType": "application/json",
+      "metadata": { "msrc.vulnerabilityId": "ADV2024-0001" },
+      "addToPendingDocuments": true
+    },
+    {
+      "uri": "https://download.microsoft.com/msrc/2024/ADV2024-0001.cvrf.zip",
+      "contentFile": "./seeds/adv2024-0001.cvrf.zip",
+      "contentType": "application/zip",
+      "status": "mapped",
+      "addToPendingDocuments": false
+    }
+  ]
+}
+```
+
+Run the helper:
+
+```bash
+dotnet run --project tools/SourceStateSeeder -- \
+  --connection-string "mongodb://localhost:27017" \
+  --database concelier \
+  --input seeds/msrc-backfill.json
+```
+
+Any documents marked `addToPendingDocuments` will appear in the connector cursor; `DownloadCvrf` can remain disabled if the ZIP artefact is pre-seeded.
+
+## 5. Outstanding items
+
+- Ops to confirm tenant/app names and provide client credentials through the secure channel.
+- Connector team monitors token cache health (already implemented); validate instrumentation once Ops supplies credentials.
+- Offline Kit packaging: add encrypted blob containing client credentials with rotation instructions.