Files

master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules

- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.

2025-10-30 00:09:39 +02:00

3.4 KiB

Raw Blame History

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

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 src/Tools/SourceStateSeeder to queue historical advisories (detail JSON + optional CVRF artefacts) for replay without manual Mongo edits. Example seed file:

{
  "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:

dotnet run --project src/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.

3.4 KiB Raw Blame History Unescape Escape