Send Cisco Duo logs to LogPulse

Duo authentication and administrator logs from the Admin API: every MFA prompt with its result, factor, device and location, and every admin change.

In short
To send Cisco Duo logs to LogPulse, add Cisco Duo under Configure → Sources → Cloud. LogPulse reads the Duo Admin API itself, without an agent. Events land in the iam index with source duo and fill the Authentication, Change data models.

Overview

How Cisco Duo data reaches LogPulse
Vendor
Duo Admin API
Collect
Integration pollerreads new events, maps the fields
Store
index=iam
  1. Duo Admin API to Integration poller
  2. Integration poller to index=iam

LogPulse signs in to Cisco Duo with the credential you give it and fetches new events every five minutes by default. You can set the interval per integration, from one minute to 24 hours.

What you need

  • A Duo Admin API application with the "Grant read log" permission
  • In LogPulse: a role that may manage API keys. Cloud integrations fall under that right.

1. Create a credential in Cisco Duo

Field in LogPulseWhere you find it
API hostnameIn the Duo Admin Panel: Applications, Protect an Application, Admin API. The hostname (api-xxxxxxxx.duosecurity.com) is on that page.
Integration keyOn the same page.
Secret keyGive the Admin API application only the permission "Grant read log". Stored encrypted and never shown again.

2. Add the integration in LogPulse

Go to Configure → Sources → Cloud and choose Cisco Duo. Fill in the fields, tick the data sources you want and save. LogPulse first tests the connection with your credential and tells you what is wrong when it fails.

Tip: Secrets are stored encrypted and never shown again. To change one, paste a new value; the rest stays.

What arrives

Data sourceIndexSourceSourcetypeWhat it holds
Authentication logiamduoduo:authenticationEach Duo authentication: user, application, factor, result and reason, the access device and its location.
Administrator logiamduoduo:administratorAdmin actions in the Duo Admin Panel: users, policies, integrations and bypass codes.

The index is the kind of data and the source is the product, so detection rules for that kind of data find Cisco Duo without changes.

Note: Duo writes authentication logs up to two minutes late, so LogPulse reads up to two minutes behind and never misses one.
Note: Fraud reports (a user pressed "this was not me") arrive as a threat.

Fields and data models

Data modelWhat you get
AuthenticationMFA prompts with user, application, factor, result, src_ip and country.
ChangeAdmin changes with admin, action and object.

Field names follow the CIM field names. These are the fields LogPulse sets on Cisco Duo events; a field is left out when Cisco Duo did not send a value.

  • action
  • app
  • auth_device
  • auth_type
  • authentication_method
  • description
  • dest
  • http_user_agent
  • id
  • object
  • object_category
  • os
  • reason
  • signature
  • src
  • src_city
  • src_country
  • src_ip
  • status
  • threat_suspected
  • user
  • user_email
  • user_id
  • vendor_action

The original record of Cisco Duo is kept with each event under raw, so nothing the vendor sent is lost.

3. Check the data

The first events arrive within a few minutes. Check what came in:

earliest=-1h index IN (iam) source IN (duo)
| stats count by index, source, sourcetype

The integration page in LogPulse shows when it last read events and the last error, if any.

Troubleshooting

The connection test names what is wrong. These are the answers you are most likely to see.

What you seeWhat to do
Duo refused the integration key or secret key.Copy both keys again from the Admin API application in the Duo Admin Panel, and check that the API hostname belongs to the same account.
The Admin API application needs the "Grant read log" permission.Open the Admin API application in Duo, tick Grant read log and save. No other permission is needed.
apiHost is the API hostname of your Duo account, e.g. api-1a2b3c4d.duosecurity.comUse the API hostname from the Admin API page, not the address of the Admin Panel.
The test passes but no events arrive.Run the search above over a longer time. No results: check on the integration page that the data source is switched on and when it last read events. Cisco Duo may also simply have had nothing new.

Frequently asked questions

How do I send Cisco Duo logs to LogPulse?
Add the Cisco Duo cloud integration under Configure, Sources, Cloud in LogPulse and fill in API hostname, Integration key, Secret key. LogPulse reads the Duo Admin API itself, every five minutes by default; there is nothing to install.
Which permissions does LogPulse need in Cisco Duo?
A Duo Admin API application with the "Grant read log" permission. Read access is enough for collecting logs.
Which index does Cisco Duo data go to?
The index is the kind of data: iam. The source is the product: duo. Each data source has its own sourcetype, listed on this page.
Which data models does Cisco Duo fill?
Authentication, Change. Detection rules and dashboards written for a data model work on Cisco Duo without changes.
Why do Duo authentications arrive two minutes late?
Duo writes authentication logs up to two minutes late. LogPulse reads two minutes behind real time so that it never misses one.