Cisco Duo

The Cisco Duo Logs Collector utilizes a pull-based mechanism that provides a robust framework for collecting security and administrative logs from Cisco Duo's Admin API.

Purpose

The purpose of the Cisco Duo Logs Collector is to enable the platform to actively retrieve authentication, administrator, and telephony logs from Cisco Duo by polling the Duo Admin API endpoints at configured intervals. It pulls security event data in JSON format from Cisco Duo into Observo AI for analysis and processing. This integration supports streamlined security monitoring, user authentication analytics, and compliance reporting, allowing organizations to enhance observability and security posture by proactively fetching logs from their Duo deployment.

The collector interacts with the following Cisco Duo Admin API endpoints:

• Authentication Logs API (/admin/v2/logs/authentication): Retrieves authentication attempt logs including successful and failed login attempts

• Administrator Logs API (/admin/v1/logs/administrator): Retrieves administrative action logs performed by Duo administrators

• Telephony Logs API (/admin/v2/logs/telephony): Retrieves telephony logs related to phone calls and SMS messages sent by Duo

Prerequisites

Before configuring the Cisco Duo Logs Collector source in Observo AI, ensure the following requirements are met to facilitate seamless data ingestion:

• Cisco Duo Admin API Application:

  • An active Duo Admin API application must be created in your Duo Admin Panel.

  • Obtain the Integration Key, Secret Key, and API Hostname from your Duo Admin API application.

• API Permissions:

  • The Duo Admin API application must have the "Grant read log" permission enabled.

  • This permission is mandatory for accessing authentication, administrator, and telephony logs.

• Network and Connectivity:

  • Ensure Observo AI can communicate with your Duo API endpoint (e.g., https://api-XXXXXXXX.duosecurity.com).

  • Check for proxy settings, firewall rules, or network configurations that may affect connectivity to the Duo API.

Prerequisite	Description	Notes
Duo Admin API App	Active API application in Duo Admin Panel	Obtain Integration Key, Secret Key, and API Hostname
API Permissions	"Grant read log" permission required	Mandatory for all log types; 403 errors occur without this
Network	Connectivity to Duo API endpoint	Check firewalls and network policies

Data Types Collected

The collector retrieves three distinct types of logs from Cisco Duo:

Authentication Logs

Contains information about user authentication attempts including:

• User identification and device information

• Authentication method used (push, SMS, phone call, hardware token, etc.)

• Authentication result (success, failure, fraud)

• IP address and geolocation data

• Timestamp of authentication event (in milliseconds)

• Application being accessed

• Access device details

Administrator Logs

Contains audit trail of administrative actions including:

• Administrator username and identification

• Action performed (user creation, policy changes, settings modifications)

• Timestamp of administrative action (in seconds)

• Description of changes made

• Affected resources or users

Telephony Logs

Contains details about phone-based authentication events including:

• Phone number used

• Call or SMS details

• Telephony event type (SMS, phone call)

• Credits used for the telephony event

• Timestamp of telephony event (in milliseconds)

• Call duration and status

Integration

The Integration section outlines the configurations for the Cisco Duo Logs Collector source. Please follow these steps to set up and test the data flow:

1. Log in to Observo AI:

• Navigate to the Sources tab.

• Click the Add Source button and select Create New.

• Choose Cisco Duo Logs Collector from the list of available sources to begin configuration.

1. General Settings:

• Name: A unique identifier for the source, such as cisco-duo-logs.

• Description: (Optional): Provide a description for the source, such as "Cisco Duo authentication and admin logs".

• Config: Configuration parameters for the Cisco Duo API.

  Key (Required)	Value	Description
  DUO_API_HOST	https://api-XXXXXXXX.duosecurity.com	Your Duo API hostname (include https://)
  DUO_INTEGRATION_KEY	<YOUR_INTEGRATION_KEY>	Integration Key from Duo Admin API application
  DUO_SECRET_KEY	<YOUR_SECRET_KEY>	Secret Key from Duo Admin API application

• Checkpoints: Seed checkpoints to define the starting point for log collection. This prevents duplicate log ingestion.

  Key (Default)	Value (Default)	Description
  ADMIN_SINCE_TIME	1661022959	Unix timestamp in seconds for administrator logs starting point
  AUTH_SINCE_TIME	1661022959934	Unix timestamp in milliseconds for authentication logs starting point
  TELEPHONY_SINCE_TIME	1661022959934	Unix timestamp in milliseconds for telephony logs starting point

  Important: Note the different timestamp formats:

  • Authentication and Telephony logs use milliseconds (13 digits)

  • Administrator logs use seconds (10 digits)

• Time in seconds to pause between script executions:

  • Default: 300 seconds (5 minutes)

Initial Setup:

• Set seed checkpoints to an appropriate starting point (don't collect years of historical data initially)

• Enable one log type at a time to validate configuration

• Test with a longer interval (e.g., 600 seconds) during initial setup

• Verify the Grant read log permission is enabled in your Duo Admin API application

Troubleshooting

Problem	Solution
403 Forbidden errors	Verify that "Grant read log" permission is enabled in your Duo Admin API application
401 Authentication errors	Double-check your Integration Key and Secret Key. Ensure there are no extra spaces or characters in the Config
No logs being collected	Check that the log type function is uncommented in the script. Ensure the time range has actual log data
Rate limit errors (429)	Increase the trigger interval to reduce API call frequency (e.g., from 300 to 600 seconds)
Missing recent logs	Verify system time is accurate. Check that maxtime parameter is set correctly. Ensure checkpoints are not ahead of current time
Timestamp format errors	Ensure AUTH_SINCE_TIME and TELEPHONY_SINCE_TIME use milliseconds (13 digits), while ADMIN_SINCE_TIME uses seconds (10 digits)