Duo Security

Duo Security is a multi-factor authentication (MFA) and single sign-on (SSO) provider that you can use to authenticate to protected networks in your organization.

Duo Security's logs can contain information about user ingress and admin activity. When you configure the Duo Admin API, you can start to monitor user accounts and authentications in InsightIDR.

The event types that InsightIDR can parse from this event source are:

  • Authentication events
  • Duo Admin events
  • Duo Trust Monitor events (available as unparsed logs). Note: Your Duo subscription must include Duo Trust Monitor.

There are two ways to send data from your Duo Security account to InsightIDR; event collection through the Cloud or through an on-premises Rapid7 Collector.

Cloud event sources are being phased in from December 2023

InsightIDR is adding cloud event collection capabilities to a select number of supported event sources; this one is included. This will be a phased release, so if your environment is not yet displaying the Run on Cloud option, please be patient–your environment will update shortly.

To set up the Duo Security event source, complete these steps:

  1. Read the requirements and complete any prerequisite steps.
  2. Configure Duo Security to send data to InsightIDR.
  3. Configure InsightIDR to receive data from the event source
  4. Test the configuration.

You can also:

Requirements

Before you start the configuration:

  • Contact your Duo representative to enable the Duo Admin API, because it is not enabled by default. Visit the Duo Admin API documentation at: https://duo.com/docs/adminapi.
  • To collect Duo Admin events and Duo Trust Monitor events in InsightIDR, ensure that you have the right subscription. Duo Trust Monitor, the threat detection component, is included in the Duo Premier and Advantage plans only. Read more about the Duo editions and pricing plans at: https://duo.com/editions-and-pricing.
  • Read more about using Duo to protect applications at: https://duo.com/docs/protecting-applications.

Configure Duo Security to send data to InsightIDR

To allow InsightIDR to receive data from Duo Security, you must configure a secret key in your Duo account to provide out-of-network access to its data.

To configure the Duo Admin API:

  1. Log in to the Duo Admin Panel and go to Applications > Protect an Application.
  2. Search for "Admin API."
  3. Record the integration key, secret key, and API hostname to enter later in InsightIDR.
  4. Go to the Properties page and enable these permissions:
    • Grant read information
    • Grant read log
    • Grant read resource
  5. Click Save Changes.

Configure InsightIDR to receive data from the event source

After you complete the prerequisite steps and configure the event source to send data, you must add the event source in InsightIDR.

Task 1: Select Duo Security

  1. From the left menu, go to Data Collection and click Setup Event Source > Add Event Source.
  2. Do one of the following:
    • Search for Duo Security in the event sources search bar.
    • In the Product Type filter, select Cloud Service.
  3. Select the Duo Security event source tile.

Task 2: Set up your collection method

There are two methods of collecting data from Duo; through a cloud connection or through a collector.

New credentials are required for cloud event sources

You cannot reuse existing on-premise credentials to create a cloud connection with this event source. You must create new credentials.

Use the Cloud Connection method
  1. In the Add Event Source panel, select Run On Cloud.
  2. Name the event source. This will become the name of the log that contains the event data in Log Search. If you do not name the event source, the log name defaults to Duo Security.
  3. Optionally, select the option to send unparsed data.
  4. Select your LDAP Account Attribution preference:
    • Use short name attribution: Applies the short name of the user without the domain suffix in the username field. For example, if the username was jsmith@myorg.example.com, the short name would be jsmith.
    • Use fully qualified domain name attribution: If you have a multi-domain environment, this option works best to attribute users and assets.
  5. Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
  6. Optionally, select the checkboxes to Collect Duo Admin logs and Collect Duo Trust Monitor logs if you would like to collect additional logs from these endpoints.
  7. Click Add a New Connection.
  8. In the Create a Cloud Connection screen, enter a name for the new connection.
  9. In the API Hostname field, enter the API hostname that you obtained in the previous section, Configure Duo Security to send data to InsightIDR.
  10. In the Integration Key field, add a new credential:
  1. In the Secret Key field, add a new credential:
  1. Click Save Connection.
  2. Click Save.
Use the Collector method
  1. In the Add Event Source panel, select Run On Collector.
  2. Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Duo Security.
  3. Optionally choose to send unparsed data.
  4. Select your LDAP Account Attribution preference:
    • Use short name attribution: Applies the short name of the user without the domain suffix in the username field. For example, if the username was jsmith@myorg.example.com, the short name would be jsmith.
    • Use fully qualified domain name attribution: If you have a multi-domain environment, this option works best to attribute users and assets.
  5. Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
  6. Enter the integration key that you copied in the earlier configuration of your Duo Security Admin API.
  7. Create a new credential:
    • Click Create New.
    • Specify a name for the credential.
    • Enter the Subdomain in the form of api-xxxxxxxx. The Subdomain is the first part of the API hostname in the Duo Admin API. For example, if you had api-12ab3456.yourdomain.com enter api-12ab3456 in the Subdomain field.
    • Enter the Token/Secret. The Token/Secret is the Secret Key in the Duo Admin API.
  8. Enter the refresh rate in minutes.
  9. Optionally, provide multi-domain details to map the relationship between applications attached to this Duo account and Active Directory domains so InsightIDR can attribute user activity.
  10. Optionally, select the checkboxes to Collect Duo Admin logs and Collect Duo Trust Monitor logs if you would like to collect additional logs from these endpoints.
  11. Click Save.

Test the Configuration

The event types that InsightIDR parses from this event source are:

  • Authentication events
  • Duo Admin events
  • Duo Trust Monitor events (available as unparsed logs)

To test that event data is flowing into InsightIDR:

  1. View the raw logs.
    • From the Data Collection Management page, click the Event Sources tab.
    • Find the event source you created and click View raw log. If the Raw Logs modal displays raw log entries, logs are successfully flowing to InsightIDR.
  2. Use Log Search to find the log entries. After approximately seven minutes, you can verify that log entries are appearing in Log Search.
    • From the left menu, go to Log Search.
    • In the Log Search filter, search for the new event source you created
    • Select the log sets and the log names under each log set. Duo Security logs flow into these log sets:
      • Ingress Authentication
      • SSO
      • Cloud Service Activity
    • Set the time range to Last 10 minutes and click Run.

The Results table displays all log entries that flowed into InsightIDR in the last 10 minutes. The keys and values that are displayed are helpful when you want to build a query and search your logs.

Sample logs

In Log Search, the log that is generated uses the name of your event source by default. The log appears under the log sets:

  • Ingress Authentication
  • SSO
  • Cloud Service Activity

To help you visualize the event logs that this event source generates, here are some sample logs:

user_marked_fraud authentication event

 
1
{
2
 "accessDevice": {
3
   "hostname": null,
4
   "ip": "0.0.0.0",
5
   "location": {
6
     "city": null,
7
     "country": null,
8
     "state": null
9
   }
10
 },
11
 "application": {
12
   "key": "AAAAAAAAAA",
13
   "name": "Okta"
14
 },
15
 "authDevice": {
16
   "ip": "30.30.30.30",
17
   "location": {
18
     "city": "Belfast",
19
     "country": "United Kingdom",
20
     "state": "Northern Ireland"
21
   },
22
   "name": "555-555-5555"
23
 },
24
 "eventType": "authentication",
25
 "factor": "duo_push",
26
 "reason": "user_marked_fraud",
27
 "result": "fraud",
28
 "timestamp": 1553767890,
29
 "txid": "a0148c14-WWWW-WWWW-acfe-ebe741cd1cfc",
30
 "user": {
31
   "key": "DUG78WWWWWXXXWWWJM21",
32
   "name": "jane doe"
33
 }
34
}

user_approved authentication event

 
1
{
2
 "ip": "0.0.0.0",
3
 "result": "success",
4
 "reason": "user_approved",
5
 "timestamp": 1614132794,
6
 "username": "jdoe",
7
 "integration": "LDAP Proxy",
8
 "factor": "duo_push",
9
 "authIp": "123.123.123.123",
10
 "eventType": "authentication",
11
 "authDeviceName": "123-702-8042",
12
 "user": {
13
   "key": "DUG78WWWWWXXXWWWJM21",
14
   "name": "John Doe"
15
 }
16
}

bypass_create admin event

 
1
{
2
 "action": "bypass_create",
3
 "description": "{\"bypass\": \"\", \"count\": 1, \"valid_secs\": 3600, \"auto_generated\": true, \"remaining_uses\": 3, \"user_id\": \"johdoeuserid\", \"bypass_code_ids\": [\"RandId\"]}",
4
 "isotimestamp": "2022-10-03T08:18:16+00:00",
5
 "object": "johndoe",
6
 "timestamp": 1664785096,
7
 "username": "John Doe"
8
}

fraud trust_monitor event

 
1
{
2
 "explanations":
3
 [
4
   {
5
     "summary": "johndoe has not accessed resources from this device recently.",
6
     "type": "NEW_DEVICE"
7
   },
8
   {
9
     "summary": "johndoe has rarely used this IP.",
10
     "type": "UNUSUAL_NETBLOCK"
11
   }
12
 ],
13
 "from_common_netblock": false,
14
 "from_new_user": false,
15
 "low_risk_ip": false,
16
 "priority_event": true,
17
 "priority_reasons":
18
 [
19
   {
20
     "label": "Corporate Okta",
21
     "type": "application"
22
   }
23
 ],
24
 "sekey": "RandKey",
25
 "state": "new",
26
 "state_updated_timestamp": null,
27
 "surfaced_auth":
28
 {
29
   "access_device":
30
   {
31
     "browser": "Chrome",
32
     "browser_version": "106.0.5249.91",
33
     "epkey": null,
34
     "flash_version": null,
35
     "hostname": null,
36
     "ip": "123.123.123.123",
37
     "is_encryption_enabled": "unknown",
38
     "is_firewall_enabled": "unknown",
39
     "is_password_set": "unknown",
40
     "java_version": null,
41
     "location":
42
     {
43
       "city": "Brandon",
44
       "country": "United States",
45
       "state": "Florida"
46
     },
47
     "os": "Linux",
48
     "os_version": "5.15.0",
49
     "security_agents": "unknown"
50
   },
51
   "adaptive_trust_assessments":
52
   {},
53
   "alias": "unknown",
54
   "application":
55
   {
56
     "key": "RandKey",
57
     "name": "Corporate Okta"
58
   },
59
   "auth_device":
60
   {
61
     "ip": null,
62
     "key": null,
63
     "location":
64
     {
65
       "city": null,
66
       "country": null,
67
       "state": null
68
     },
69
     "name": null
70
   },
71
   "email": "",
72
   "event_type": null,
73
   "factor": "not_available",
74
   "isotimestamp": "2022-10-03T01:39:16.650+00:00",
75
   "ood_software": "",
76
   "reason": "no_duo_certificate_present",
77
   "result": "fraud",
78
   "timestamp": 1664761156,
79
   "trusted_endpoint_status": null,
80
   "txid": "92a06204-80a1-4d51-a59c-121839649482",
81
   "user":
82
   {
83
     "groups":
84
     [
85
       "Rapid7 (from AD sync \"TOR\")",
86
       "All workers (from AD sync \"TOR\")"
87
     ],
88
     "key": "RandKey",
89
     "name": "johndoe"
90
   }
91
 },
92
 "surfaced_timestamp": 1664832130952,
93
 "triage_event_uri": "https://rapid7.com",
94
 "triaged_as_interesting": false,
95
 "type": "auth"
96
}

Troubleshooting

If you experience issues with the Duo Security event source, try the solutions provided in this section. Duo also provides a troubleshooting section in their Admin API docs at: https://duo.com/docs/adminapi#troubleshooting

Issues Connecting a Windows Collector

When using Windows collectors, you may experience issues connecting to Duo when using hardened cipher-suites. Duo recommends applying a Microsoft patch to fix issues with TLS1.1 or TLS1.2. Further information can be found here: https://help.duo.com/s/article/ka070000000fy7pAAA/3136?language=en_US.

Rate Limiting

After Duo Security is first set up, or during periods when there is a high volume of logs, you may notice a slight delay in the ingestion of the logs. This is because the Duo API enforces rate limiting. If the issue does not resolve itself within 10 minutes, contact Duo Security support.