git.stella-ops.org/docs/ops/concelier-cisco-operations.md

# Concelier Cisco PSIRT Connector – OAuth Provisioning SOP

_Last updated: 2025-10-14_

## 1. Scope

This runbook describes how Ops provisions, rotates, and distributes Cisco PSIRT openVuln OAuth client credentials for the Concelier Cisco connector. It covers online and air-gapped (Offline Kit) environments, quota-aware execution, and escalation paths.

## 2. Prerequisites

- Active Cisco.com (CCO) account with access to the Cisco API Console.
- Cisco PSIRT openVuln API entitlement (visible under “My Apps & Keys” once granted).citeturn3search0
- Concelier configuration location (typically `/etc/stella/concelier.yaml` in production) or Offline Kit secret bundle staging directory.

## 3. Provisioning workflow

1. **Register the application**
   - Sign in at <https://apiconsole.cisco.com>.
   - Select **Register a New App** → Application Type: `Service`, Grant Type: `Client Credentials`, API: `Cisco PSIRT openVuln API`.citeturn3search0
   - Record the generated `clientId` and `clientSecret` in the Ops vault.
2. **Verify token issuance**
   - Request an access token with:
     ```bash
     curl -s https://id.cisco.com/oauth2/default/v1/token \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d "grant_type=client_credentials" \
       -d "client_id=${CLIENT_ID}" \
       -d "client_secret=${CLIENT_SECRET}"
     ```
   - Confirm HTTP 200 and an `expires_in` value of 3600 seconds (tokens live for one hour).citeturn3search0turn3search7
   - Preserve the response only long enough to validate syntax; do **not** persist tokens.
3. **Authorize Concelier runtime**
   - Update `concelier:sources:cisco:auth` (or the module-specific secret template) with the stored credentials.
   - For Offline Kit delivery, export encrypted secrets into `offline-kit/secrets/cisco-openvuln.json` using the platform’s sealed secret format.
4. **Connectivity validation**
   - From the Concelier control plane, run `stella db jobs run source:vndr-cisco:fetch --dry-run`.
   - Ensure the Source HTTP diagnostics record `Bearer` authorization headers and no 401/403 responses.

## 4. Rotation SOP

| Step | Owner | Notes |
| --- | --- | --- |
| 1. Schedule rotation | Ops (monthly board) | Rotate every 90 days or immediately after suspected credential exposure. |
| 2. Create replacement app | Ops | Repeat §3.1 with “-next” suffix; verify token issuance. |
| 3. Stage dual credentials | Ops + Concelier On-Call | Publish new credentials to secret store alongside current pair. |
| 4. Cut over | Concelier On-Call | Restart connector workers during a low-traffic window (<10 min) to pick up the new secret. |
| 5. Deactivate legacy app | Ops | Delete prior app in Cisco API Console once telemetry confirms successful fetch/parse cycles for 2 consecutive hours. |

**Automation hooks**
- Rotation reminders are tracked in OpsRunbookOps board (`OPS-RUN-KEYS` swim lane); add checklist items for Concelier Cisco when opening a rotation task.
- Use the secret management pipeline (`ops/secrets/rotate.sh --connector cisco`) to template vault updates; the script renders a redacted diff for audit.

## 5. Offline Kit packaging

1. Generate the credential bundle using the Offline Kit CLI:  
   `offline-kit secrets add cisco-openvuln --client-id … --client-secret …`
2. Store the encrypted payload under `offline-kit/secrets/cisco-openvuln.enc`.
3. Distribute via the Offline Kit channel; update `offline-kit/MANIFEST.md` with the credential fingerprint (SHA256 of plaintext concatenated with metadata).
4. Document validation steps for the receiving site (token request from an air-gapped relay or cached token mirror).

## 6. Quota and throttling guidance

- Cisco enforces combined limits of 5 requests/second, 30 requests/minute, and 5 000 requests/day per application.citeturn0search0turn3search6
- Concelier fetch jobs must respect `Retry-After` headers on HTTP 429 responses; Ops should monitor for sustained quota saturation and consider paging window adjustments.
- Telemetry to watch: `concelier.source.http.requests{concelier.source="vndr-cisco"}`, `concelier.source.http.failures{...}`, and connector-specific metrics once implemented.

## 7. Telemetry & Monitoring

- **Metrics (Meter `StellaOps.Concelier.Connector.Vndr.Cisco`)**
  - `cisco.fetch.documents`, `cisco.fetch.failures`, `cisco.fetch.unchanged`
  - `cisco.parse.success`, `cisco.parse.failures`
  - `cisco.map.success`, `cisco.map.failures`, `cisco.map.affected.packages`
- **Shared HTTP metrics** via `SourceDiagnostics`:
  - `concelier.source.http.requests{concelier.source="vndr-cisco"}`
  - `concelier.source.http.failures{concelier.source="vndr-cisco"}`
  - `concelier.source.http.duration{concelier.source="vndr-cisco"}`
- **Structured logs**
  - `Cisco fetch completed date=… pages=… added=…` (info)
  - `Cisco parse completed parsed=… failures=…` (info)
  - `Cisco map completed mapped=… failures=…` (info)
  - Warnings surface when DTO serialization fails or GridFS payload is missing.
- Suggested alerts: non-zero `cisco.fetch.failures` in 15m, or `cisco.map.success` flatlines while fetch continues.

## 8. Incident response

- **Token compromise** – revoke the application in the Cisco API Console, purge cached secrets, rotate immediately per §4.
- **Persistent 401/403** – confirm credentials in vault, then validate token issuance; if unresolved, open a Cisco DevNet support ticket referencing the application ID.
- **429 spikes** – inspect job scheduler cadence and adjust connector options (`maxRequestsPerWindow`) before requesting higher quotas from Cisco.

## 9. References

- Cisco PSIRT openVuln API Authentication Guide.citeturn3search0
- Accessing the openVuln API using curl (token lifetime).citeturn3search7
- openVuln API rate limit documentation.citeturn0search0turn3search6