Active Directory

Overview

Active Directory is a directory service from Microsoft that allows network administrators to manage users, domains, and objects within a network. D3's integration with Active Directory can perform operations such as disabling/enabling user accounts, resetting passwords, retrieving user and computer information, listing users, and more.

D3 SOAR is providing REST operations to function with Active Directory.

Active Directory is available for use in:

D3 SOAR	V12.7.83.0+
Category	Identity Access Management
Deployment Options	Option I, Option III

Known Limitations

A few known limitations of Active Directory are listed below.

A domain controller can create slightly less than 2.15 billion objects during its lifetime.
Users, groups, and computer accounts (security principals) can be members of a maximum of approximately 1,015 groups.
A limit of 999 Group Policy Objects (GPOs) can be applied to a user account or a computer account.
Avoid performing more than 5,000 operations per LDAP transaction when writing scripts or applications or an LDAP transaction.
Active Directory does not support Microsoft Entra ID Protection.

Please refer to https://jumpcloud.com/blog/active-directory-faq for more information.

Connection

To connect to Active Directory from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server Address	The server URL with a port number. If you need to use LDAPS, the port number is 636. Add the port number for LDAPS after the server address, separated by a colon (:).	example server address
Domain Name (FQDN)	The domain name for Active Directory.	sample domain
Username	The username of the Active Directory user to connect to.	Administrator
Password	The password of the Active Directory user to connect to.	Yourpassword

Permission Requirements

Commands	Required Permissions
Disable AD User Account	Account Operators
Enable AD User Account	Account Operators
Find Users	Domain Users
Get Users by Username	Domain Users
Get Computer	Domain Users
Get User logon/logoff Information from AD	Event Log Readers
Get User By Group	Domain Users
Reset User Password	*Change password and Rest password permissions for the desired user
Test Connection	Domain Users

* Upon creating a user, the default assigned role is Domain Users, which grants the least amount of permissions. Additional permissions may be required to run certain commands. For instructions on granting permissions, please refer to steps 1 to 4 of Modifying a User (Granting Permissions and Modifying Account Options).

* To run the Reset Password command for a desired user, permissions must be granted to that user. Follow the steps below:

Right-click on the desired user (in this example, User 2) and select Properties.
Select the Security tab. If the Security tab is not visible, go to View and ensure Advanced Features is checked. The Security tab will be then displayed.
Under Group or user names section, locate the user that is being used for the connection (DOCuser in this example). Under Permissions for [Username] (DOCuser in this case), allow the Change password and Reset password permissions. Click Apply.
Once this setting has been configured, the connection with the configured user or group (DOCuser in this example) can be used to reset the password for the desired user (User2 in this case).

Configuring Active Directory to Work with D3 SOAR

Creating a User

Access Azure Directory Users and Computers. Locate the Users folder under your domain in the left navigation panel and right-click on it. Select New > User.
The New Object - User window will appear. Fill in the user's basic information including First Name, Last Name, User logon name etc. Click Next. Note: The User logon name is the username you will need to input into D3 SOAR when configuring the integration connection.
Enter a new password for the user twice for confirmation. You can also choose to set the password attributes for the user. Click Next.
Review the configured user settings. Take note of the user logon name, excluding the domain name (e.g. @domain.name) as this will be required for the Username field when establishing the integration connection in D3 SOAR.

Modifying a User (Granting Permissions and Modifying Account Options)

Access Azure Directory Users and Computers and navigate to the Users folder under your domain in the left navigation panel. Right-click on the user you want to modify and select Properties.
The corresponding user's properties window will appear. Select the Member Of tab.
In the Member Of tab, click Add. The Select Group window will appear. In the Enter the object names to select field, enter your desired permissions, and select Check Names. Please refer to Permission Requirements for more details. Then click OK.
Click Apply to apply the changes.
If you want to modify the user's account settings, select the Account tab. Configure the settings as desired, then click Apply and OK.

Identifying the Domain Name

The domain name required to establish the integration in D3 SOAR can be found in Active Directory Users and Computers in the left navigation panel.

Configuring D3 SOAR to Work with Active Directory

Log in to D3 SOAR.
Find the Active Directory integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Active Directory in the search box to find the integration, then click it to select it.
4. Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Active Directory.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server Address.
  2. Input the Domain Name. See Identifying the Domain Name for more details.
  3. Input your account Username. See step 2 of Creating a User.
  4. Input your account Password. See step 3 of Creating a User.
9. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click Add to create and add the configured connection.

Commands

Active Directory includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Active Directory to Work with D3 SOAR for details.

Disable AD User Accounts

Disables the specified Active Directory user accounts.

Reader Note

Changes may not be reflected on the Active Directory application immediately after running this command. To view the changes, please refresh the AD page.
This command required the Account Operators permission. If insufficient permissions are granted, the command may still return a success message. However, this does not guarantee the successful execution of the disabling process. The user status will remain unchanged when you refresh the page.
Avoid disabling the account that your connection is currently using, as doing so will render the connection unusable for other commands.

Input

Input Parameter	Required/Optional	Description	Example
Usernames	Required	The usernames of the AD user accounts to disable.	["sample username"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "User": "sample username",
        "Status": "Success"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "User": "sample username",
        "Status": "Success"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Status": [
        "Success"
    ],
    "User": [
        "span"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

User	Status
span	Success

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Disable AD User Accounts failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The user is not found in AD.

Error Sample Data

Disable AD User Accounts failed.

Status Code: 404.

Message: The user is not found in AD.

Enable AD User Accounts

Enables the specified Active Directory user accounts.

Reader Note

Changes may not be reflected on the Active Directory application immediately after running this command. To view the changes, please refresh the AD page.
This command requires the Account Operators permission. If insufficient permissions are granted, the command may still return a success message. However, this does not guarantee the successful execution of the enabling process. The user status will remain unchanged when you refresh the page.

Input

Input Parameter	Required/Optional	Description	Example
Usernames	Optional	The usernames of the AD user accounts to enable.	["sample username"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "User": "span",
        "Status": "Success"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "User": "span",
        "Status": "Success"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Status": [
        "Success"
    ],
    "User": [
        "span"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

User	Status
span	Success

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Enable AD User Accounts failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The user is not found in AD.

Error Sample Data

Enable AD User Accounts failed.

Status Code: 404.

Message: The user is not found in AD.

Find Users

Returns detailed user information based on the specified query criteria.

Reader Note

All input parameters are labeled optional. However, at least one of the input parameters must be defined in order to run this command. Multiple parameters can be defined simultaneously, but they will be processed using an "and" logic.

Input

Input Parameter	Required/Optional	Description	Example
First Name	Optional	The whole or partial first name to query users. Use an asterisk () to partially match the name. For instance, if the name begins with "An," enter "An." If the name ends with "na," enter "na." If the name contains "nn," enter "nn*." If the name is "Anna," simply enter "Anna." Note: At least one of the input parameters must be defined in order to run this command.	An*
Last Name	Optional	The whole or partial last name to query users. Use an asterisk () to partially match the name. For instance, if the name begins with "Gil", enter "Gil". If the name ends with "pie", enter "pie". If the name contains "illesp", enter "illesp*". If the name is "Gillespie," simply enter "Gillespie". Note: At least one of the input parameters must be defined in order to run this command.	Gilles*
Common Name	Optional	The whole or partial common name of users to query users. Use an asterisk () to partially match the name. For instance, if the common name begins with "User", enter "User". If the common name ends with "er1", enter "er1". If the common name contains "ser", enter "ser*". If the name is "User1", simply enter "User1". Note: At least one of the input parameters must be defined in order to run this command.	lles
Email Address	Optional	The whole or partial user email addresses to query users. Use an asterisk () to partially match the email address. For instance, if the email address begins with "User", enter "User". If the email address ends with "abc.com", enter "abc.com". If the email address contains "ser", enter "ser*". If the email address is "user1@abc.com", simply enter "user1@abc.com". Note: At least one of the input parameters must be defined in order to run this command.	test@*

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

[
    {
        "UserID": "{***-***-***-***-***}",
        "EmployeID": "***",
        "UserPrincipalName": "test@example.com",
        "LoginName": "test",
        "FirstName": "test",
        "Initials": "te",
        "LastName": "name",
        "DisplayName": "test name",
        "Title": "Cyber Security Engineer",
        "Description": "In charge of cyber security",
        "BusinessUnit": "London Office",
        "Department": "Lab",
        "Division": "IT Service Division",
        "Company": "D3 Security",
        "Address1": "",
        "Address2": "",
        "State": "BC",
        "StreetAddress": "700 Pender ST",
        "City": "Vancouver",
        "Country": "Canada",
        "Zip": "V3K 8O9",
        "POBox": "Po Box 1",
        "EmailAddress": "test@example.com",
        "DateCreated": "2021-06-07 23:02:23",
        "DateLastModified": "2021-07-26 22:19:54",
        "DateOfExpiry": "",
        "AccountIsActive": true,
        "Manager": "CN=Administrator,CN=Users,DC=test,DC=local",
        "MemberOf": [
            "CN=Testgroup,CN=Users,DC=test,DC=local",
            "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=test,DC=local",
            "CN=Administrators,CN=Builtin,DC=test,DC=local"
        ],
        "DistinguishedName": "CN=test,CN=Users,DC=test,DC=local"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "UserID": "{***-***-***-***-***}",
        "EmployeID": "***",
        "UserPrincipalName": "test@example.com",
        "LoginName": "test",
        "FirstName": "name",
        "Initials": "te",
        "LastName": "name",
        "DisplayName": "test name",
        "Title": "Cyber Security Engineer",
        "Description": "In charge of cyber security",
        "BusinessUnit": "London Office",
        "Department": "Lab",
        "Division": "IT Service Division",
        "Company": "D3 Security",
        "Address1": "",
        "Address2": "",
        "State": "BC",
        "StreetAddress": "700 Pender ST",
        "City": "Vancouver",
        "Country": "Canada",
        "Zip": "V3K 8O9",
        "POBox": "Po Box 1",
        "EmailAddress": "test@example.com",
        "DateCreated": "2021-06-07 23:02:23",
        "DateLastModified": "2021-07-26 22:19:54",
        "DateOfExpiry": "",
        "AccountIsActive": true,
        "Manager": "CN=Administrator,CN=Users,DC=test,DC=local",
        "MemberOf": [
            "CN=Testgroup,CN=Users,DC=test,DC=local",
            "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=test,DC=local",
            "CN=Administrators,CN=Builtin,DC=test,DC=local"
        ],
        "DistinguishedName": "CN=test,CN=Users,DC=test,DC=local"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DistinguishedNames": [
        "CN=user1,CN=Users,DC=test,DC=local"
    ],
    "UserIDs": [
        "{***-***-***-***-***}"
    ],
    "EmailAddresses": [
        "test@example.com"
    ],
    "LoginNames ": [
        "test"
    ],
    "Divisions": [
        "Information Technology Service Division"
    ],
    "BusinessUnits": [
        "Digital & Transformation"
    ],
    "Departments": [
        "IT Department"
    ],
    "AccountIsActive": [
        true
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

USERID	EMPLOYEID	USERPRINCIPALNAME	LOGINNAME	FIRSTNAME	INITIALS	LASTNAME	DISPLAYNAME	TITLE	DESCRIPTION	BUSINESSUNIT	DEPARTMENT	DIVISION	COMPANY	ADDRESS1	ADDRESS2	STATE	STREETADDRESS	CITY	COUNTRY	ZIP	POBOX	EMAILADDRESS	DATECREATED	DATELASTMODIFIED	DATEOFEXPIRY	ACCOUNTISACTIVE	MANAGER	MEMBEROF	DISTINGUISHEDNAME
{*----**}		test@example.com	test	user	te	test	test user	Cyber Security Engineer	In charge of cyber security	London Office	Lab	IT Service Division	D3 Security			BC	700 Pender ST	Vancouver	Canada	V3K 8O9	Po Box 1	test@example.com	2021-06-07 23:02:23	2021-07-26 22:19:54		True	CN=Administrator,CN=Users,DC=test,DC=local	[ "CN=Testgroup,CN=Users,DC=test,DC=local", "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=d3cyber7,DC=local", "CN=Administrators,CN=Builtin,DC=d3cyber7,DC=local" ]	CN=test,CN=Users,DC=test,DC=local

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Find Users failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: Users not found.

Error Sample Data

Find Users failed.

Status Code: 404.

Message: Users not found.

Get Users by Username

Retrieves detailed information on the specified Active Directory user(s).

Input

Input Parameter

Required/Optional

Description

Example

Usernames

Required

The login username(s) to retrieve corresponding user info.

[

"user4"

]

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

[
    {
        "LoginName": "Test User",
        "FirstName": "Test",
        "MiddleInitial": "",
        "LastName": "User",
        "Address1": "",
        "Address2": "",
        "Title": "",
        "Company": "",
        "City": "",
        "State": "",
        "Country": "",
        "Zip": "",
        "Phone": "",
        "Extension": "",
        "Fax": "",
        "EmailAddress": "test@example.com",
        "ChallengeQuestion": "",
        "ChallengeResponse": "",
        "MemberCompany": "",
        "CompanyRelationShipExists": "",
        "Status": "",
        "AssignedSalesPerson": "",
        "AcceptTAndC": "",
        "Jobs": "",
        "Email_Overnight": "false",
        "Email_DailyEmergingMarkets": "false",
        "Email_DailyCorporateAlerts": "false",
        "AssetMgtRange": "",
        "ReferralCompany": "",
        "CorporateAffiliation": "",
        "DateCreated": "4/30/2017 12:43:27 AM",
        "DateLastModified": "2/11/2020 12:02:33 AM",
        "DateOfExpiry": "",
        "AccountIsActive": "True",
        "Manager": "",
        "MemberOf": "CN=Domain Admins,CN=Users,DC=qa,DC=van",
        "DistinguishedName": "CN=Tset,CN=Users,DC=qa,DC=van",
        "Description": "An user",
        "EmployeeID": "12345"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 enriches the Context Data by extracting the data from the paths $[*].User, $[*].EmailAddress, $[*].MemberOf, $[*].DistinguishedName, $[*].EmployeeID, and $[*].pwdLastSet in the returned raw data.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "User": "span",
        "EmailAddress": "test@example.com",
        "MemberOf": "CN=Domain Admins,CN=Users,DC=qa,DC=van",
        "DistinguishedName": "CN=Tets User,CN=Users,DC=qa,DC=van",
        "EmployeeID": "12345"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DistinguishedName": [
        "CN=Star Pan,CN=Users,DC=qa,DC=van"
    ],
    "EmailAddress": [
        "test@example.com"
    ],
    "MemberOf": [
        "CN=Domain Admins,CN=Users,DC=qa,DC=van"
    ],
    "User": [
        "span"
    ],
    "EmployeeID": [
        "12345"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

User	EmailAddress	MemberOf	DistinguishedName
span	test@example.com	CN=Domain Admins,CN=Users,DC=qa,DC=van	CN=Test User,CN=Users,DC=qa,DC=van

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Get Users by Username failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The user is not found in AD.

Error Sample Data

Get Users by Username failed.

Status Code: 404.

Message: The user is not found in AD.

Get Computer

Retrieves detailed information on the specified Active Directory computer(s).

Reader Note

The input parameter Hostnames is required to run this command.

Hostnames can be obtained from the Active Directory client. Please note that this parameter accepts the display name of the host, not its DNS name.

Input

Input Parameter	Required/Optional	Description	Example
Hostnames	Required	The hostnames of the AD user computers to retrieve detailed information.	["Host1","Host2"]

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

[
    {
        "CN": "Host1",
        "FQDN": "CN=Host1,CN=Computers,DC=test,DC=local",
        "HostName": "Host1***",
        "Name": "Host1",
        "ObjectCategory": "CN=Computer,CN=Schema,CN=Configuration,DC=***,DC=local",
        "ObjectClass": "top",
        "OperatingSystem": "Windows Server 2019 Standard",
        "OperatingSystemVersion": "10.0 (17763)",
        "SamAccountName": "Host1$",
        "sAMAccountType": "***"
    },
    {
        "CN": "Host2",
        "FQDN": "CN=Host2,CN=Computers,DC=***,DC=local",
        "HostName": "Host2***",
        "Name": "Host2",
        "ObjectCategory": "CN=Computer,CN=Schema,CN=Configuration,DC=***,DC=local",
        "ObjectClass": "top",
        "OperatingSystem": "Windows Server 2016 Standard",
        "OperatingSystemVersion": "10.0 (14393)",
        "SamAccountName": "Host22$",
        "sAMAccountType": "***"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "FQDN": "CN=Host1,CN=Computers,DC=***,DC=local",
        "HostName": "Host1***"
    },
    {
        "FQDN": "CN=Host2,CN=Computers,DC=***,DC=local",
        "HostName": "Host2***"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "HostNames": [
        "Host1***",
        "Host2***"
    ],
    "FQDNs": [
        "CN=Host1,CN=Computers,DC=***,DC=local",
        "CN=Host2,CN=Computers,DC=***,DC=local"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

FQDN	HOSTNAME
CN=Host1,CN=Computers,DC=***,DC=local	Host1***
CN=Host2,CN=Computers,DC=***,DC=local	Host2***

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Get Computer failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The hostname is not found in AD.

Error Sample Data

Get Computer failed.

Status Code: 404.

Message: The hostname is not found in AD.

Get User logon/logoff Information from AD

Returns the logon and logoff time of the specified Azure Directory user(s).

Reader Note

You can access the logon and logoff information through the Event Viewer. However, this command can only retrieve user logon and logoff information with the task category of Other Logon/Logoff Events.
Below is an example of a logon and logoff information log from an administrator in the Event Viewer.

Input

Input Parameter	Required/Optional	Description	Example
Usernames	Required	The usernames of the AD user accounts to retrieve logon and logoff times.	["User1"]
Start Time	Optional	The start time of the time range to filter returned logs in UTC time.	2023-02-15 00:00
End Time	Optional	The end time of the time range to filter returned logs in UTC time.	2023-02-22 00:00

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

[
    {
        "LogonId": null,
        "FQDN": "CN=PC1,CN=Computers,DC=dc,DC=local",
        "HostName": "PC1",
        "Email": "test@example.com",
        "Address": "",
        "UserName": "User1",
        "MachineName": "-",
        "DomainName": "domain",
        "IPAddress": "1.1.1.1",
        "LoginTime": "2019-11-30T16:04:31.8646625-08:00",
        "LogoffTime": null
    },
    {
        "LogonId": null,
        "FQDN": "CN=PC2,CN=Computers,DC=dc,DC=local",
        "HostName": "PC2",
        "Email": "test2@example.com",
        "Address": "",
        "UserName": "User1",
        "MachineName": "-",
        "DomainName": "domain",
        "IPAddress": "1.1.1.1",
        "LoginTime": "2019-11-30T16:04:38.2842387-08:00",
        "LogoffTime": "2019-11-30T16:04:38.5908231-08:00"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 enriches the Context Data by extracting the data from the paths $[*].HostName, $[*].IPAddress, $[*].LoginTime and $[*].LogoffTime in the returned raw data.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "HostName": "PC1",
        "IPAddress": "1.1.1.1",
        "LoginTime": "2019-11-30T16:04:31.8646625-08:00",
        "LogoffTime": null
    },
    {
        "HostName": "PC2",
        "IPAddress": "1.1.1.1",
        "LoginTime": "2019-11-30T16:04:38.2842387-08:00",
        "LogoffTime": "2019-11-30T16:04:38.5908231-08:00"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "HostName": [
        "PC1",
        "PC2"
    ],
    "IPAddress": [
        "1.1.1.1",
        "1.1.1.2"
    ],
    "LoginTime": [
        "2019-11-30T16:04:31.8646625-08:00",
        "2019-11-30T16:04:38.2842387-08:00"
    ],
    "LogoffTime": [
        "2019-11-30T16:04:38.5908231-08:00"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Get User logon/logoff Information from AD failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: Invalid server address.

Error Sample Data

Get User logon/logoff Information from AD failed.

Status Code: 403.

Message: Invalid server address.

Get Users By Group

Retrieves a list of Active Directory users of the specified group.

Reader Note

If you encounter a group that returns a success message with no results, it could be because the group is a system group. To address this issue, consider searching for a customized group instead.

Input

Input Parameter	Required/Optional	Description	Example
Group Name	Optional	The name of the group to return a list of users.	Test Group

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

[
    {
        "UserID": "{***-***-***-***-***}",
        "EmployeID": "***",
        "UserPrincipalName": "test@example.com",
        "LoginName": "test",
        "FirstName": "user",
        "Initials": "te",
        "LastName": "user",
        "DisplayName": "test user",
        "Title": "Cyber Security Engineer",
        "Description": "In charge of cyber security",
        "BusinessUnit": "London Office",
        "Department": "Lab",
        "Division": "IT Service Division",
        "Company": "D3 Security",
        "Address1": "",
        "Address2": "",
        "State": "BC",
        "StreetAddress": "700 Pender ST",
        "City": "Vancouver",
        "Country": "Canada",
        "Zip": "V3K 8O9",
        "POBox": "Po Box 1",
        "EmailAddress": "test@example.com",
        "DateCreated": "2021-06-07 23:02:23",
        "DateLastModified": "2021-07-26 22:19:54",
        "DateOfExpiry": "",
        "AccountIsActive": true,
        "Manager": "CN=Administrator,CN=Users,DC=***,DC=local",
        "MemberOf": [
            "CN=Testgroup,CN=Users,DC=***,DC=local",
            "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=d3cyber7,DC=local",
            "CN=Administrators,CN=Builtin,DC=***,DC=local"
        ],
        "DistinguishedName": "CN=test,CN=Users,DC=***,DC=local"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "UserID": "{***-***-***-***-***}",
        "EmployeID": "***",
        "UserPrincipalName": "test@example.com",
        "LoginName": "test",
        "FirstName": "user",
        "Initials": "te",
        "LastName": "user",
        "DisplayName": "test user",
        "Title": "Cyber Security Engineer",
        "Description": "In charge of cyber security",
        "BusinessUnit": "London Office",
        "Department": "Lab",
        "Division": "IT Service Division",
        "Company": "D3 Security",
        "Address1": "",
        "Address2": "",
        "State": "BC",
        "StreetAddress": "700 Pender ST",
        "City": "Vancouver",
        "Country": "Canada",
        "Zip": "V3K 8O9",
        "POBox": "Po Box 1",
        "EmailAddress": "test@example.com",
        "DateCreated": "2021-06-07 23:02:23",
        "DateLastModified": "2021-07-26 22:19:54",
        "DateOfExpiry": "",
        "AccountIsActive": true,
        "Manager": "CN=Administrator,CN=Users,DC=***,DC=local",
        "MemberOf": [
            "CN=Testgroup,CN=Users,DC=***,DC=local",
            "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=d3cyber7,DC=local",
            "CN=Administrators,CN=Builtin,DC=***,DC=local"
        ],
        "DistinguishedName": "CN=test,CN=Users,DC=***,DC=local"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DistinguishedNames": [
        "CN=user1,CN=Users,DC=***,DC=local"
    ],
    "UserIDs": [
        "{***-***-***-***-***}"
    ],
    "EmailAddresses": [
        "test@example.com"
    ],
    "LoginNames ": [
        "user1"
    ],
    "Divisions": [
        "Information Technology Service Division"
    ],
    "BusinessUnits": [
        "Digital & Transformation"
    ],
    "Departments": [
        "IT Department"
    ],
    "AccountIsActive": [
        true
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

USERID	EMPLOYEID	USERPRINCIPALNAME	LOGINNAME	FIRSTNAME	INITIALS	LASTNAME	DISPLAYNAME	TITLE	DESCRIPTION	BUSINESSUNIT	DEPARTMENT	DIVISION	COMPANY	ADDRESS1	ADDRESS2	STATE	STREETADDRESS	CITY	COUNTRY	ZIP	POBOX	EMAILADDRESS	DATECREATED	DATELASTMODIFIED	DATEOFEXPIRY	ACCOUNTISACTIVE	MANAGER	MEMBEROF	DISTINGUISHEDNAME
{*----**}		test@example.com	test	user	te	uesr	test user	Cyber Security Engineer	In charge of cyber security	London Office	Lab	IT Service Division	D3 Security			BC	700 Pender ST	Vancouver	Canada	V3K 8O9	Po Box 1	test@example.com	2021-06-07 23:02:23	2021-07-26 22:19:54		True	CN=Administrator,CN=Users,DC=***,DC=local	[ "CN=Testgroup,CN=Users,DC=*,DC=local", "CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=,DC=local", "CN=Administrators,CN=Builtin,DC=**,DC=local" ]	CN=test,CN=Users,DC=***,DC=local

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Get Users By Group failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The Group Name is not found in AD.

Error Sample Data

Get Users By Group failed.

Status Code: 404.

Message: The Group Name is not found in AD.

Reset User Password

Resets the specified Active Directory user's password.

Reader Note

If you encounter the "LDAPStartTLSError: startTLS failed - unavailable" error, you can resolve it by setting up LDAPS on your Windows Server. Refer to this link for a step-by-step guide on how to set up LDAPS. Once you have successfully set up LDAPS, the error should no longer occur.

Input

Input Parameter	Required/Optional	Description	Example
Username	Optional	The username of the AD user to reset password.	Sysint
New Password	Optional	The new password.	XXXXXXXXXX
Confirm Password	Optional	The new password re-entered for confirmation.	XXXXXXXXXX

Output

Raw Data

The primary response data from the request.

SAMPLE DATA

JSON

{
    "User": "testuser",
    "Status": "Success"
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

{
    "User": "testuser",
    "Status": "Success"
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "UserName": "testuser"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The request returned an error message
No response from the request

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

USER	STATUS
testuser	Success

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or directory services, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input.	Reset User Password failed.
Status Code	The response code issued by the server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the directory service about the request failure.	Message: The user is not found in AD.

Error Sample Data

Reset User Password failed.

Status Code: 404.

Message: The user is not found in AD.