--- title: "Duo collector" canonical: "https://docs.devo.com/space/latest/94655941/Duo%20collector" format: markdown --- > Macro (excerpt-include) > Macro (toc) ## Purpose An analyst wants to detect unauthorized access attempts using compromised credentials. Using the [Duo Security](https://duo.com/) collector to send multi-factor authentication logs to Devo, the analyst will find authentication failures from unexpected locations. As a result, the analyst will disable the affected accounts, preventing attackers from accessing sensitive systems. ## Example tables | **[Table](https://devodocs.atlassian.net/wiki/spaces/latest/pages/94660824)** | **Description** | | --- | --- | | `auth.duo.administrator` | Administrative actions in Duo | | `auth.duo.administrator.events` | Administrative events in Duo | | `auth.duo.administrator.login` | Administrator login attempts | | `auth.duo.authentication.events` | User authentication activity | | `auth.duo.authenticationProxy.events` | Authentication proxy events | | `auth.duo.telephony.events` | Phone-based authentication events | | Union tables that use these tags: `auth.all` | Union tables collect information for monitoring purposes. | ## Authorize it You need the owner role to perform these steps. Learn more [here](https://duo.com/docs/admin-roles). 1. Log in to the **[Duo Admin Panel](https://admin.duosecurity.com/)** and navigate to Applications. ![image-20240723-102041.png](media://31ac636d-1dc0-42ab-946e-9e77099f54a5) 2. Click **Protect an Application** and locate the entry for Admin API in the applications list. ![image-20240723-102053.png](media://34d245c1-fdb1-4df7-86a5-cf16b291e4dd) 3. Click **Protect** to configure the application. 4. Enable **"Grant read log"** permission for the Admin API application. ![image-20240723-102114.png](media://4978bd3d-b64e-413a-891f-d5ec6d9adeae) 5. Optionally, specify which IP addresses or ranges are allowed to use this Admin API application. The Admin API performs the IP check after verifying the [authentication signature](https://duo.com/docs/adminapi#authentication) in a request. If you restrict the allowed networks for API access and see logged events for blocked Admin API requests from unrecognised IP addresses, this may indicate a compromise of your Admin API application's secret key. 6. Copy the **integration key**, **secret key**, and **API hostname** for use in the collector configuration. Secure your secret key as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances. ### Connectivity requirements This application communicates with Duo's service on SSL TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review [Duo Knowledge Base article 1337](https://help.duo.com/s/article/1337). Effective June 30, 2023, Duo no longer supports TLS 1.0 or 1.1 connections or insecure TLS/SSL cipher suites. See [Duo Knowledge Base article 7546](https://help.duo.com/s/article/7546) for additional guidance. ## Run it In the Cloud Collector App, [create](https://devodocs.atlassian.net/wiki/spaces/latest/pages/409305131) a **Duo** collector instance. Insert this parameters template, replacing the values enclosed in `< >`. The `id` must be a unique [five digit number](https://www.random.org/integers/?num=1&min=10000&max=99999&col=5&base=10&format=html&rnd=new). ``` { "inputs": { "duo": { "id": "", "services": { "": {} }, "credentials": { "integration_key": "", "secret_key": "", "hostname": "" } } } } ``` ## Secure it Devo [Exchange](https://docs.devo.com/space/latest/95212575/Exchange) has alerts which will help secure Duo events: - [Authentication Alert Pack](https://devodocs.atlassian.net/wiki/spaces/latest/pages/411238402): The *SecOpsAuthPasswordSprayHost* alert detects password spray attacks across multiple user accounts. ## Monitor it Create an [inactivity alert](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126785) to detect interruptions of transfer of data from the source using the query ``` from auth.duo.authentication.events where toktains(hostchain,"collector-") select split(hostchain,"-",1) as collector_id ``` Set the inactivity alert to keep track of the `collector_id`. ## Parameters ### Example ``` { "global_overrides": { "debug": false }, "inputs": { "duo": { "id": "", "enabled": true, "credentials": { "integration_key": "", "secret_key": "", "hostname": "" }, "services": { "administrator": { "start_datetime_utc": "", "override_base_tag": "" }, "authentication": { "start_datetime_utc": "", "override_tag": "" }, "telephony": { "start_datetime_utc": "", "override_tag": "" } } } } } ``` ### Details | **Parameter** | **Data type** | **Necessity** | **Details** | | --- | --- | --- | --- | | `id` | string | Mandatory | Five unique digits. | | `debug` | string | Discouraged | Do not enable debug. | | `integration_key` | string | Mandatory | Client ID for Duo authentication. It acts as the HTTP username | | `secret_key` | string | Mandatory | Client secret for Duo authentication. It acts as the HTTP password | | `hostname` | string | Mandatory | Host for Duo requests. This is different for each customer.This is the URL for the different requests | | `override_base_tag` | string | Optional | The family of administrator logs will have a `level1.level2` different from `auth.duo`. Use this only with `my.app` or you won't be able to see the logs in Devo. | | `override_tag` | string | Optional | The authentication and telephony logs will have a `level1.level2.level3.level4` different from `auth.duo.authentication.events` and `auth.duo.telephony.events`. Use this only with `my.app.level3.level4` or you won't be able to see the logs in Devo. | | `start_datetime_utc` | string | Optional | If present, it will be the start date and time for pulling events. If not, the current date and time will be used. Example: `2024-07-01T03:00:00.000Z` | ## Troubleshooting General collector troubleshooting ### Setting the target pods This collector should only use one pod. It does not support multipod operation. ### Lookups This collector does not create lookups. To convert data from the collector to a lookup,[create a lookup from a query.](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95204060) ### Configuration errors | **Error type** | **Error ID** | **Error message** | **Cause** | **Solution** | | --- | --- | --- | --- | --- | | InitVariablesError | 0 | Invalid content detected in the metadata config | The internal config did not pass the format validation. Contact Devo Support. | Check the documentation and update the configuration accordingly | | InitVariablesError | 1 | Invalid content detected in the user config | The user config did not pass the format validation | Check the documentation and update the configuration accordingly | | InitVariablesError | 3 | Invalid content detected in the requests_limits config | The user config did not pass the format validation. | Check error traces for details and visit our documentation. | | DuoSetupException | 103 | Missing required credentials | Missing or empty credentials in the configuration | Include the proper credentials in the configuration | | DuoException | 100 | Service not supported | An unexpected service definition was found | Configure the available services: `administrator`, `authentication` or `telephony`. | | DuoException | 101 | Tag not found for `authentication` or `telephony` | An override tag value is found and it is empty or not valid | Configure the proper base_tag override for the `authentication` or `telephony` services. | | DuoException | 102 | Base tag not found for `administrator` | An override base_tag value is found and it is empty or not valid | Configure the proper base_tag override for the `administrator` service. | ## API Endpoints | **Endpoint** | **Service** | **Table** | | --- | --- | --- | | /admin/v2/logs/authentication | authentication | `auth.duo.authentication.events` | | /admin/v1/logs/administrator | administrator | `auth.duo.administrator.login` `auth.duo.administrator.events` | | /admin/v1/logs/telephony | telephony | `auth.duo.telephony.events` | ## Release Notes - v2.2.1 2023 - Fixed local variable referenced before assignment error - v2.2.0 2023-06-03 - Updated DCSDK Docker base image to "1.5.1" and DevoCollectorSDK Python package to "1.16.2" - v2.1.0 2023-05-20 - Updated DCSDK Docker base image from "1.3.1" to "1.5.0" and DevoCollectorSDK Python package from "1.13.1" to "1.16.1" - v2.0.4 2023-01-17 - Fixed the duplication issue in the incidents service v2.0.3 (2022-12-04): Added 2 new pullers and a base puller, improved unit tests, added checks for validating start_time - v2.0.2 2022-11-07 - Updated DCSDK from 1.12.4 to 1.13.1 - Fixed metric-related bugs - Improved MacOS compatibility - v2.0.1 2022-09-30 - Upgraded docker base image to 1.3.1 - Fixed infinite issue condition - v2.0.0 2022-09-06 - Added audit_management and all_alert services, moved to unified puller structure - v1.4.0 2022-08-23 - Added start_time as an optional parameter - Added deduplication logic - Updated Docker image - v1.3.0 2022-05-23 - Upgraded DC SDK to version 1.11.1 - Upgraded Docker base image to 1.2.0 - v1.2.0 2022-03-20 - Initial version - Added start_time configuration for alerts service