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 (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.