87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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.
|