git.stella-ops.org/docs/ops/connector-setup-guide.md

# Connector Setup Guide — Concelier + Excititor

Companion to the UI-driven setup work on 2026-04-22. This guide lists every advisory/VEX connector available in the codebase, whether it needs credentials, and — for the credentialed ones — **exact steps for the operator to create the credentials at the provider's site**. An agent cannot create real accounts on your behalf; you must do these steps yourself with your own accounts, then hand the tokens back so the UI/CLI persists them.

## Scope

- Concelier advisory sources (from `src/Concelier/__Libraries/StellaOps.Concelier.Connector.*`)
- Excititor VEX providers (from `src/Concelier/__Libraries/StellaOps.Excititor.Connectors.*`)
- Already registered in DB on 2026-04-22: Concelier `{auscert, redhat, stella-mirror}`, Excititor `{excititor:redhat, excititor:ubuntu, excititor:cisco, excititor:oracle}`

## Credential requirements at a glance

| Connector | Needs creds? | What you need to create |
|---|---|---|
| **Concelier/GHSA** | YES | GitHub Personal Access Token (classic) with `read:packages` + `read:public_repo` |
| **Concelier/Vndr.Cisco** | YES | Cisco PSIRT openVuln `client_id` + `client_secret` |
| **Concelier/Vndr.Msrc** | YES | Microsoft Entra app `tenant_id` + `client_id` + `client_secret` |
| **Excititor/Cisco.CSAF** | YES | same Cisco PSIRT OAuth creds (can reuse) |
| **Excititor/MSRC.CSAF** | YES | same Microsoft Entra creds (can reuse) |
| All other Concelier connectors | NO | public endpoints |
| All other Excititor connectors | NO | public CSAF / OpenVEX endpoints |

## Step-by-step — credentialed providers

### 1. GitHub Security Advisories (GHSA)

**What Stella Ops needs**: a GitHub Personal Access Token (classic) to query the GraphQL security-advisories API at scale.

**Steps**:
1. Open <https://github.com/settings/tokens> (must be logged into your GitHub account).
2. Click **Generate new token** → **Generate new token (classic)**.
3. Name it something like `stella-ops-concelier-ghsa` (note: tokens are per-user, not per-organisation; use a service account if the project has one).
4. Set expiration per your org's policy (**90 days minimum recommended**).
5. Scopes required:
   - `read:packages`
   - `public_repo` (or `read:public_repo` if you have that fine-grained scope available)
6. Click **Generate token** and copy the `ghp_...` string immediately — GitHub won't show it again.
7. If your GitHub org requires SAML SSO, authorize the token for that org: on the token list page, click **Configure SSO** next to the new token → **Authorize** per org.

**Where to paste in Stella Ops**:
- UI: `/setup/integrations` → advisory sources → GHSA → paste token in the PAT field.
- CLI: `stellaops-cli db connectors configure ghsa --credential token=<ghp_...>`

### 2. Cisco PSIRT openVuln (Concelier/Vndr.Cisco + Excititor/Cisco.CSAF)

**What Stella Ops needs**: a Cisco PSIRT openVuln OAuth 2.0 client (grant_type=client_credentials). Cisco mints these through their developer portal app registration flow.

**Steps**:
1. Open <https://apiconsole.cisco.com/apps/myapps> (Cisco developer portal; create/sign into a free Cisco developer account if you don't have one).
2. Click **Register a New App** (or **My Apps & Keys** → **Register a New App**).
3. App details:
   - Name: `stella-ops-concelier-psirt`
   - OAuth2 Credentials: tick **Client Credentials** grant.
   - APIs to grant: **openVuln API**.
4. Submit. Cisco will show the new app's `client_id` and `client_secret` on the detail page.
5. Copy both strings.

Cisco ref: <https://developer.cisco.com/docs/psirt/authentication/>

**Where to paste in Stella Ops**:
- UI: `/setup/integrations` → advisory sources → Cisco → paste `clientId` + `clientSecret`. The same credentials are reused by the Excititor Cisco VEX provider.
- CLI: `stellaops-cli db connectors configure cisco --credential clientId=<id> --credential clientSecret=<secret>`

### 3. Microsoft MSRC + Microsoft VEX (Concelier/Vndr.Msrc + Excititor/MSRC.CSAF)

**What Stella Ops needs**: a Microsoft Entra (Azure AD) confidential client app with API permission to the MSRC Security Updates API.

**Steps**:
1. Open <https://entra.microsoft.com/> → **App registrations** (must be signed into an Entra tenant; the tenant can be your org or a personal/developer tenant).
2. Click **New registration**.
3. Name: `stella-ops-concelier-msrc`. Supported account types: **Accounts in this organizational directory only** (single tenant). Redirect URI: leave blank.
4. After registration, copy from the Overview page:
   - **Directory (tenant) ID** — GUID like `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`
   - **Application (client) ID** — another GUID
5. Go to **Certificates & secrets** → **New client secret**:
   - Description: `stella-ops-concelier-msrc`
   - Expiry: 24 months (or per policy)
   - Click **Add** and **immediately copy the `Value` column** — it's hidden after you leave the page.
6. Go to **API permissions** → **Add a permission** → **Microsoft APIs** → **Security Updates API** (you may need to type the name; if not visible, enter its Application ID `83b40db2-0d04-4b56-9e77-0e7d76a47d4b` via **APIs my organization uses**).
7. Select **Application permissions** → tick `SecurityUpdates.Read.All` → **Add permissions**.
8. Click **Grant admin consent for <tenant>** (requires admin; if you're not admin, have one click this).

Microsoft refs: <https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>, <https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials>.

**Where to paste in Stella Ops**:
- UI: `/setup/integrations` → advisory sources → MSRC → `tenantId`, `clientId`, `clientSecret`.
- CLI: `stellaops-cli db connectors configure msrc --credential tenantId=<guid> --credential clientId=<guid> --credential clientSecret=<value>`

## Unauthenticated connectors — no credentials needed

Just enable them via UI `/setup/integrations` → advisory sources (or Excititor providers) → **Add**:

### Concelier advisory sources
- ACSC, CCCS, CERT-BUND, CERT/CC, CERT-FR, CERT-IN, ICS-CISA, ICS-Kaspersky
- CVE (MITRE), EPSS, KEV, JVN, KISA, NVD (API-key-optional), OSV
- Distro: Alpine, Debian, Red Hat, SUSE, Ubuntu
- Vendor: Adobe, Apple, Chromium, Oracle, VMware
- Regional: RU.BDU (FSTEC), RU.NKCKI

### Excititor VEX providers
- Oracle.CSAF, RedHat.CSAF, Ubuntu.CSAF, SUSE.RancherVEXHub, OCI.OpenVEX.Attest

## Retained-secret contract (important)

Stella Ops never echoes secrets back to callers once they're persisted. The UI will show something like `••••set••••` or a "secret retained" badge for persisted credentials. Updating an unrelated field on a credentialed source does NOT require re-entering the secret; the server detects "no change" and preserves the stored value.

Only provide a new secret when you're **rotating** it. Provide empty string `""` if you want to explicitly **clear** it (which will put the source into `readiness=blocked` state).

## After you have the credentials

Hand them back in this turn of the conversation (in a secure channel — these are tokens) and I'll drive the UI to persist them for you. Or paste them yourself through the `/setup/integrations` page. Either way.