git.stella-ops.org/docs/modules/concelier/operations/connectors/cisco.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:

     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