From 4af8931b4992b4334dcfac91885c9d31a2abe876 Mon Sep 17 00:00:00 2001 From: Dympna Laverty Date: Mon, 6 Nov 2023 12:50:54 +0000 Subject: [PATCH] Updated to allow optional collection of events and logs for task --- plugins/duo_admin/.CHECKSUM | 4 +- plugins/duo_admin/help.md | 1197 ++++++----------- .../tasks/monitor_logs/schema.py | 25 +- .../tasks/monitor_logs/task.py | 117 +- .../duo_admin/komand_duo_admin/util/api.py | 1 - plugins/duo_admin/plugin.spec.yaml | 15 + 6 files changed, 532 insertions(+), 827 deletions(-) diff --git a/plugins/duo_admin/.CHECKSUM b/plugins/duo_admin/.CHECKSUM index df8af85371..c97893f0f5 100644 --- a/plugins/duo_admin/.CHECKSUM +++ b/plugins/duo_admin/.CHECKSUM @@ -1,5 +1,5 @@ { - "spec": "b3d9442c06533628429f0e2b0bd325b4", + "spec": "fc0a9b9c3caa9302cf295b27db2e2083", "manifest": "f4e1dd49f20e1296961d505355562e0c", "setup": "04a7da9d3378345c594daac9b8c9db60", "schemas": [ @@ -49,7 +49,7 @@ }, { "identifier": "monitor_logs/schema.py", - "hash": "f8c9067346589ef6a11e81c6132015e2" + "hash": "ff4f7adf6cbae20cd793af79e763a06d" } ] } \ No newline at end of file diff --git a/plugins/duo_admin/help.md b/plugins/duo_admin/help.md index efcedf4e17..d716597293 100644 --- a/plugins/duo_admin/help.md +++ b/plugins/duo_admin/help.md @@ -1,46 +1,31 @@ # Description -[Duo](https://duo.com/)'s Trusted Access platform verifies the identity of your users with two-factor authentication and -security health of their devices before they connect to the apps they use. Using the Duo plugin for InsightConnect will -allow Duo user management within automation workflows. +Duo is a trusted access solution for organizations. The Duo Admin plugin for Rapid7 InsightConnect allows users to manage and administrate their Duo organization # Key Features - -* Add user -* Delete user -* Enroll user -* Get logs -* Get phones by user ID -* Get user by ID -* Get user by username -* Get user status -* Get users -* Modify user + +*This plugin does not contain any key features.* # Requirements - -The following information are required for using `Duo Admin` plugin: -* Two secret keys - `integration key` and `secret key` -* `API hostname` - -Read more [here](https://duo.com/docs/adminapi#first-steps). + +*This plugin does not contain any requirements.* # Supported Product Versions - + * Duo Admin API 2023-05-19 # Documentation ## Setup - -The connection configuration accepts the following parameters: + +The connection configuration accepts the following parameters: |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | |hostname|string|None|True|Duo API hostname|None|api-XXXXXXXX.duosecurity.com| |integrationKey|credential_secret_key|None|True|API integration key|None|DUCUULF6HBMZ43IG9MBH| |secretKey|credential_secret_key|None|True|API secret key|None|3rlCtQGBVpoCXkjP3pLslVWxO8b4W5j1| - + Example input: ``` @@ -55,293 +40,215 @@ Example input: ### Actions -#### Get User by ID -This action is used to retrieve user information by ID. +#### Add User + +Add a user in Duo Admin ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|userId|string|None|True|User unique ID|None|DUCUULF6HBMZ43IG9MBH| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|aliases|[]string|None|False|User aliases. May have up to 4 unique amongst users|None|['test-alias']| +|email|string|None|False|Email of the user|None|user@example.com| +|firstname|string|None|False|The user's given name. Required for Duo's ID Proofing feature|None|Test| +|lastname|string|None|False|The user's surname. Required for Duo's ID Proofing feature|None|User| +|notes|string|None|False|An optional description or notes field|None|Example note| +|realname|string|None|False|User's real name|None|Example User| +|status|string|active|False|User status|['active', 'bypass', 'disabled']|active| +|username|string|None|True|The name of the user to create|None|example-user| + Example input: ``` { - "userId": "DUCUULF6HBMZ43IG9MBH" + "aliases": "test-alias", + "email": "user@example.com", + "firstname": "Test", + "lastname": "User", + "notes": "Example note", + "realname": "Example User", + "status": "active", + "username": "example-user" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|user|user|False|User details|{}| - +| :--- | :--- | :--- | :--- | :--- | +|user|user|False|User|{}| + Example output: ``` { - "user": { - "created": 1111111111, - "email": "user@example.com", - "lastLogin": 1511423501, - "phones": [ - { - "activated": true, - "capabilities": [ - "auto", - "push", - "sms", - "phone", - "mobile_otp" - ], - "lastSeen": "2018-08-20T06:52:20", - "number": "+11111111111", - "phoneId": "1234ABCDEFG", - "platform": "Apple iOS", - "smsPasscodesSent": false, - "type": "Mobile" - } - ], - "realname": "John Doe", - "status": "active", - "userId": "BUUUUUUUUUUUUUUUUUUZ", - "username": "jdoe" - } + "user": {} } ``` -#### Get User by Username - -This action is used to retrieve information by username. +#### Delete User by ID + +Delete a user by ID ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|username|string|None|True|Specify a username (or username alias) to look up a single user|None|jdoe| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|userId|string|None|True|User ID to remove|None|DUCUULF6HBMZ43IG9MBH| + Example input: ``` { - "username": "jdoe" + "userId": "DUCUULF6HBMZ43IG9MBH" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|user|user|False|User details|{}| - +| :--- | :--- | :--- | :--- | :--- | +|success|boolean|False|Whether the action was successful|True| + Example output: ``` { - "user": { - "created": 1462823674, - "email": "user@example.com", - "lastLogin": 1534446415, - "phones": [ - { - "activated": true, - "capabilities": [ - "auto", - "push", - "sms", - "phone", - "mobile_otp" - ], - "lastSeen": "2018-08-21T15:57:34", - "number": "+12222222222", - "phoneId": "11111113RP6666666666", - "platform": "Google Android", - "smsPasscodesSent": false, - "type": "Mobile" - } - ], - "status": "active", - "userId": "A777777777777777777W", - "username": "jdoe" - } + "success": true } ``` -#### Get User Status - -This action is used to get the account status of a user. - -If the user is found, the action returns one of the following statuses: active, bypass, disabled, or locked out, and the user's ID. The user's ID can be used as input to actions in the plugin that require a User ID. +#### Enroll User + +Enrolls a user and sends an enrollment email to the specified email address ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|username|string|None|True|The username or alias for which you want to get the status|None|user| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|email|string|None|True|Email address to send enrollment email to|None|user@example.com| +|timeToExpiration|number|0|False|Amount of time in seconds until enrollment email expires. Use '0' for no expiration|None|3600| +|username|string|None|True|Username for user to enroll|None|test-username| + Example input: ``` { - "username": "user" + "email": "user@example.com", + "timeToExpiration": 0, + "username": "test-username" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|status|string|True|Status of the user|active| -|userId|string|True|ID of the user|DU0W79YFWZAJWJV6P00L| - -Example user: +| :--- | :--- | :--- | :--- | :--- | +|success|boolean|False|Whether or not the enrollment was successful|True| + +Example output: ``` { - "status": "active" - "userId": "DU3RP9I2WOC59VZX672" + "success": true } ``` -#### Modify User by ID - -This action is used to modify a user by ID. +#### Get Authentication Logs + +Get auth logs, limited to past 180 days ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|alias1|string|None|False|A username alias 1|None|alias1| -|alias2|string|None|False|A username alias 1|None|alias2| -|alias3|string|None|False|A username alias 3|None|alias3| -|alias4|string|None|False|A username alias 4|None|alias3| -|email|string|None|False|The new email address|None|user@example.com| -|firstname|string|None|False|The user's new given name|None|Example| -|lastname|string|None|False|The user's new surname|None|Example| -|notes|string|None|False|The new notes field|None|Example| -|realname|string|None|False|The new realname (or full name)|None|Example| -|status|string|None|False|The new status. Select 'None' to skip status change|['active', 'disabled', 'bypass', 'None']|active| -|userId|string|None|True|User unique ID|None|DUCUULF6HBMZ43IG9MBH| -|username|string|None|False|The new username|None|Example| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|applications|[]string|None|False|List of application IDs to filter on|None|['DIV9C5V7T6L02DRWL4RU']| +|eventTypes|[]string|None|False|List of event types(authentication, enrollment) to filter on, to include all leave this parameter empty|None|['authentication']| +|factors|[]string|None|False|List of factors or methods used for an authentication attempt to filter on, to include all leave this parameter empty. Check the help documentation to see all available inputs|None|['duo_push', 'sms_passcode']| +|groups|[]string|None|False|List of group IDs to filter on|None|['DG67EON0I1QA2ZDUF32M']| +|maxtime|integer|None|False|Maximum time in UNIX timestamp milliseconds. Must be 13 or more digits in length and greater than mintime. To use current time leave this parameter empty|None|1611069760000| +|mintime|integer|None|True|Minimum time in UNIX timestamp milliseconds. Must be 13 or more digits in length|None|1609377288936| +|phoneNumbers|[]string|None|False|List of phone numbers to filter on|None|['+11111111111']| +|reasons|[]string|None|False|List of reasons associated with an authentication attempt to filter on, to include all leave this parameter empty. Check the help documentation to see all available inputs|None|['user_disabled']| +|results|[]string|None|False|List of results of an authentication attempt(success, denied, fraud) to filter on, to include all leave this parameter empty|None|['denied']| +|tokens|[]string|None|False|List of FIDO U2F token registration IDs or WebAuthn security keys to filter on|None|['WA4ED9AUVMSWUF00KES4']| +|users|[]string|None|False|List of user IDs to filter on|None|['DUW2DKA44RFYECTU8R1O']| + Example input: ``` { - "alias1": "alias1", - "alias2": "alias2", - "alias3": "alias3", - "alias4": "alias3", - "email": "user@example.com", - "firstname": "Example", - "lastname": "Example", - "notes": "Example", - "realname": "Example", - "status": "active", - "userId": "DUCUULF6HBMZ43IG9MBH", - "username": "Example" + "applications": "DIV9C5V7T6L02DRWL4RU", + "eventTypes": "authentication", + "factors": "duo_push", + "groups": "DG67EON0I1QA2ZDUF32M", + "maxtime": 1611069760000, + "mintime": 1609377288936, + "phoneNumbers": "+11111111111", + "reasons": "user_disabled", + "results": "denied", + "tokens": "WA4ED9AUVMSWUF00KES4", + "users": "DUW2DKA44RFYECTU8R1O" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|user|user|False|User details|{}| - +| :--- | :--- | :--- | :--- | :--- | +|authLogs|[]authLog|True|Logs|[]| + Example output: ``` { - "user": { - "alias1": "alias1", - "alias2": "alias2", - "alias3": "alias3", - "alias4": "alias4", - "aliases": { - "alias1": "alias1", - "alias2": "alias2", - "alias3": "alias3", - "alias4": "alias4" - }, - "created": 1684765611, - "email": "user@example.com", - "firstname": "Example", - "isEnrolled": false, - "lastname": "Example", - "notes": "Example", - "realname": "Example", - "status": "active", - "userId": "DUCUULF6HBMZ43IG9MBH", - "username": "Example" - } + "authLogs": [] } ``` -#### Get Users - -This action is used to retrieve information on users. +#### Get Phones by User ID + +Gets a list of phones associated with the user ID ##### Input -_This action does not contain any inputs._ +|Name|Type|Default|Required|Description|Enum|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|userId|string|None|True|The identifier of the user|None|DUCUULF6HBMZ43IG9MBH| + +Example input: + +``` +{ + "userId": "DUCUULF6HBMZ43IG9MBH" +} +``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|users|[]user|False|List of users|[]| - +| :--- | :--- | :--- | :--- | :--- | +|phoneList|[]phoneUser|False|List of phones associated with the user's ID|[]| + Example output: ``` { - "users": [ - { - "created": 1111111111, - "email": "user@example.com", - "lastLogin": 1511423501, - "phones": [ - { - "activated": true, - "capabilities": [ - "auto", - "push", - "sms", - "phone", - "mobile_otp" - ], - "lastSeen": "2018-08-20T06:52:20", - "number": "+11111111111", - "phoneId": "ABCDEFGHIJ", - "platform": "Apple iOS", - "smsPasscodesSent": false, - "type": "Mobile" - } - ], - "realname": "John Doe", - "status": "active", - "userId": "BUUUUUUUUUUUUUUUUUUZ", - "username": "jdoe" - }, - ... - ] + "phoneList": [] } ``` -#### Delete User by ID - -This action is used to delete a user by ID. +#### Get User by ID + +Get a user by ID ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|userId|string|None|True|User ID to remove|None|DUCUULF6HBMZ43IG9MBH| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|userId|string|None|True|User unique ID|None|DUCUULF6HBMZ43IG9MBH| + Example input: ``` @@ -353,665 +260,418 @@ Example input: ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|success|boolean|False|Whether the action was successful|True| - +| :--- | :--- | :--- | :--- | :--- | +|user|user|False|User details|{}| + Example output: ``` { - "success": true + "user": {} } ``` -#### Get Authentication Logs - -This action is used to get auth logs, limited to past 180 days. -[Currentmillis.com](https://currentmillis.com/) is useful for finding a usable UNIX timestamp. - -Available inputs for parameters: - -* `factors` - a comma-separated list of factors, if left empty, the action returns the authentication logs for all factors used for an authentication attempt - * bypass_code - * digipass_go_7_token - * duo_mobile_passcode - * duo_push - * hardware_token - * not_available - * passcode - * phone_call - * remembered_device - * sms_passcode - * sms_refresh - * trusted_network - * u2f_token - * yubikey_code -* `reasons` - a comma-separated list of reasons, if left empty, the action returns the authentication logs for all reasons associated with an authentication attempt - * allow_unenrolled_user - * allow_unenrolled_user_on_trusted_network - * allowed_by_policy - * anomalous_push - * anonymous_ip - * bypass_user - * call_timed_out - * could_not_determine_if_endpoint_was_trusted - * denied_by_policy - * deny_unenrolled_user - * endpoint_failed_google_verification - * endpoint_is_not_in_management_system - * endpoint_is_not_trusted - * error - * factor_restricted - * invalid_device - * invalid_management_certificate_collection_state - * invalid_passcode - * invalid_referring_hostname_provided - * location_restricted - * locked_out - * no_activated_duo_mobile_account - * no_disk_encryption - * no_duo_certificate_present - * no_keys_pressed - * no_referring_hostname_provided - * no_response - * no_screen_lock - * no_web_referer_match - * out_of_date - * platform_restricted - * remembered_device - * rooted_device - * software_restricted - * touch_id_disabled - * trusted_location - * trusted_network - * user_approved - * user_cancelled - * user_disabled - * user_marked_fraud - * user_not_in_permitted_group - * user_provided_invalid_certificate - * valid_passcode - * version_restricted +#### Get User by Username + +Get a user by username ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|applications|[]string|None|False|List of application IDs to filter on|None|["DIV9C5V7T6L02DRWL4RU"]| -|eventTypes|[]string|None|False|List of event types(authentication, enrollment) to filter on, to include all leave this parameter empty|None|["authentication"]| -|factors|[]string|None|False|List of factors or methods used for an authentication attempt to filter on, to include all leave this parameter empty. Check the help documentation to see all available inputs|None|["duo_push", "sms_passcode"]| -|groups|[]string|None|False|List of group IDs to filter on|None|["DG67EON0I1QA2ZDUF32M"]| -|maxtime|integer|None|False|Maximum time in UNIX timestamp milliseconds. Must be 13 or more digits in length and greater than mintime. To use current time leave this parameter empty|None|1611069760000| -|mintime|integer|None|True|Minimum time in UNIX timestamp milliseconds. Must be 13 or more digits in length|None|1609377288936| -|phoneNumbers|[]string|None|False|List of phone numbers to filter on|None|["+11111111111"]| -|reasons|[]string|None|False|List of reasons associated with an authentication attempt to filter on, to include all leave this parameter empty. Check the help documentation to see all available inputs|None|["user_disabled"]| -|results|[]string|None|False|List of results of an authentication attempt(success, denied, fraud) to filter on, to include all leave this parameter empty|None|["denied"]| -|tokens|[]string|None|False|List of FIDO U2F token registration IDs or WebAuthn security keys to filter on|None|["WA4ED9AUVMSWUF00KES4"]| -|users|[]string|None|False|List of user IDs to filter on|None|["DUW2DKA44RFYECTU8R1O"]| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|username|string|None|True|Specify a username (or username alias) to look up a single user|None|jdoe| + Example input: ``` { - "applications": [ - "DIV9C5V7T6L02DRWL4RU" - ], - "eventTypes": [ - "authentication" - ], - "factors": [ - "duo_push", - "sms_passcode" - ], - "groups": [ - "DG67EON0I1QA2ZDUF32M" - ], - "maxtime": 1611069760000, - "mintime": 1609377288936, - "phoneNumbers": [ - "+11111111111" - ], - "reasons": [ - "user_disabled" - ], - "results": [ - "denied" - ], - "tokens": [ - "WA4ED9AUVMSWUF00KES4" - ], - "users": [ - "DUW2DKA44RFYECTU8R1O" - ] + "username": "jdoe" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|authLogs|[]authLog|True|Logs|[]| - +| :--- | :--- | :--- | :--- | :--- | +|user|user|False|User details|{}| + Example output: ``` { - "authLogs": [ - { - "accessDevice": { - "browser": "Chrome", - "browserVersion": "67.0.3396.99", - "flashVersion": "uninstalled", - "ip": "198.51.100.1", - "isEncryptionEnabled": "true", - "isFirewallEnabled": "true", - "isPasswordSet": "true", - "javaVersion": "uninstalled", - "location": { - "city": "Bloomington", - "country": "United States", - "state": "Illinois" - }, - "os": "Mac OS X", - "osVersion": "10.14.1" - }, - "alias": "test", - "application": { - "key": "DIV9C5V7T6L02DRWL4RU", - "name": "Microsoft Azure Active Directory" - }, - "authDevice": { - "ip": "198.51.100.1", - "location": { - "city": "Bloomington", - "country": "United States", - "state": "Illinois" - }, - "name": "+11111111111" - }, - "email": "user@example.com", - "eventType": "authentication", - "factor": "duo_push", - "isotimestamp": "2021-01-19T14:47:24.309957+00:00", - "reason": "user_disabled", - "result": "denied", - "timestamp": 1611067644, - "txid": "9de5069c-5afe-602b-2ea0-a04b66beb2c0", - "user": { - "groups": [ - "InsightConnect Group" - ], - "key": "DUW2DKA44RFYECTU8R1O", - "name": "user@example.com" - } - } - ] + "user": {} } ``` -#### Add User - -This action is used to add a user in Duo Admin. +#### Get User Status + +Get account status of a user ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|aliases|[]string|None|False|User aliases. May have up to 4 unique amongst users|None|["test-alias"]| -|email|string|None|False|Email of the user|None|user@example.com| -|firstname|string|None|False|The user's given name. Required for Duo's ID Proofing feature|None|Test| -|lastname|string|None|False|The user's surname. Required for Duo's ID Proofing feature|None|User| -|notes|string|None|False|An optional description or notes field|None|Example note| -|realname|string|None|False|User's real name|None|Example User| -|status|string|active|False|User status|['active', 'bypass', 'disabled']|active| -|username|string|None|True|The name of the user to create|None|example-user| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|username|string|None|True|The username or alias for which you want to get the status|None|user| + Example input: ``` { - "aliases": [ - "test-alias" - ], - "email": "user@example.com", - "firstname": "Test", - "lastname": "User", - "notes": "Example note", - "realname": "Example User", - "status": "active", - "username": "example-user" + "username": "user" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|user|user|False|User|{}| - +| :--- | :--- | :--- | :--- | :--- | +|status|string|True|Status of the user|active| +|userId|string|True|ID of the user|DU0W79YFWZAJWJV6P00L| + Example output: ``` { - "user": { - "aliases": [ - "test-alias" - ], - "created": 1538529180, - "email": "user@example.com", - "firstname": "Test", - "lastname": "User", - "notes": "Example note", - "realname": "Example User", - "status": "active", - "userId": "DUVSXMGU7NLM8H803W9L", - "username": "example-user" - } + "status": "active", + "userId": "DU0W79YFWZAJWJV6P00L" } ``` -#### Get Phones by User ID - -This action is used to get a list of phones associated with the user ID. +#### Get Users + +Get list of users ##### Input - -|Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|userId|string|None|True|The identifier of the user|None|DUCUULF6HBMZ43IG9MBH| - -Example input: - -``` -{ - "userId": "DUCUULF6HBMZ43IG9MBH" -} -``` + +*This action does not contain any inputs.* ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|phoneList|[]phoneUser|False|List of phones associated with the user's ID|[]| - +| :--- | :--- | :--- | :--- | :--- | +|users|[]user|False|List of users|[]| + Example output: ``` { - "phoneList": [ - { - "activated": true, - "capabilities": [ - "auto", - "push", - "sms", - "phone", - "mobile_otp" - ], - "lastSeen": "2019-01-15T23:02:20", - "number": "123456789", - "phoneId": "DUCUULF6HBMZ43IG9MBH", - "platform": "Google Android", - "smsPasscodesSent": false, - "type": "Mobile" - } - ] + "users": [] } ``` -#### Enroll User - -This action is used to enroll a user and send an enrollment email to the specified email address. +#### Modify User by ID + +Modify a user by ID ##### Input |Name|Type|Default|Required|Description|Enum|Example| -|----|----|-------|--------|-----------|----|-------| -|email|string|None|True|Email address to send enrollment email to|None|user@example.com| -|timeToExpiration|number|0|False|Amount of time in seconds until enrollment email expires. Use '0' for no expiration|None|3600| -|username|string|None|True|Username for user to enroll|None|test-username| - +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|alias1|string|None|False|A username alias 1|None|alias1| +|alias2|string|None|False|A username alias 1|None|alias2| +|alias3|string|None|False|A username alias 3|None|alias3| +|alias4|string|None|False|A username alias 4|None|alias3| +|email|string|None|False|The new email address|None|user@example.com| +|firstname|string|None|False|The user's new given name|None|Example| +|lastname|string|None|False|The user's new surname|None|Example| +|notes|string|None|False|The new notes field|None|Example| +|realname|string|None|False|The new realname (or full name)|None|Example| +|status|string|None|False|The new status. Select 'None' to skip status change|['active', 'disabled', 'bypass', 'None']|active| +|userId|string|None|True|User unique ID|None|DUCUULF6HBMZ43IG9MBH| +|username|string|None|False|The new username|None|Example| + Example input: ``` { + "alias1": "alias1", + "alias2": "alias2", + "alias3": "alias3", + "alias4": "alias3", "email": "user@example.com", - "timeToExpiration": 3600, - "username": "test-username" + "firstname": "Example", + "lastname": "Example", + "notes": "Example", + "realname": "Example", + "status": "None", + "userId": "DUCUULF6HBMZ43IG9MBH", + "username": "Example" } ``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|success|boolean|False|Whether or not the enrollment was successful|True| - +| :--- | :--- | :--- | :--- | :--- | +|user|user|False|User details|{}| + Example output: ``` { - "success": true + "user": {} } ``` - ### Triggers - -_This plugin does not contain any triggers._ - + +*This plugin does not contain any triggers.* ### Tasks -#### Monitor Logs -This task is used to monitor administrator, authentication and trust monitor event logs. +#### Monitor Logs + +Monitor administrator, authentication and trust monitor event logs ##### Input -_This task does not contain any inputs._ +|Name|Type|Default|Required|Description|Enum|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +|collectAdminLogs|boolean|True|True|Whether to collect Adming logs (note requires appropriate level of Duo Admin license)|None|False| +|collectTrustMonitorEvents|boolean|True|True|Whether to collect Trust Monitor events (note requires appropriate level of Duo Admin license)|None|False| + +Example input: + +``` +{ + "collectAdminLogs": true, + "collectTrustMonitorEvents": true +} +``` ##### Output |Name|Type|Required|Description|Example| -|----|----|--------|-----------|-------| -|logs|[]log|True|List of administrator, authentication and trust monitor event logs within the specified time range|[]| - +| :--- | :--- | :--- | :--- | :--- | +|logs|[]object|True|List of administrator, authentication and trust monitor event logs within the specified time range|[]| + Example output: ``` { - "logs": [ - { - "accessDevice": { - "browser": "Chrome", - "browserVersion": "113.0.0.0", - "ip": "198.51.100.1", - "isEncryptionEnabled": "unknown", - "isFirewallEnabled": "unknown", - "isPasswordSet": "unknown", - "location": { - "city": "Los Angeles", - "country": "United States", - "state": "California" - }, - "os": "Mac OS X", - "osVersion": "10.15.7" - }, - "alias": "unknown", - "application": { - "key": "DI8CODQSMK4BXPLYS47K", - "name": "User Portal" - }, - "authDevice": { - "key": "DPAVQAJMU3BW0LV7OCX3", - "name": "Generic Smartphone" - }, - "eventType": "enrollment", - "factor": "not_available", - "isotimestamp": "2023-05-29T10:07:38.631165+00:00", - "result": "success", - "timestamp": 1685354858, - "trustedEndpointStatus": "unknown", - "txid": "9de5069c-5afe-602b-2ea0-a04b66beb2c0", - "user": { - "groups": [ - "Test Group" - ], - "key": "DUOR48RKV2AYN7YVS9BT", - "name": "example-user" - }, - "logType": "authentication" - }, - { - "action": "user_create", - "description": "{\"status\": \"Active\", \"email\": \"user@example.com\", \"realname\": \"\", \"notes\": \"\", \"uname\": \"user\"}", - "isotimestamp": "2023-04-30T07:52:18+00:00", - "object": "user", - "timestamp": 1682836490, - "username": "API (Admin API)", - "logType": "administrator" - }, - { - "bypassStatusEnabled": 1682836486230, - "enabledBy": { - "key": "DEKU19BYSSJSOABCD123", - "name": "Admin" - }, - "enabledFor": { - "key": "DUM07ZQ4LY00TABCD123", - "name": "example-user" - }, - "priorityEvent": false, - "sekey": "SE80GVU5Z47F0ABCD123", - "state": "new", - "surfacedTimestamp": 1682836486232, - "triagedAsInteresting": false, - "type": "bypass_status", - "logType": "trust_monitor_event" - } - ] + "logs": [] } ``` -### Custom Output Types - -#### accessDevice - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Access Device|string|False|The web browser used for access| -|Browser Version|string|False|The browser version| -|Flash Version|string|False|The Flash plugin version used| -|Hostname|string|False|The hostname| -|IP Address|string|False|The access device's IP address| -|Is Encryption Enabled|string|False|Reports the disk encryption state as detected by the Duo Device Health app. One of true, false, or unknown| -|Is Firewall Enabled|string|False|Reports the firewall state as detected by the Duo Device Health app. One of true, false, or unknown| -|Is Password Set|string|False|Reports the system password state as detected by the Duo Device Health app. One of true, false, or unknown| -|Java Version|string|False|The Java plugin version used| -|Location|location|False|The GeoIP location of the access device| -|Operating System|string|False|The device operating system name| -|Operating System Version|string|False|The device operating system version| - -#### adaptiveTrustAssessments - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|More Secure Auth|trustAssessmentObject|False|Trust assessment information for Risk-Based Factor Selection| -|Remember Me|trustAssessmentObject|False|Trust assessment information for Risk-Based Remembered Devices| - -#### authDevice - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|IP Address|string|False|The IP address of the authentication device| -|Key|string|False|The Duo identifier of the authentication device| -|Location|location|False|The GeoIP location of the authentication device| -|Name|string|False|The name of the authentication device| - -#### authLog - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Access Device|accessDevice|False|Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo's inline browser prompt| -|Adaptive Trust Assessments|adaptiveTrustAssessments|False|Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied| -|Alias|string|False|The username alias used to log in. No value if the user logged in with their username instead of a username alias| -|Application|keyNamePair|False|Information about the application accessed| -|Auth Device|authDevice|False|Information about the device used to approve or deny authentication| -|Email|string|False|The email address of the user| -|Event Type|string|False|The type of activity logged| -|Factor|string|False|The authentication factor| -|ISO8601 Timestamp|string|False|ISO8601 timestamp of the event| -|OOD Software|string|False|If authentication was denied due to out-of-date software, shows the name of the software| -|Reason|string|False|The reason for the authentication attempt result| -|Result|string|False|The result of the authentication attempt. One of: 'success', 'denied', 'failure', 'error', or 'fraud'| -|Timestamp|number|False|An integer indicating the Unix timestamp of the event| -|Transaction ID|string|False|The transaction ID of the event| -|User|authlogUser|False|Information about the authenticating user| - -#### authlogUser - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Groups|[]string|False|Duo group membership information for the user| -|Key|string|False|The ID of the user| -|Name|string|False|The name of the user| - -#### explanation - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Summary|string|False|Summary of the event| -|Type|string|False|Type of the event| - -#### group - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Description|string|False|The group's description| -|Group ID|string|False|The group's ID| -|Name|string|False|The group's name| -|Status|string|False|The group's authentication status| - -#### keyNamePair - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Key|string|False|The integration key| -|Name|string|False|The name| - -#### location - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|City|string|False|The city name| -|Country|string|False|The country name| -|State|string|False|The state, county, province, or prefecture| - -#### log - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Access Device|accessDevice|False|Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo's inline browser prompt| -|Action|string|False|The type of change that was performed| -|Adaptive Trust Assessments|adaptiveTrustAssessments|False|Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied| -|Alias|string|False|The username alias used to log in. No value if the user logged in with their username instead of a username alias| -|Application|keyNamePair|False|Information about the application accessed| -|Auth Device|authDevice|False|Information about the device used to approve or deny authentication| -|Bypass Status Enabled|integer|False|An integer indicating the Unix timestamp in milliseconds when bypass status was enabled for the user or group| -|Description|string|False|String detailing what changed| -|Email|string|False|The email address of the user| -|Enabled By|keyNamePair|False|The application or the administrator that enabled bypass status| -|Enabled For|keyNamePair|False|The user or group with bypass status| -|Event Type|string|False|The type of activity logged| -|Explanations|[]explanation|False|An array of objects describing why Trust Monitor surfaced the event| -|Factor|string|False|The authentication factor| -|From Common Netblock|boolean|False|A boolean describing if this event was created from a common IP netblock| -|From New User|boolean|False|A boolean describing if this event was created for a new user| -|ISO8601 Timestamp|string|False|ISO8601 timestamp of the event| -|Log Type|string|False|Type of the log| -|Low Risk IP|boolean|False|A boolean describing if this event was created from an IP address identified in the Risk Profile configuration as a low risk IP address| -|Object|string|False|The object that was acted on| -|OOD Software|string|False|If authentication was denied due to out-of-date software, shows the name of the software| -|Priority Event|boolean|False|A boolean describing if the event matches the Risk Profile configuration| -|Priority Reasons|[]priorityReason|False|An array of objects describing how the event matches the Trust Monitor Risk Profile configuration| -|Reason|string|False|The reason for the authentication attempt result| -|Result|string|False|The result of the authentication attempt. One of: 'success', 'denied', 'failure', 'error', or 'fraud'| -|Sekey|string|False|The unique identifier for this event| -|State|string|False|A string describing the state of the event| -|State Updated Timestamp|integer|False|An integer indicating the Unix timestamp in milliseconds of the last change to the state of the event| -|Surfaced Auth|authLog|False|An object which represents the actual authentication| -|Surfaced Timestamp|integer|False|An integer indicating the Unix timestamp in milliseconds when the event was surfaced by Trust Monitor| -|Timestamp|number|False|An integer indicating the Unix timestamp of the event| -|Triage Event URI|string|False|A string representing the URI of the security event, which a Duo administrator can use to view and process the surfaced event in the Duo Admin Panel| -|Triaged As Interesting|boolean|False|A boolean describing if this event was triaged as being interesting or not interesting| -|Transaction ID|string|False|The transaction ID of the event| -|Type|string|False|The type of event| -|User|authlogUser|False|Information about the authenticating user| -|Username|string|False|The full name of the administrator who performed the action| - -#### phoneUser - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Activated|boolean|False|Whether the phone has already been activated for Duo Mobile| -|Capabilities|[]string|False|List of factors that can be used with the phone| -|Encrypted|string|False|The encryption status of an Android or iOS device file system| -|Extension|string|False|Extension of the phone| -|Fingerprint|string|False|Whether an Android or iOS phone is configured for biometric verification| -|Last Seen|string|False|An integer indicating the timestamp of the last contact between Duo's service and the activated Duo Mobile app installed on the phone| -|Model|string|False|The phone's model| -|Name|string|False|Free-form label for the phone| -|Number|string|False|Number| -|Phone ID|string|False|The phone's ID| -|Platform|string|False|The phone platform| -|Postdelay|string|False|The time (in seconds) to wait after the extension is dialed and before the speaking the prompt| -|Predelay|string|False|The time (in seconds) to wait after the number picks up and before dialing the extension| -|Screen Lock|string|False|Whether screen lock is enabled on an Android or iOS phone| -|SMS Passcodes Sent|boolean|False|Whether the SMS passcodes has been sent to this phone| -|Type|string|False|Whether an iOS or Android device is jailbroken or rooted| -|Type|string|False|The type of phone| - -#### priorityReason - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Label|string|False|The label of the priority reason for the event's match| -|Type|string|False|The type of priority reason for the event's match| - -#### token - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Admins|[]object|False|A list of administrators associated with this hardware token| -|Serial|string|False|The serial number of the hardware token| -|Token ID|string|False|The hardware token's unique ID| -|Type|string|False|The type of hardware token| -|Users|[]object|False|A list of end users associated with this hardware token| - -#### trustAssessmentObject - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Features Version|string|False|The feature version for the risk-based authentication trust assessment| -|Model Version|string|False|The model version for the risk-based authentication trust assessment| -|Policy Enabled|boolean|False|Denotes if risk-based authentication was enabled by the policy under which the trust assessment was evaluated| -|Reason|string|False|The reason behind the trust assessment level| -|Trust Level|string|False|The trust assessment level. Can be one of: ERROR, LOW, NORMAL, UNKNOWN, or UNSET| - -#### user - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Alias 1|string|False|The user's username alias 1| -|Alias 2|string|False|The user's username alias 2| -|Alias 3|string|False|The user's username alias 3| -|Alias 4|string|False|The user's username alias 4| -|Aliases|object|False|The user's aliases| -|Created|integer|False|The user's creation date as a UNIX timestamp| -|Email|string|False|The user's email address| -|First Name|string|False|The user's given name| -|Groups|[]group|False|List of groups to which this user belongs| -|Is Enrolled|boolean|False|Whether the user has a phone, hardware token, U2F token, WebAuthn security key, or other WebAuthn method available for authentication| -|Last Directory Sync|integer|False|An integer indicating the last update to the user via directory sync as a Unix timestamp, or null if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo| -|Last Login|integer|False|An integer indicating the last time this user logged in, as a Unix timestamp, or null if the user has not logged in| -|Last Name|string|False|The user's surname| -|Notes|string|False|Notes about this user| -|Phones|[]phoneUser|False|A list of phones that this user can use| -|Real Name|string|False|The user's real name or full name| -|Status|string|False|The user's status| -|Tokens|[]token|False|A list of tokens that this user can use| -|User ID|string|False|The user's ID| -|Username|string|False|The user's username| -|Web Auth Credentials|[]webauthnaredentials|False|A list of WebAuthn authenticators that this user can use| - -#### webauthnaredentials - -|Name|Type|Required|Description| -|----|----|--------|-----------| -|Credential Name|string|False|Free-form label for the WebAuthn credential| -|Credential Name|integer|False|The date the WebAuthn credential was registered in Duo| -|Label|string|False|Indicates the type of WebAuthn credential| -|User|object|False|Selected information about the end user attached to the WebAuthn credential| -|WebAuthnKey|string|False|The WebAuthn credential's registration identifier| +### Custom Types + +**phoneUser** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Activated|boolean|None|False|Whether the phone has already been activated for Duo Mobile|True| +|Capabilities|[]string|None|False|List of factors that can be used with the phone|['push']| +|Encrypted|string|None|False|The encryption status of an Android or iOS device file system|Encrypted| +|Extension|string|None|False|Extension of the phone|ExampleExtension| +|Fingerprint|string|None|False|Whether an Android or iOS phone is configured for biometric verification|Configured| +|Last Seen|string|None|False|An integer indicating the timestamp of the last contact between Duo's service and the activated Duo Mobile app installed on the phone|2023-05-12 07:34:09| +|Model|string|None|False|The phone's model|Apple iPhone 11 Pro| +|Name|string|None|False|Free-form label for the phone|ExampleName| +|Number|string|None|False|Number|123456789| +|Phone ID|string|None|False|The phone's ID|ABCDEABC00ABC00ABCDE| +|Platform|string|None|False|The phone platform|unknown| +|Postdelay|string|None|False|The time (in seconds) to wait after the extension is dialed and before the speaking the prompt|3600| +|Predelay|string|None|False|The time (in seconds) to wait after the number picks up and before dialing the extension|3600| +|Screen Lock|string|None|False|Whether screen lock is enabled on an Android or iOS phone|Locked| +|SMS Passcodes Sent|boolean|None|False|Whether the SMS passcodes has been sent to this phone|True| +|Type|string|None|False|Whether an iOS or Android device is jailbroken or rooted|Tampered| +|Type|string|None|False|The type of phone|mobile| + +**group** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Description|string|None|False|The group's description|Example Description| +|Group ID|string|None|False|The group's ID|ABCDEABC00ABC00ABCDE| +|Name|string|None|False|The group's name|Example Group Name| +|Status|string|None|False|The group's authentication status|Active| + +**token** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Admins|[]object|None|False|A list of administrators associated with this hardware token|[]| +|Serial|string|None|False|The serial number of the hardware token|123456| +|Token ID|string|None|False|The hardware token's unique ID|ABCDEABC00ABC00ABCDE| +|Type|string|None|False|The type of hardware token|type1| +|Users|[]object|None|False|A list of end users associated with this hardware token|[]| + +**webauthnaredentials** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Credential Name|string|None|False|Free-form label for the WebAuthn credential|Key1| +|Credential Name|integer|None|False|The date the WebAuthn credential was registered in Duo|1550674764| +|Label|string|None|False|Indicates the type of WebAuthn credential|Security Key| +|User|object|None|False|Selected information about the end user attached to the WebAuthn credential|{}| +|WebAuthnKey|string|None|False|The WebAuthn credential's registration identifier|ABCDEABC00ABC00ABCDE| + +**user** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Alias 1|string|None|False|The user's username alias 1|example-alias-1| +|Alias 2|string|None|False|The user's username alias 2|example-alias-2| +|Alias 3|string|None|False|The user's username alias 3|example-alias-3| +|Alias 4|string|None|False|The user's username alias 4|example-alias-4| +|Aliases|object|None|False|The user's aliases|{}| +|Created|integer|None|False|The user's creation date as a UNIX timestamp|1684238502| +|Email|string|None|False|The user's email address|example@user.com| +|First Name|string|None|False|The user's given name|Example| +|Groups|[]group|None|False|List of groups to which this user belongs|[]| +|Is Enrolled|boolean|None|False|Whether the user has a phone, hardware token, U2F token, WebAuthn security key, or other WebAuthn method available for authentication|True| +|Last Directory Sync|integer|None|False|An integer indicating the last update to the user via directory sync as a Unix timestamp, or null if the user has never synced with an external directory or if the directory that originally created the user has been deleted from Duo|1234| +|Last Login|integer|None|False|An integer indicating the last time this user logged in, as a Unix timestamp, or null if the user has not logged in|1234| +|Last Name|string|None|False|The user's surname|Example| +|Notes|string|None|False|Notes about this user|Example Note| +|Phones|[]phoneUser|None|False|A list of phones that this user can use|[]| +|Real Name|string|None|False|The user's real name or full name|Test User| +|Status|string|None|False|The user's status|active| +|Tokens|[]token|None|False|A list of tokens that this user can use|[]| +|User ID|string|None|False|The user's ID|ABCDEABC00ABC00ABCDE| +|Username|string|None|False|The user's username|test-username| +|Web Auth Credentials|[]webauthnaredentials|None|False|A list of WebAuthn authenticators that this user can use|[]| + +**location** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|City|string|None|False|The city name|Ann Arbor| +|Country|string|None|False|The country name|United States| +|State|string|None|False|The state, county, province, or prefecture|Michigan| + +**keyNamePair** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Key|string|None|False|The integration key|DIY231J8BR23QK4UKBY8| +|Name|string|None|False|The name|Microsoft Azure Active Directory| + +**authlogUser** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Groups|[]string|None|False|Duo group membership information for the user|['Duo Users']| +|Key|string|None|False|The ID of the user|DU3KC77WJ06Y5HIV7XKQ| +|Name|string|None|False|The name of the user|user@example.com| + +**authDevice** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|IP Address|string|None|False|The IP address of the authentication device|198.51.100.1| +|Key|string|None|False|The Duo identifier of the authentication device|DP5BJ05HI4WRBVI4Q7JF| +|Location|location|None|False|The GeoIP location of the authentication device|{}| +|Name|string|None|False|The name of the authentication device|My iPhone X| + +**accessDevice** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Access Device|string|None|False|The web browser used for access|Chrome| +|Browser Version|string|None|False|The browser version|67.0.3396.99| +|Flash Version|string|None|False|The Flash plugin version used|uninstalled| +|Hostname|string|None|False|The hostname|example-hostname| +|IP Address|string|None|False|The access device's IP address|198.51.100.1| +|Is Encryption Enabled|string|None|False|Reports the disk encryption state as detected by the Duo Device Health app. One of true, false, or unknown|True| +|Is Firewall Enabled|string|None|False|Reports the firewall state as detected by the Duo Device Health app. One of true, false, or unknown|True| +|Is Password Set|string|None|False|Reports the system password state as detected by the Duo Device Health app. One of true, false, or unknown|True| +|Java Version|string|None|False|The Java plugin version used|uninstalled| +|Location|location|None|False|The GeoIP location of the access device|{}| +|Operating System|string|None|False|The device operating system name|Mac OS X| +|Operating System Version|string|None|False|The device operating system version|10.14.1| + +**trustAssessmentObject** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Features Version|string|None|False|The feature version for the risk-based authentication trust assessment|3.0| +|Model Version|string|None|False|The model version for the risk-based authentication trust assessment|2022.07.19.001| +|Policy Enabled|boolean|None|False|Denotes if risk-based authentication was enabled by the policy under which the trust assessment was evaluated|False| +|Reason|string|None|False|The reason behind the trust assessment level|Normal level of trust; no detection of known attack pattern| +|Trust Level|string|None|False|The trust assessment level. Can be one of: ERROR, LOW, NORMAL, UNKNOWN, or UNSET|NORMAL| + +**adaptiveTrustAssessments** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|More Secure Auth|trustAssessmentObject|None|False|Trust assessment information for Risk-Based Factor Selection|{}| +|Remember Me|trustAssessmentObject|None|False|Trust assessment information for Risk-Based Remembered Devices|{}| + +**authLog** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Access Device|accessDevice|None|False|Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo's inline browser prompt|{}| +|Adaptive Trust Assessments|adaptiveTrustAssessments|None|False|Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied|{}| +|Alias|string|None|False|The username alias used to log in. No value if the user logged in with their username instead of a username alias|test| +|Application|keyNamePair|None|False|Information about the application accessed|{}| +|Auth Device|authDevice|None|False|Information about the device used to approve or deny authentication|{}| +|Email|string|None|False|The email address of the user|user@example.com| +|Event Type|string|None|False|The type of activity logged|authentication| +|Factor|string|None|False|The authentication factor|duo_push| +|ISO8601 Timestamp|string|None|False|ISO8601 timestamp of the event|2020-02-13 18:56:20.351346+00:00| +|OOD Software|string|None|False|If authentication was denied due to out-of-date software, shows the name of the software|Chrome| +|Reason|string|None|False|The reason for the authentication attempt result|user_approved| +|Result|string|None|False|The result of the authentication attempt. One of: 'success', 'denied', 'failure', 'error', or 'fraud'|success| +|Timestamp|number|None|False|An integer indicating the Unix timestamp of the event|1581620180| +|Transaction ID|string|None|False|The transaction ID of the event|9de5069c-5afe-602b-2ea0-a04b66beb2c0| +|User|authlogUser|None|False|Information about the authenticating user|{}| + +**explanation** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Summary|string|None|False|Summary of the event|example-user has not accessed this application recently| +|Type|string|None|False|Type of the event|NEW_IKEY| + +**priorityReason** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Label|string|None|False|The label of the priority reason for the event's match|country| +|Type|string|None|False|The type of priority reason for the event's match|CN| + +**log** + +|Name|Type|Default|Required|Description|Example| +| :--- | :--- | :--- | :--- | :--- | :--- | +|Access Device|accessDevice|None|False|Browser, plugin, and operating system information for the endpoint used to access the Duo-protected resource. Values present only when the application accessed features Duo's inline browser prompt|{}| +|Action|string|None|False|The type of change that was performed|user_update| +|Adaptive Trust Assessments|adaptiveTrustAssessments|None|False|Risk-based authentication information. Values present only when the application accessed features Duo's inline browser prompt and has a Duo Risk-Based Authentication policy applied|{}| +|Alias|string|None|False|The username alias used to log in. No value if the user logged in with their username instead of a username alias|test| +|Application|keyNamePair|None|False|Information about the application accessed|{}| +|Auth Device|authDevice|None|False|Information about the device used to approve or deny authentication|{}| +|Bypass Status Enabled|integer|None|False|An integer indicating the Unix timestamp in milliseconds when bypass status was enabled for the user or group|1604337058989| +|Description|string|None|False|String detailing what changed|{"notes": "Joe asked for their nickname to be displayed instead of Joseph.", "realname": "Joe Smith"}| +|Email|string|None|False|The email address of the user|user@example.com| +|Enabled By|keyNamePair|None|False|The application or the administrator that enabled bypass status|{}| +|Enabled For|keyNamePair|None|False|The user or group with bypass status|{}| +|Event Type|string|None|False|The type of activity logged|authentication| +|Explanations|[]explanation|None|False|An array of objects describing why Trust Monitor surfaced the event|[]| +|Factor|string|None|False|The authentication factor|duo_push| +|From Common Netblock|boolean|None|False|A boolean describing if this event was created from a common IP netblock|True| +|From New User|boolean|None|False|A boolean describing if this event was created for a new user|False| +|ISO8601 Timestamp|string|None|False|ISO8601 timestamp of the event|2020-02-13 18:56:20.351346+00:00| +|Log Type|string|None|False|Type of the log|auth| +|Low Risk IP|boolean|None|False|A boolean describing if this event was created from an IP address identified in the Risk Profile configuration as a low risk IP address|False| +|Object|string|None|False|The object that was acted on|jsmith| +|OOD Software|string|None|False|If authentication was denied due to out-of-date software, shows the name of the software|Chrome| +|Priority Event|boolean|None|False|A boolean describing if the event matches the Risk Profile configuration|False| +|Priority Reasons|[]priorityReason|None|False|An array of objects describing how the event matches the Trust Monitor Risk Profile configuration|[]| +|Reason|string|None|False|The reason for the authentication attempt result|user_approved| +|Result|string|None|False|The result of the authentication attempt. One of: 'success', 'denied', 'failure', 'error', or 'fraud'|success| +|Sekey|string|None|False|The unique identifier for this event|SEDOR9BP00L23C6YUH5| +|State|string|None|False|A string describing the state of the event|new| +|State Updated Timestamp|integer|None|False|An integer indicating the Unix timestamp in milliseconds of the last change to the state of the event|1675893605269| +|Surfaced Auth|authLog|None|False|An object which represents the actual authentication|{}| +|Surfaced Timestamp|integer|None|False|An integer indicating the Unix timestamp in milliseconds when the event was surfaced by Trust Monitor|1675893605269| +|Timestamp|number|None|False|An integer indicating the Unix timestamp of the event|1581620180| +|Triage Event URI|string|None|False|A string representing the URI of the security event, which a Duo administrator can use to view and process the surfaced event in the Duo Admin Panel|https://example.com| +|Triaged As Interesting|boolean|None|False|A boolean describing if this event was triaged as being interesting or not interesting|False| +|Transaction ID|string|None|False|The transaction ID of the event|9de5069c-5afe-602b-2ea0-a04b66beb2c0| +|Type|string|None|False|The type of event|auth| +|User|authlogUser|None|False|Information about the authenticating user|{}| +|Username|string|None|False|The full name of the administrator who performed the action|admin| ## Troubleshooting @@ -1021,6 +681,7 @@ A User ID can be obtained by passing a username to the Get User Status action. # Version History +* 4.3.0 - Monitor Logs task: Added inputs for collecting events and logs. Updated 403 error handling * 4.2.2 - Monitor Logs task: updated unit tests * 4.2.1 - Monitor Logs task: updated timestamp handling * 4.2.0 - Monitor Logs task: removed formatting of task output diff --git a/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/schema.py b/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/schema.py index 78e907470f..54a24bcb24 100755 --- a/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/schema.py +++ b/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/schema.py @@ -8,7 +8,8 @@ class Component: class Input: - pass + COLLECTADMINLOGS = "collectAdminLogs" + COLLECTTRUSTMONITOREVENTS = "collectTrustMonitorEvents" class State: @@ -21,7 +22,27 @@ class Output: class MonitorLogsInput(insightconnect_plugin_runtime.Input): schema = json.loads(r""" - {} + { + "type": "object", + "title": "Variables", + "properties": { + "collectAdminLogs": { + "type": "boolean", + "title": "Collect Duo Admin Logs", + "description": "Whether to collect Admin logs (note requires appropriate level of Duo Admin license)", + "default": true, + "order": 2 + }, + "collectTrustMonitorEvents": { + "type": "boolean", + "title": "Collect Duo Trust Monitor Events", + "description": "Whether to collect Trust Monitor events (note requires appropriate level of Duo Admin license)", + "default": true, + "order": 1 + } + }, + "definitions": {} +} """) def __init__(self): diff --git a/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/task.py b/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/task.py index f8a65635e2..d6e57699fb 100755 --- a/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/task.py +++ b/plugins/duo_admin/komand_duo_admin/tasks/monitor_logs/task.py @@ -105,6 +105,9 @@ def run(self, params={}, state={}): # noqa: C901 trust_monitor_next_page_params = state.get(self.TRUST_MONITOR_NEXT_PAGE_PARAMS) auth_logs_next_page_params = state.get(self.AUTH_LOGS_NEXT_PAGE_PARAMS) admin_logs_next_page_params = state.get(self.ADMIN_LOGS_NEXT_PAGE_PARAMS) + collect_trust_monitor_events = params.get(MonitorLogsInput.COLLECTTRUSTMONITOREVENTS, True) + collect_admin_logs = params.get(MonitorLogsInput.COLLECTADMINLOGS, True) + if last_collection_timestamp: # Previously only one timestamp was held (the end of the collection window) # This has been superceded by a latest timestamp per log type @@ -134,66 +137,72 @@ def run(self, params={}, state={}): # noqa: C901 previous_auth_log_hashes = state.get(self.PREVIOUS_AUTH_LOG_HASHES, []) new_trust_monitor_event_hashes, new_admin_log_hashes, new_auth_log_hashes = [], [], [] - # Get trust monitor events - mintime, maxtime, get_next_page = self.get_parameters_for_query( - TRUST_MONITOR_EVENTS_LOG_TYPE, - now, - trust_monitor_last_log_timestamp, - trust_monitor_next_page_params, - backward_comp_first_run, - ) - - if (get_next_page and trust_monitor_next_page_params) or not get_next_page: - trust_monitor_events, trust_monitor_next_page_params = self.get_trust_monitor_event( - mintime, maxtime, trust_monitor_next_page_params - ) - new_trust_monitor_events, new_trust_monitor_event_hashes = self.compare_hashes( - previous_trust_monitor_event_hashes, trust_monitor_events - ) - new_logs.extend(new_trust_monitor_events) - state[self.TRUST_MONITOR_LAST_LOG_TIMESTAMP] = self.get_highest_timestamp( + if collect_trust_monitor_events: + # Get trust monitor events + mintime, maxtime, get_next_page = self.get_parameters_for_query( + TRUST_MONITOR_EVENTS_LOG_TYPE, + now, trust_monitor_last_log_timestamp, - new_trust_monitor_events, + trust_monitor_next_page_params, backward_comp_first_run, - TRUST_MONITOR_EVENTS_LOG_TYPE, ) - self.logger.info(f"{len(new_trust_monitor_events)} trust monitor events retrieved") - if new_trust_monitor_event_hashes: - state[self.PREVIOUS_TRUST_MONITOR_EVENT_HASHES] = new_trust_monitor_event_hashes - - if trust_monitor_next_page_params: - state[self.TRUST_MONITOR_NEXT_PAGE_PARAMS] = trust_monitor_next_page_params - has_more_pages = True - elif state.get(self.TRUST_MONITOR_NEXT_PAGE_PARAMS): - state.pop(self.TRUST_MONITOR_NEXT_PAGE_PARAMS) - - # Get admin logs - mintime, maxtime, get_next_page = self.get_parameters_for_query( - ADMIN_LOGS_LOG_TYPE, - now, - admin_logs_last_log_timestamp, - admin_logs_next_page_params, - backward_comp_first_run, - ) - if (get_next_page and admin_logs_next_page_params) or not get_next_page: - admin_logs, admin_logs_next_page_params = self.get_admin_logs( - mintime, maxtime, admin_logs_next_page_params - ) - new_admin_logs, new_admin_log_hashes = self.compare_hashes(previous_admin_log_hashes, admin_logs) - new_logs.extend(new_admin_logs) - state[self.ADMIN_LOGS_LAST_LOG_TIMESTAMP] = self.get_highest_timestamp( - admin_logs_last_log_timestamp, new_admin_logs, backward_comp_first_run, ADMIN_LOGS_LOG_TYPE + if (get_next_page and trust_monitor_next_page_params) or not get_next_page: + trust_monitor_events, trust_monitor_next_page_params = self.get_trust_monitor_event( + mintime, maxtime, trust_monitor_next_page_params + ) + new_trust_monitor_events, new_trust_monitor_event_hashes = self.compare_hashes( + previous_trust_monitor_event_hashes, trust_monitor_events + ) + new_logs.extend(new_trust_monitor_events) + state[self.TRUST_MONITOR_LAST_LOG_TIMESTAMP] = self.get_highest_timestamp( + trust_monitor_last_log_timestamp, + new_trust_monitor_events, + backward_comp_first_run, + TRUST_MONITOR_EVENTS_LOG_TYPE, + ) + self.logger.info(f"{len(new_trust_monitor_events)} trust monitor events retrieved") + if new_trust_monitor_event_hashes: + state[self.PREVIOUS_TRUST_MONITOR_EVENT_HASHES] = new_trust_monitor_event_hashes + + if trust_monitor_next_page_params: + state[self.TRUST_MONITOR_NEXT_PAGE_PARAMS] = trust_monitor_next_page_params + has_more_pages = True + elif state.get(self.TRUST_MONITOR_NEXT_PAGE_PARAMS): + state.pop(self.TRUST_MONITOR_NEXT_PAGE_PARAMS) + else: + self.logger.info(f"Collect trust monitor events set to {collect_trust_monitor_events}. Do not attempt to collect trust monitor events") + + if collect_admin_logs: + # Get admin logs + mintime, maxtime, get_next_page = self.get_parameters_for_query( + ADMIN_LOGS_LOG_TYPE, + now, + admin_logs_last_log_timestamp, + admin_logs_next_page_params, + backward_comp_first_run, ) - self.logger.info(f"{len(new_admin_logs)} admin logs retrieved") - if new_admin_log_hashes: - state[self.PREVIOUS_ADMIN_LOG_HASHES] = new_admin_log_hashes - if admin_logs_next_page_params: - state[self.ADMIN_LOGS_NEXT_PAGE_PARAMS] = admin_logs_next_page_params - has_more_pages = True - elif state.get(self.ADMIN_LOGS_NEXT_PAGE_PARAMS): - state.pop(self.ADMIN_LOGS_NEXT_PAGE_PARAMS) + if (get_next_page and admin_logs_next_page_params) or not get_next_page: + admin_logs, admin_logs_next_page_params = self.get_admin_logs( + mintime, maxtime, admin_logs_next_page_params + ) + new_admin_logs, new_admin_log_hashes = self.compare_hashes(previous_admin_log_hashes, admin_logs) + new_logs.extend(new_admin_logs) + state[self.ADMIN_LOGS_LAST_LOG_TIMESTAMP] = self.get_highest_timestamp( + admin_logs_last_log_timestamp, new_admin_logs, backward_comp_first_run, ADMIN_LOGS_LOG_TYPE + ) + self.logger.info(f"{len(new_admin_logs)} admin logs retrieved") + + if new_admin_log_hashes: + state[self.PREVIOUS_ADMIN_LOG_HASHES] = new_admin_log_hashes + if admin_logs_next_page_params: + state[self.ADMIN_LOGS_NEXT_PAGE_PARAMS] = admin_logs_next_page_params + has_more_pages = True + elif state.get(self.ADMIN_LOGS_NEXT_PAGE_PARAMS): + state.pop(self.ADMIN_LOGS_NEXT_PAGE_PARAMS) + else: + self.logger.info(f"Collect admin logs set to {collect_admin_logs}. Do not attempt to collect admin logs") # Get auth logs mintime, maxtime, get_next_page = self.get_parameters_for_query( diff --git a/plugins/duo_admin/komand_duo_admin/util/api.py b/plugins/duo_admin/komand_duo_admin/util/api.py index d8da3cd6a0..2d36daf736 100644 --- a/plugins/duo_admin/komand_duo_admin/util/api.py +++ b/plugins/duo_admin/komand_duo_admin/util/api.py @@ -169,7 +169,6 @@ def make_request(self, method: str, path: str, params: dict = {}) -> requests.Re self.logger.info(f"403 Response data returned for reference: {response.json()}") return {} self._handle_exceptions(response, path) - self.logger.info(f"Response data returned: {response.text}") if 200 <= response.status_code < 300: return response raise PluginException(preset=PluginException.Preset.UNKNOWN, data=response.text) diff --git a/plugins/duo_admin/plugin.spec.yaml b/plugins/duo_admin/plugin.spec.yaml index 67a89feb0c..55b2bd0386 100644 --- a/plugins/duo_admin/plugin.spec.yaml +++ b/plugins/duo_admin/plugin.spec.yaml @@ -1267,6 +1267,21 @@ tasks: monitor_logs: title: Monitor Logs description: Monitor administrator, authentication and trust monitor event logs + input: + collectTrustMonitorEvents: + title: Collect Duo Trust Monitor Events + description: Whether to collect Trust Monitor events (note requires appropriate level of Duo Admin license) + type: boolean + required: false + default: true + example: false + collectAdminLogs: + title: Collect Duo Admin Logs + description: Whether to collect Admin logs (note requires appropriate level of Duo Admin license) + type: boolean + required: false + default: true + example: false output: logs: title: Logs