Skip to main content

Insight Enrichment Server

The Cloud SIEM Insight Enrichment Server is a component that automatically enriches Cloud SIEM Insights.  

warning

The Insight Enrichment Server is deprecated. Use the Automation Service instead for enrichments. See Migrate from legacy actions and enrichments to the Automation Service.

note

This topic describes v1.5.0 of the non-FedRAMP version of the Insight Enrichment Server, and v1.0.3 for the FedRAMP version.

What the Insight Enrichment Server does​

The Insight Enrichment Server performs an external query on the Entity for an Insight—for example, an IP address, a hostname, username, or a MAC address—and adds the query results as an enrichment to the Insight.

You configure enrichments in the server’s configuration file. The key settings are the Entity type to run the enrichment on, and the command and command arguments to run. 

The Insight Enrichment Server periodically polls Cloud SIEM for new Insights. If an Insight’s Entity is of the same type as the entity_type specified for an enrichment configured in the server’s configuration file, the server runs the enrichment for the Entity instance in the Insight. You can see an enrichment that has been added to an Insight on the Enrichments tab for an Insight.  

Example enrichment

Create configuration file​

Before installing the server, create a configuration file named config.ini—options should be configured in this file before you install the server. See the Example configuration file later in this topic. Refer to the Configuration section for information about configuration options.

Install Insight Enrichment Server​

Follow the instructions for the deployment in which you're installing the Insight Enrichment Server.

If you're not installing the Insight Enrichment Server on the FED deployment, follow these instructions:

Prerequisites

The Cloud SIEM Insight Enrichment Server can be installed on any Windows system with a Vista+ or Server 2008 or newer operating system. It does not have significant RAM or CPU requirements, so it should be fine running on almost any hardware.   

You must have local administrative privileges to install the Insight Enrichment Server. By default, the server runs under the LocalService account on the machine. If the Insight Enrichment Server needs privileges to perform actions as a different user, see Run the server under a service account, below.

The installation process requires a valid configuration file before the installation is started. 

Installation Process

The Insight Enrichment Server is packaged with an interactive installer. You’ll be prompted to supply the following configuration options when you run the installer.

  • Installation Directory. By default, the Insight Enrichment Server will be installed in C:\Windows\SumoLogic\EnrichmentService. Sumo Logic recommends that you accept this default.   
  • Enrichment Service Credentials. If you need to run the server under a user with different privileges than the LocalService, provide them when prompted. See Run the server under a service account below for account requirements.
  • Configuration File. The installer prompts you to provide the location of a configuration file with an .ini extension. The file must be a valid configuration file with required configuration options. For an example, see Example configuration file. The file will be copied to C:\Windows\SumoLogic\EnrichmentService on your local machine.

Run the server under a service account

At installation time, you can configure the Insight Enrichment Server to run under a different user (service) account. To do so, you provide the username and password of the preferred service account. That account must have the "Log in as Service" privilege. The installer will verify that the account has the appropriate permissions. 

Install the Insight Enrichment Server

Download the binary from here. The checksum for the binary is here.

Run the installer and follow the instructions.

Configuration​

Variables​

The Enrichment Server supports these variables:

${IP}, ${MAC}, ${USERNAME}, and ${HOSTNAME}, and for custom Entities, ${ENTITY}.

General settings​

The following parameters control general server behaviors, as opposed to enrichment-specific options.

SettingRequired?Description
URLyesThe URL for your API endpoint. For more information, see Sumo Logic API Authentication, Endpoints, and Security.
api_idyesEnter your Sumo Logic Access ID. For more information, see Manage your access keys on Preferences page.
api_keyyesEnter your Sumo Logic Access Key.
log_levelnoLog level the server should use. The options are:

-error. Only display error messages.
-info. Display informational messages. This is the recommended value.
-debug. Displays debug (or trace) data. Recommended only when debugging.

Default: info
poll_intervalnoHow often the Insight Enrichment Server should check for new Insights. You can specify the interval in seconds (s), minutes (m), or hours (h).

Default: 10s
post_workersnoThe number of parallel workers (threads) posting enrichment results. Default: 6
enrichment_workersnoThe number of parallel workers (threads) running enrichment tasks.

Default: 12
proxy_urlnoAn HTTP proxy URL to use when communicating with the Sumo Logic backend. For example, my.proxy.myorg.com:3128 or username:password@my.proxy.myorg.com:31281.

Default: No proxy used

Enrichment settings​

The table below defines the settings you configure for each enrichment. 

Each enrichment should be configured in a separate section in the configuration file. The name of the section (for example [name]) corresponds to a given enrichment name as it appears within the UI. Each section must have an enrichment_type defined. Currently, the only supported enrichment_type is "command". Each enrichment supports the options defined in the table below.  

SettingRequired?Description
enrichment_typeyesSpecifies the type of the enrichment. Currently, the only supported value is command.
entity_typeyesThe type of Entity to enrich. The Insight Enrichment server supports built-in Entity types, including IP, mac, username, and hostname. (For a complete list, see View and Manage Entities. It also supports custom Entity types. For custom Entity types, the entity_type should match the unique Identifier assigned to the custom Entity type.
cache_timenoThe length of time that the results of a specific enrichment for a specific Entity will be cached and returned for other enrichment requests for that enrichment and Entity. This setting can be used to prevent an enrichment from running multiple times for the same Entity. You can specify cache_time in hours (h), minutes (m), or seconds (s). If you specify a value without a unit, the value is treated as nanoseconds.

Default: none
ip_rangenoWhen entity_type is IP, you can specify a range of IP addresses that the enrichment will be limited to. Specify IP address ranges as a comma-separated list. For example:

192.168.1.1-192.168.1.255, 192.168.5.1-192.168.8.120
command_exeyesThe executable to run when enriching the Entity.
command_argsyesThe arguments to pass to the executable specified by command_exe when performing the enrichment. Note that the value ${IP} will be replaced by the IP address for IP Entities. The value ${HOSTNAME} will be replaced with the hostname for hostname Entities. The value ${MAC} will be replaced with the MAC address for MAC Entities. The value ${USERNAME} will be replaced with the username for username Entities. command_args also supports an ${ENTITY} replacement value that you can use for custom Entity types and any of the built-in Entity types.
command_timeoutnoA timeout value (in seconds) that will be enforced when running the command.

Default: none

Example enrichment​

This is an example of an enrichment:

[whois]
enrichment_type = command
entity_type = ip
command_exe = whois.exe
command_args = ${IP}
ip_range = 10.10.10.1-10.10.10.4, 192.168.0.0-192.168.255.255

If an Insight’s Entity is an IP address in one of the ranges specified by ip_range, the enrichment will run the command whois.exe on that IP address.

Example configuration file​

url = https://<>.sumologic.com
api_id = <>
api_key = <>
log_level = info

[nslookupHostname]
enrichment_type = command
entity_type = hostname
command_exe = nslookup.exe
command_args = ${HOSTNAME}
cache_time = 5m

[Logged In Usershostname]
enrichment_type = command
entity_type = hostname
command_exe = powershell.exe
command_args = query user /server:${HOSTNAME}
ip_range = 10.10.10.1-10.10.10.4, 192.168.0.0-192.168.255.255
cache_time = 5m

[Logged In Usersip]
enrichment_type = command
entity_type = ip
command_exe = powershell.exe
command_args = query user /server:${IP}
ip_range = 10.10.10.1-10.10.10.4, 192.168.0.0-192.168.255.255
cache_time = 5m

[nslookupIP]
enrichment_type = command
entity_type = ip
command_exe = nslookup.exe
command_args = ${IP}
cache_time = 5m

[whois]
enrichment_type = command
entity_type = ip
command_exe = whois.exe
command_args = ${IP}
ip_range = 10.10.10.1-10.10.10.4, 192.168.0.0-192.168.255.255

[dsquery]
enrichment_type = command
entity_type = username
command_exe = powershell.exe
command_args = dsquery user -name ${USERNAME}
cache_time = 5m

Passing parameters to PowerShell scripts​

You can configure the Insight Enrichment Server to pass parameters to a PowerShell script, as shown in the examples below.

CarbonBlack enrichment​

This enrichment queries the Carbon Black Device API for an IP address and returns host information. 

info

The example provided below is not guaranteed to work with all versions of the application. Modify the example to work in your environment. If you need assistance, ask your Sumo Logic representative to engage the Professional Services team.

Script:  c:\scripts\CB.ps1

param([string]$IP)
$uri = "https://api5.conferdeploy.net:443/integrationServices/v3/device?ipAddress=$IP"
$headers = @{'X-Auth-Token' = 'XXX/XXX'}
Invoke-RestMethod -Uri $uri -Method Get -Headers $headers | ConvertTo-Json

Enrichment configuration

[Carbon Black]
enrichment_type = command
entity_type = ip
command_exe = powershell.exe
command_args = -file c:\scripts\cb.ps1 ${IP}

Enrichment in the UI

Example Carbon Black enrichment

CrowdStrike enrichment​

This enrichment queries the CrowdStrike Device API for an IP address and returns host information.

info

The example provided below is not guaranteed to work with all versions of the application. Modify the example to work in your environment. If you need assistance, ask your Sumo Logic representative to engage the Professional Services team.

Prerequisites

This enrichment requires the PSFalcon PowerShell module, which is available at https://github.com/bk-cs/PSFalcon. To install it:

moduleInstall-Module -Name PSFalcon
Update-Module -Name PSFalcon

Script - CS.ps1

param([string]$IP)
Get-CsToken -Id "<>" -Secret "<>"
Get-CsHostId -Filter "local_ip:'$IP'" -OutVariable HostId | ConvertTo-Json *>$null
(Get-CsHostInfo -Id $HostId.resources).resources

Enrichment configuration

[CrowdStrike]
enrichment_type = command
entity_type = ip
command_exe = powershell.exe
command_args = -file c:\Windows\SumoLogic\EnrichmentService\CS.ps1 ${IP}
ip_range = 192.168.38.104-192.168.38.105

Enrichment in the UI

Example CrowdStrike enrichment

GreyNoise enrichment​

GreyNoise helps security teams reduce noise and prioritize signal-targeted attacks against their organization. This enrichment queries GreyNoise to see what it knows about the IP address.

info

The example provided below is not guaranteed to work with all versions of the application. Modify the example to work in your environment. If you need assistance, ask your Sumo Logic representative to engage the Professional Services team.

Script - c:\scripts\GreyNoise.ps1

param([string]$IP)
$uri = "https://api.greynoise.io/v2/noise/context/$IP"
$headers = @{
    'Accept' = 'application/json'
    'key' = 'key'
}
Invoke-RestMethod -Uri $uri -Method Get -Headers $headers

Enrichment configuration

[whois]
enrichment_type = command
entity_type = ip
command_exe = powershell.exe
command_args = -file c:\scripts\GreyNoise.ps1 ${IP}

SentinelOne enrichment​

The SentinelOne enrichment queries IP addresses or hostnames using the SentinelOne API and returns the information SentinelOne knows about the host.

info

The example provided below is not guaranteed to work with all versions of the application. Modify the example to work in your environment. If you need assistance, ask your Sumo Logic representative to engage the Professional Services team.

  1. In the PowerShell scripts below, replace usea1-partners with your portal.
  2. In the PowerShell scripts below, replace <> with your SentinelOne API key
  3. Copy the PowerShell scripts to c:\Windows\Jask\EnrichmentService\.
    note

    Depending on your version of the enrichment server, the directory location may be different.

  4. Add the lines below to your config.ini file.
    note

    The path that follows command_args -file must be the directory where you put the PowerShell scripts. Edit the path as necessary.

    [s1ip]
    enrichment_type = command
    entity_type = ip
    command_exe = powershell.exe
    command_args = -file c:\Windows\Jask\EnrichmentService\s1ip.ps1 ${IP}
    [s1hostname]
    enrichment_type = command
    entity_type = hostname
    command_exe = powershell.exe
    command_args = -file c:\Windows\Jask\EnrichmentService\S1hostname.ps1 ${HOSTNAME}
  5. Restart the enrichment server.

PowerShell Scripts

S1hostname.ps1

param([string]$HOSTNAME)
$uri = "https://usea1-partners.sentinelone.net/web/api/v2.1/agents?computerName=$HOSTNAME"
$headers = @{'Authorization' = 'ApiToken <>'}
Invoke-RestMethod -Uri $uri -Method Get -Headers $headers | ConvertTo-Json

s1ip.ps1

param([string]$IP)
$uri = "https://usea1-partners.sentinelone.net/web/api/v2.1/agents?networkInterfaceInet__contains=$IP"
$headers = @{'Authorization' = 'ApiToken <>'}
Invoke-RestMethod -Uri $uri -Method Get -Headers $headers | ConvertTo-Json

Sample enrichment

Example SentinelOne enrichment
Edit this page
Last updated on by John Pipkin (Sumo Logic)
Status
Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.