id: duo
name: Cisco Duo
version: 1.0.0
description: "Cisco Duo (Admin API) — MFA/identity containment and investigation: list and read users, disable/enable/bypass a user (containment), delete users, read bypass codes and devices, and pull authentication logs. HMAC-SHA1 signed authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: get users/user, modify user status (disable/enable/bypass), delete user, get bypass codes, get devices, get user devices, authentication logs."
category: identity

# Per-instance configuration. Requests are signed (HMAC-SHA1) with the
# integration key + secret key against the Admin API hostname.
config_schema:
  properties:
    api_hostname:
      type: string
      description: "Duo Admin API hostname (e.g. api-xxxxxxxx.duosecurity.com)"
    integration_key:
      type: string
      description: "Admin API integration key (ikey)"
      x-soar-sensitive: true
    secret_key:
      type: string
      description: "Admin API secret key (skey)"
      x-soar-sensitive: true
  required:
    - api_hostname
    - integration_key
    - secret_key

commands:
  - id: get_users
    name: duo-get-users
    description: "List users (optionally filter by exact username)."
    risk: read
    inputs_schema:
      properties:
        username: { type: string, description: "Optional exact username to look up" }
        limit: { type: number, description: "Max users (default 100)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_user
    name: duo-get-user
    description: "Get a single user by user ID."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "Duo user ID" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: modify_user
    name: duo-modify-user
    description: "Change a user's status — disable (containment), enable (active), or bypass."
    inputs_schema:
      properties:
        user_id: { type: string, description: "Duo user ID" }
        status: { type: string, description: "active | disabled | bypass" }
      required: [user_id, status]
    outputs_schema: { properties: {} }
  - id: delete_user
    name: duo-delete-user
    description: "Delete a user."
    inputs_schema:
      properties:
        user_id: { type: string, description: "Duo user ID" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: get_bypass_codes
    name: duo-get-bypass-codes
    description: "List a user's bypass codes."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "Duo user ID" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: get_devices
    name: duo-get-devices
    description: "List all phones/devices in the account."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Max devices (default 100)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_user_devices
    name: duo-get-user-devices
    description: "List the phones/devices associated with a user."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "Duo user ID" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: get_authentication_logs
    name: duo-get-authentication-logs
    description: "Pull authentication logs for a time window."
    risk: read
    inputs_schema:
      properties:
        mintime: { type: number, description: "Start time as Unix epoch milliseconds (required by Duo v2 logs)" }
        maxtime: { type: number, description: "End time as Unix epoch milliseconds" }
        limit: { type: number, description: "Max events (default 100, max 1000)" }
      required: [mintime, maxtime]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: duo-test-connection
    description: "Verify connectivity and the signed credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }