git.stella-ops.org/docs/modules/concelier/operations/source-credentials.md

# Advisory Source Credential Entry

_Last updated: 2026-04-22_

## 1. Purpose

Stella Ops now supports operator-supplied advisory source settings through the product surfaces that operators already use:

- Web UI source management
- `stella db connectors configure ...` in the CLI

Environment variables and host-local `concelier.yaml` values remain compatibility fallbacks for older deployments, but the primary operator path for supported advisory sources is now persisted source configuration owned by Concelier itself.

## 2. Operator entry paths

### Web UI

Use either of these routes:

- **Security Posture -> Configure Sources**
- **Ops -> Operations -> Feeds & Airgap -> Configure Sources**

Then:

1. Expand the source card.
2. Open **Stored Connector Configuration**.
3. Enter or update the source fields.
4. Save the configuration.

Sensitive fields never round-trip back to the browser. A stored secret is shown only as retained state. Leaving a password field blank keeps the retained secret. Explicitly checking the clear control removes the stored secret.

### Blocked or sleeping sources

If an operator enables a source that still lacks required credentials or required URIs, Concelier now preserves the enable intent but marks the source as `blocked` instead of pretending it is runnable.

- `enabled=true` means the operator wants the source scheduled once it becomes usable.
- `syncState=blocked` means the source is intentionally on hold because required configuration is still missing.
- Manual or batch sync attempts will report that the source is blocked and will echo the missing-configuration reason, typically `SOURCE_CONFIG_REQUIRED`.

This is the expected state for credential-gated sources that have been selected before the upstream token or client-secret values are available.

### CLI

Inspect current persisted source configuration:

```bash
stella db connectors configure ghsa --server https://concelier.example.internal
stella db connectors configure cisco --server https://concelier.example.internal
```

Update a source:

```bash
stella db connectors configure ghsa \
  --server https://concelier.example.internal \
  --set apiToken=github_pat_xxx

stella db connectors configure cisco \
  --server https://concelier.example.internal \
  --set clientId=... \
  --set clientSecret=...

stella db connectors configure microsoft \
  --server https://concelier.example.internal \
  --set tenantId=... \
  --set clientId=... \
  --set clientSecret=...

stella db connectors configure oracle \
  --server https://concelier.example.internal \
  --set calendarUris=https://www.oracle.com/security-alerts/,https://mirror.example.internal/oracle/

stella db connectors configure adobe \
  --server https://concelier.example.internal \
  --set indexUri=https://mirror.example.internal/adobe/security-bulletin.html \
  --set additionalIndexUris=https://mirror.example.internal/adobe/archive-1.html;https://mirror.example.internal/adobe/archive-2.html

stella db connectors configure chromium \
  --server https://concelier.example.internal \
  --set feedUri=https://mirror.example.internal/chromium/atom.xml
```

Clear stored fields:

```bash
stella db connectors configure ghsa \
  --server https://concelier.example.internal \
  --clear apiToken
```

Notes:

- `--set` accepts `key=value`.
- Multi-value URI fields such as `calendarUris`, `advisoryUris`, and `additionalIndexUris` accept comma-, semicolon-, or newline-separated absolute URIs.
- The current CLI path places literal values on the command line. If shell-history exposure is unacceptable for a secret, prefer the Web UI path or use an operator-approved secure shell/history procedure.

## 3. Credential acquisition matrix

| Source | Where to sign in or look | What to create or capture | Can the config be skipped? | Entitlement / paywall notes |
| --- | --- | --- | --- | --- |
| `ghsa` | `https://github.com/settings/personal-access-tokens` or a GitHub App owned by your org | `apiToken` | Not for the current StellaOps GHSA connector path. The upstream API can expose public reviewed advisories anonymously, but the current StellaOps connector still expects a token. | No separate GHSA paywall. GitHub org PAT policy or SAML SSO may require approval or token authorization. |
| `cisco` | `https://apiconsole.cisco.com` -> **My Apps & Keys** | `clientId`, `clientSecret` for a Service / Client Credentials app bound to Cisco PSIRT openVuln API | Not for the authenticated Concelier Cisco advisory connector. | No separate StellaOps-side fee, but a Cisco.com account, terms acceptance, and visible openVuln entitlement are required. This is separate from the public Cisco CSAF VEX bootstrap, which stays credential-free. |
| `microsoft` | `https://entra.microsoft.com` -> **App registrations** | `tenantId`, `clientId`, `clientSecret` for a confidential client allowed to use MSRC client credentials | Not for the MSRC advisory connector. | No separate documented MSRC paywall, but you need a Microsoft Entra tenant plus permission to register the app and grant the required consent. |
| `oracle` | Public Oracle security pages | Usually nothing. Optionally capture mirrored `calendarUris` or pinned `advisoryUris`. | Yes, if the default Oracle security alerts landing page is acceptable. Configure it only when pinning or mirroring. | Public, no login or paywall required for the default path. |
| `adobe` | Public Adobe bulletin index | Usually nothing. Optionally capture a mirrored `indexUri` and `additionalIndexUris`. | Yes, for the default public Adobe index. Configure it only when overriding or mirroring the public endpoints. | Public, no login or paywall required for the default path. |
| `chromium` | Public Chrome Releases Atom feed | Usually nothing. Optionally capture a mirrored `feedUri`. | Yes, for the default public Chromium feed. Configure it only when overriding or mirroring the public endpoint. | Public, no login or paywall required for the default path. |

## 4. What operators should actually look for

### GHSA

- Personal access token page or org-owned GitHub App credentials
- If the organization enforces SAML SSO or PAT approval, make sure the token is authorized for the target org after creation
- The StellaOps field name is `apiToken`

### Cisco

- Cisco API Console entry for **Cisco PSIRT openVuln API**
- Application type: `Service`
- Grant type: `Client Credentials`
- Capture the generated `clientId` and `clientSecret`

### Microsoft / MSRC

- Microsoft Entra **Application (client) ID**
- Microsoft Entra **Directory (tenant) ID**
- A newly created **Client secret** value
- Confirm admin consent and the app permissions expected by your MSRC onboarding process before storing the values in StellaOps

### Oracle / Adobe / Chromium

- No credential creation is required
- Only collect alternate URIs if you are pointing Concelier at an approved internal mirror or pinning a specific public advisory page

## 5. References

- GitHub PAT management: <https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>
- GitHub global security advisories REST API: <https://docs.github.com/en/enterprise-cloud@latest/rest/security-advisories/global-advisories>
- GitHub SSO authorization for PATs: <https://docs.github.com/articles/authorizing-a-personal-access-token-for-use-with-a-saml-single-sign-on-organization>
- Cisco PSIRT openVuln authentication: <https://developer.cisco.com/docs/psirt/authentication/>
- Microsoft Entra app registration quickstart: <https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>
- Microsoft Entra application credentials: <https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials>
- Adobe bulletin index: <https://helpx.adobe.com/security/security-bulletin.html>
- Oracle security alerts: <https://www.oracle.com/security-alerts/>
- Chrome Releases Atom feed: <https://chromereleases.googleblog.com/atom.xml>