Working with the EDR PowerShell module

SECURITY   Datto EDR subscription with administrator or analyst-level platform access

SECURITY   Service account or administrator-level rights on the target endpoint

BEFORE YOU BEGIN  On each endpoint for which you'd like to enable communication with the API, perform the steps described in Configuring the Datto EDR PowerShell module.

With the Datto EDR PowerShell module, you can gain programmatic access to the API, export audit data from endpoints in CSV or JSON formats, manage locations, upload offline scans, and initiate collection. This article describes the functions and cmdlets that you can use to do so.

Run all commands described in this article from an administrator-level PowerShell session on the endpoint that you'd like to communicate with your EDR instance.

Index

Getting started

To open communication to an instance from an endpoint, use the Set-ICToken command. Replace <instanceName> with the first part of your EDR instance's URL. As an example, for the URL https://alpo1.infocyte.com, enter alpo1.

PS > Set-ICToken -Instance <instanceName> -Token <token> -save

Retrieving and filtering data

Records in Datto EDR are either event-based or object-based.

The platform aggregates both types of records by their unique hash and path, and then categorizes these aggregations into "boxes" of events for the last seven or 15 days for each location.

By default, the Get-ICObject and Get-ICData functions will return events from the Global Last 7 Days box. Both commands have the same function and are aliases of one another.

You can also filter the returns to a specific location ID and time frame.

To view all records for all locations from the last seven days, use the Get-ICData function. GET results are capped at 1,000 records unless you use the -NoLimit switch. Refer to Removing result caps for more information.

PS> Get-ICData

To view all records for a designated location from the last seven days, use the where argument. Replace groupId with the ID of the location you'd like to query. If you don't know the ID, you can find it by following the steps in the Determining a location from the last seven days, use the where argument. Replace groupId with the ID of the location ID section of this article.

PS> Get-ICData -where @{ targetGroupId = "groupId" }

Use the following syntax to find a location's identifier. Replace Location Name with the name of the location from the last seven days, use the where argument. Replace groupId with the ID of the location as it appears in your EDR instance.

PS> $TG = Get-ICTargetGroup | where { $_.name -eq "Location Name"}

The API will return a UUID similar to that shown in the following screenshot.

If you'd like to audit information from a specific range of dates, there are several switches you can use.

Switch Definition
-Trailing <days>

Specifies the number of previous days to include in the search; replace <days> with any number up to 15
-StartTime <datetime> Designates the date from which the information should begin; replace <datetime> with the start date you'd like to use
-EndTime <datetime> Designates the date at which the information should end; replace <datetime> with the end date you'd like to use

GET results are capped at 1,000 records unless you use the -NoLimit switch. Attach the switch to the end of your argument list, as shown in the following example.

PS> Get-ICObject -Type Process -StartDate (get-date -Date "10/27/2022") -Enddate (get-date).AddHours(-12) -NoLimit
Function Definition
Get-ICAlert Get-ICAlert
Get-ICFileDetail Get details of a file by hash
Get-ICNote Get all analyst notes
Get-ICVulnerability Display details of a vulnerable application

Filters in the Datto EDR API are constructed using the LoopBack specifications and format. Additional supported filters include hashtables and AND/OR operators.

The module will convert the hashtable in the examples below into the JSON ingested by LoopBack, but you will need to use LoopBack operators.

Example

PS> $whereFilter = @{ threatName = @{ regexp = "Unknown|Suspicious|Bad" } }
PS> $whereFilter += @{ commentCount = 0 }
PS> Get-ICObject -Type File -where $whereFilter

Example

PS> [HashTable]$where = @{ term1 = "asdf1"; term2 = "asdf2" }

Example

PS> Get-ICObject -Type File -where @{ path = @{ regexp = "/roaming/i" } }

NOTE  While you can use PowerShell piping to filter after retrieval, we do not recommend it. The -where LoopBack filter will automatically be applied by the EDR server, which conserves bandwidth and avoids potential throttling. Learn more at LoopBack's website.

In the examples that follow, replace <hostScanId> and <scanId> with the corresponding IDs of the scans you'd like to query. Replace <hostname> with the name of the host you'd like to query. Replace <num> with the maximum number of records you'd like returned.

Example AND request for a specific scan on a specific host

Replace <hostname> and <scanId> with the name of the host and the ID of the scan.

{"where":{"and":[{"hostname":{"eq":"<hostname>"}},{"scanId":{"eq":"<scanId>"}}]}

Example AND request to limit the number of entries returned

{"where":{"and":[{"hostname":{"eq":"<hostname>"}},{"scanId":{"eq":"<scanId>"}}]},"limit":<num>}

In the examples that follow, replace <hostScanId> and <scanId> with the corresponding IDs of the scans you'd like to query.

Example OR request with hostScanId

In this example, <hostScanId> is the mandatory field, and the remaining fields are optional. The query may match threatScore, blacklist, localblacklist, or malicious based on the condition value.

{"where":{"and":[{"hostScanId":{"eq":"<hostScanId>"}},{"or":[{"threatScore":{"gt":"4"}},{"blacklist":{"eq":"true"}},{"localBlacklist":{"eq":"true"}},{"malicious":{"eq":"true"}}]}],"limit":5000}}

Example OR request with scanId

In this example, <scanId> is the mandatory field, and the remaining fields are optional. The query may match threatScore, blacklist, localblacklist, or malicious based on the condition value.

{"where":{"and":[{"scanId":{"eq":"<scanId>"}},{"or":[{"threatScore":{"gt":"4"}},{"blacklist":{"eq":"true"}},{"localBlacklist":{"eq":"true"}},{"malicious":{"eq":"true"}}]}],"limit":5000}}

Good to know

The best time format to use with your custom LoopBack filters is ISO-8601 or Get-Dates type code "o" (i.e., 2019-05-03T00:37:40.0056344-05:00).

Enumerating, scanning, and responding to threats

Many of the functions described here require a TargetGroupId reference. Refer to the Determining a location from the last seven days, use the where argument. Replace groupId with the ID of the location ID section of this article for more information.

Enumerating hosts
Function Definition
Invoke-ICFindHosts List all endpoints in your environment monitored by Datto EDR
Scan scheduling
Function Definition
Add-ICScanSchedule Create a new scan
Get-ICScanchedule Schedule a known scan to run
Remove-ICScanSchedule Delete a scheduled scan
Function Definition
Add-ICScanSchedule Create a new scan
Get-ICScanchedule Schedule a known scan to run
Invoke-ICScan Run an existing scan
New-ICScanOptions Create a new scheduled scan
Remove-ICScanSchedule Delete a scheduled scan
Invoke-ICScanTarget Scans the specified host
Function Definition
Get-ICHostScanResult Display the results of a host scan
Get-ICResponseResult Get response taken on a specific alert
Invoke-ICResponse Runs an extension on a specified host

Scans and other activities are tracked as tasks. Each task can have multiple items, typically hosts, that the action will iterate through. Individual items and host progress will also be tracked and can be reviewed by using the functions listed here, coupled with a reference to the TaskItemId.

Function Definition
Get-ICTask Show task list
Get-ICTaskItem Display details of a specific task
Get-ICTaskItemProgress Display the progress of a specific task

Importing and exporting data

If an endpoint cannot connect to the internet due to a network outage or because of security considerations, you can perform manual offline scans of the host and use the Import-ICSurvey function to upload the results to our analysis engine for review.

To learn more, refer to Scanning an offline endpoint.

Data is separated by object type. You can retrieve all object and event data by using a reference to the object type. Because Datto EDR handles applications and vulnerabilities differently than other objects, they have their own functions. You can also query individual file reputation data by its sha1 value.

Function Definition
Get-ICObject Return events from the Global Last 7 Days box
Get-ICApplication Show known applications
Get-ICVulnerability List discovered vulnerabilities
Get-ICFileDetail Queries an individual file for its reputation data

location management

locations are logical grouping of hosts and related data that you can view and manage at Organizations. Each location from the last seven days, use the where argument. Replace groupId with the ID of the location has an address table listing hosts that have been discovered or agents that have been added to each group. For more information, refer to Creating organizations, locations, and devices.

Function Definition
Get-ICAddress Display address list of discovered host
Get-ICAgent Display agent list
Get-ICTargetGroup Display current locations
New-ICTargetGroup Create a new location
Remove-ICAddress Manage devices logically in locations
Remove-ICAgent Manage devices in the global agent list
Remove-ICTargetGroup Delete an existing location

Development functions

Function Definition
Get-ICExtension Display list of current extensions
Import-ICExtension Loads an extension into your instance
New-ICExtension Create a new extension
Remove-ICExtension Delete existing extension
Test-ICExtension Runs the extension locally for testing
Update-ICExtension Modify an existing extension
Function Definition
Get-ICRule Get a list of current detection rules
Import-ICRule Loads a rule into your instance from a YAML file
New-ICRule Create a new detection rule
Remove-ICRule Delete existing detection rule
Test-ICRule Runs the rule locally for testing
Update-ICRule Update existing detection rule

Additional functions

The following additional functions are supported by the API.

Administrative functions
Function Definition
Add-ICComment Add a new comment to detection
Get-ICUser Show user account information
Get-ICUserAuditLog Get audit log of user activity
Authentication functions
Function Definition
Set-ICToken
(alias: Set-ICInstance) 		Create a new API token
Generic API functions
Function Definition
Get-ICAPI  
Invoke-ICAPI  
Get-ICHelp Open the in-application help
Task status functions
Switch Definition
Get-ICTask Get a list of tasks
Get-ICTaskItems See specific details of a task