up

docs/ops/feedser-cisco-operations.md

@@ -0,0 +1,94 @@
+# Feedser 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 Feedser 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
+- Feedser configuration location (typically `/etc/stella/feedser.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 Feedser runtime**
+   - Update `feedser: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 Feedser 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 + Feedser On-Call | Publish new credentials to secret store alongside current pair. |
+| 4. Cut over | Feedser 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 Feedser 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
+- Feedser 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: `feedser.source.http.requests{feedser.source="vndr-cisco"}`, `feedser.source.http.failures{...}`, and connector-specific metrics once implemented.
+
+## 7. Telemetry & Monitoring
+
+- **Metrics (Meter `StellaOps.Feedser.Source.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`:
+  - `feedser.source.http.requests{feedser.source="vndr-cisco"}`
+  - `feedser.source.http.failures{feedser.source="vndr-cisco"}`
+  - `feedser.source.http.duration{feedser.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