PS-SentinelOne PowerShell Module

Table of Contents

• Overview
• Installation and Removal
• Configuration
• Capability

---

Overview

This is a PowerShell script module that provides command-line interaction and automation using the SentinelOne REST API.

Development is ongoing, with the goal to add support for the majority of the API set, and an attempt to provide examples for various capabilities.

---

Luke Notes

In this fork, I've replaced the Protect / Unprotect API key functions with ConvertToSecureString and ConvertFrom-SecureString, to make it functional on Linux platforms.\

---

Installation and Removal

One Liner Install multiplatform

$ModuleName='PS-SentinelOne';$parentFldr='PS-SentinelOne-master';$u='https://github.com/Luke-Williams9/PS-SentinelOne/archive/refs/heads/master.zip';If($IsWindows){$s=';'}else $s=':'};$mp=($Env:PSModulePath.split($s) -like "$HOME*")[0];$td='.'+$ModuleName+'_temp';$tempdir=Join-Path '~' $td;$z=Join-Path $tempdir ($ModuleName + '.zip');New-Item -path '~' -name $td -type 'directory' -ErrorAction SilentlyContinue;Invoke-WebRequest -Uri $u -OutFile $z;Expand-Archive $z -DestinationPath $tempdir -Force;New-Item -path $mp -name $ModuleName -ItemType 'directory' -ErrorAction SilentlyContinue;Copy-Item (Join-Path $tempdir $parentFldr $moduleName) -Destination $mp -Force -Recurse;Get-Module -listAvailable $ModuleName

Installation of this module currently consists of a pair of scripts that will copy the module to one of the PowerShell module paths, and check PowerShell module paths to remove it.

Install Script

.\Install-Module.ps1

Uninstall Script

.\Uninstall-Module.ps1

---

Configuration

PS-SentinelOne includes commandlets to configure information specific to your environment, such as the URI of your SentinelOne console, and your API Token.

You may choose to cache this information for the current session, or save the information to disk. Saved API Tokens are protected by using secure strings.

In Session Configuration

Commandlets will utilize the URI and API Token cached in the current session. If no URI or API Token is cached, an attempt will be mode to retrieve any settings that have been saved to disk.

Set the base URI for your management console, and your API Token for this session

PS > Set-S1ModuleConfiguration -URI "https://management-tenant.sentinelone.net" -ApiToken "<API Token>"

Set the base URI for your management console, and authenticate with your credentials for a temporary token Note: You must have a URI set in order to authenticate, otherwise the commandlet will not know where to connect to perform authentication.

PS > Set-S1ModuleConfiguration -URI "https://management-tenant.sentinelone.net"
PS > Get-S1Token
Windows PowerShell credential request.
Input SentinelOne username and password to authenticate for a temporary API token.
User: john.smith@acme.com
Password for user john.smith@acme.com: **************

Check the settings in the current session

PS > Get-S1ModuleConfiguration

Persisted Configuration

Save to disk the base URI for your management console and your API Token.

PS > Set-S1ModuleConfiguration -URI "https://management-tenant.sentinelone.net" -ApiToken "<API Token>" -Persist

Review any settings saved to disk

PS > Get-S1ModuleConfiguration -Persisted

Import settings saved to disk into the current session

PS > Get-S1ModuleConfiguration -Persisted -Cache

Saved settings do not need to be manually imported into the current session. If there are settings saved to disk and the current session has none configured, the module will automatically import the saved settings when running your first commandlet that requires them. You can test this by doing the following

PS > Import-Module .\PS-SentinelOne.psm1
PS > Get-S1ModuleConfiguration
Name                           Value
----                           -----
ConfPath                       C:\Users\<username>\AppData\Local\PS-SentinelOne\config.json

PS > Get-S1Site
<OUTPUT REMOVED>

PS > Get-S1ModuleConfiguration

Name                           Value
----                           -----
ManagementURL                  https://management-tenant.sentinelone.net
ApiToken                       <API Token as Secure String>
ConfPath                       C:\Users\<username>\AppData\Local\PS-SentinelOne\config.json

---

Capability

For API coverage, see the API Coverage documentation

The examples below need to be revised and expanded upon, please bare with me.

• Accounts
  • Retrieve accounts list
• Sites
  • Retrieve sites list
  • Retrieve sites for account
  • Retrieve active sites
  • Retrieve a site by name
• Groups
  • Retrieve all groups in a specific site
  • Retrieve a specific group in a specific site
  • Create a new group
  • Delete a group
• Agents
  • Retrieve agents in a group
  • Retrieve agents for a certain domain
  • Retrieve agents with macOS
  • Retrieve agents in detect mode
  • Retrieve infected agents
  • Retrieve passphrase for an agent
• Exclusions (Whitelist)
  • Retrieve hash exclusions for a site
  • Retrieve path exclusions for a site
• Blacklist
  • Retrieve blacklist for a site
  • Add a hash to the blacklist
• Applications
  • Retrieve installed applications for a specific agent
  • Retrieve application instances and versions by application name
• Agent Actions
  • Get Available Actions
  • Move agent to different group
  • Move agent to different site
  • Initiate a scan
  • Abort a scan
  • Fetch a file
  • Fetch logs from agent
  • Send a message to an agent
  • Start network quarantine for an agent
  • Stop network quarantine for an agent
• Updates
  • Get packages list
  • Initiate agent update

Accounts

Retrieve accounts list

PS > Get-S1Account

Sites

Retrieve sites list

PS > Get-S1Site

Retrieve sites for account

PS > $Account = Get-S1Account -Name "My Account"
PS > Get-S1Site -AccountID $Account.id

Retrieve active sites

PS > Get-S1Site -State active # Tab complete capability

Retrieve a site by name

PS > Get-S1Site -Name "My Site"

Groups

Retrieve all groups in a specific site

PS > $Site = Get-S1Site -Name "My Site"
PS > $Groups = Get-S1Group -SiteID $Site.id

Retrieve a specific group in a specific site

PS > $Site = Get-S1Site -Name "My Site"
PS > $Groups = Get-S1Group -SiteID $Site.id -Name "Default Group"

Create a new group

PS > $Site = Get-S1Site -Name "My Site"
PS > $NewGroup = New-S1Group -Name "Test" -SiteID $Site.id

Delete a group

PS > $Site = Get-S1Site -Name "My Site"
PS > $Group = New-S1Group -Name "Test" -SiteID $Site.id
PS > Remove-S1Group -GroupID $Group.id

success
-------
   True

Agents

Retrieve agents in a group

PS > $Group = Get-S1Group -Name "Default Group"
PS > Get-S1Agent -GroupID $Group.id

Retrieve agents for a certain domain

PS > Get-S1Agent -Domain acme

Retrieve agents with macOS

PS > Get-S1Agent -OSType macos

Retrieve agents in detect mode

PS > Get-S1Agent -MitigationMode detect

Retrieve infected agents

PS > Get-S1Agent -Infected true

Retrieve passphrase for an agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Get-S1Passphrase -AgentID $Agent.id

Exclusions (Whitelist)

Retrieve hash exclusions for a site

PS > $TargetSite = Get-S1Site -Name "Rebel Alliance"
PS > Get-S1Exclusion -SiteID $TargetSite.id -Type white_hash

Retrieve path exclusions for a site

PS > $TargetSite = Get-S1Site -Name "Rebel Alliance"
PS > Get-S1Exclusion -SiteID $TargetSite.id -Type path

Blacklist

Retrieve blacklist for a site

PS > $TargetSite = Get-S1Site -Name "Rebel Alliance"
PS > Get-S1Blacklist -SiteID $TargetSite.id

Add a hash to the blacklist

PS > $TargetSite = Get-S1Site -Name "Rebel Alliance"
PS > New-S1Blacklist -Hash "2EF7BDE608CE5404E97D5F042F95F89F1C232871" -Description "Terrible" -OSType windows -SiteID $TargetSite.id

Applications

Retrieve installed applications for a specific agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Get-S1Application -AgentID $Agent.id

Retrieve application instances and versions by application name

PS > $ChromeInstances = Get-S1Application -ApplicationName "Google Chrome"

Agent Actions

Get Available Actions

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Get-S1AvailableActions -AgentID $Agent.id

isDisabled name                     Example
---------- ----                     -------
     False fetchLogs                Invoke-S1AgentAction -AgentID <agent_id> -FetchLogs
     False initiateScan             Invoke-S1AgentAction -AgentID <agent_id> -Scan
     False abortScan                Invoke-S1AgentAction -AgentID <agent_id> -AbortScan
     False disconnectFromNetwork    Invoke-S1AgentAction -AgentID <agent_id> -DisconnectFromNetwork
     False reconnectToNetwork       Invoke-S1AgentAction -AgentID <agent_id> -ReconnectToNetwork
     False updateSoftware
     False sendMessage              Invoke-S1AgentAction -AgentID <agent_id> -SendMessage <message>
     False shutDown
     False decommission             Invoke-S1AgentAction -AgentID <agent_id> -Decommission
     False reboot
     False reloadConf               Invoke-S1AgentAction -AgentID <agent_id> -Reload <log, static, agent, monitor>
     False uninstall
     False approveUninstall         Invoke-S1AgentAction -AgentID <agent_id> -ApproveUninstall
     False rejectUninstall          Invoke-S1AgentAction -AgentID <agent_id> -RejectUninstall
     False moveToAnotherSite        Invoke-S1AgentAction -AgentID <agent_id> -MoveToSite -TargetSiteID <site.id>
     False configureFirewallLogging
     False remoteShell
     False clearRemoteShellSession
     False purgeResearchData
     False purgeCrashDumps
     False flushEventsQueue
     False resetLocalConfiguration  Invoke-S1AgentAction -AgentID <agent_id> -ResetLocalConfig
      True restartServices
     False markAsUpToDate
     False protect                  Invoke-S1AgentAction -AgentID <agent_id> -Protect
     False unprotect                Invoke-S1AgentAction -AgentID <agent_id> -Unprotect
     False revokeToken
     False purgeDB
     False controlCrashDumps
     False controlResearchData
     False eventsThrottling
     False configuration
     False migrateAgent
     False randomizeUUID
     False fileFetch
     False showApplications
     False showPassphrase
     False searchOnDeepVisibility
     False viewThreats
     False setCustomerIdentifier
      True enableRanger
      True disableRanger

Move agent to different group

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > $TargetGroup = Get-S1Group -Name "Destroyed Battle Stations"
PS > Move-S1Agent -AgentID $Agents.id -TargetGroupID $TargetGroup.id

Move agent to different site

PS > $Agent = Get-S1Agent -Name "Kashyyyk"
PS > $TargetSite = Get-S1Site -Name "Rebel Alliance"
PS > Move-S1Agent -AgentID $Agents.id -TargetSiteID $TargetSite.id

Initiate a scan

PS > $Agents = Get-S1Agent -ScanStatus aborted
PS > Invoke-S1AgentAction -AgentID $Agents.id -Scan
Scan initiated for X agents

Abort a scan

PS > $Started = Get-S1Agent -ScanStatus started
PS > Invoke-S1AgentAction -AgentID $Started.id -AbortScan
Scan aborted for X agents

Fetch a file

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1FetchFile -AgentID $Agent.id -FilePath "/path/to/file" -Password ExecuteOrder66!

success
-------
   True

Fetch logs from agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1AgentAction -AgentID $Agent.id -FetchLogs
Fetch Logs initiated for 1 agents

Send a message to an agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1AgentAction -AgentID $Agent.id -SendMessage "Do I execute order 66?"

Start network quarantine for an agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1AgentAction -AgentID $Agent.id -DisconnectFromNetwork

Stop network quarantine for an agent

PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1AgentAction -AgentID $Agent.id -ReconnectToNetwork

Updates

Get packages list

PS > $Site = Get-S1Site -Name "Rebel Alliance"
PS > Get-S1Package -SiteID $Site.id

PS > $Site = Get-S1Site -Name "Rebel Alliance"
PS > Get-S1Package -SiteID $Site.id -FileExtension ".exe" -PackageType "Agent" -OSType "windows"

Initiate agent update

PS > $Site = Get-S1Site -Name "Rebel Alliance"
PS > $Package = Get-S1Package -SiteID $Site.id -FileExtension .exe -PackageType Agent -OSType windows  | Where-Object { $_.status -like "GA*" } | Sort -Descending version | Select-Object -First 1
PS > $Agent = Get-S1Agent -Name "Deathstar"
PS > Invoke-S1AgentUpdate -AgentID $Agent.id -PackageID $Package.id
Update initiated for 1 agents