Skip to main content
Sumo Logic

Insight Enrichment Server

You can use the CSE Insight Enrichment Server to automatically enrich CSE Insights.


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

What the Insight Enrichment Server does

The Insight Enrichment Server performs an external query on the entity for an Insight—an IP address, a hostname, 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 on. 

The Insight Enrichment Server periodically polls CSE 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.  

The enrichment shown below returned the IP address associated with the hostname that is the entity for the Insight.

enrichment-1a.png

Install the Insight Enrichment Server

Prerequisites

The CSE 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 Windows 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\Jask\EnrichmentServer. 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\Jask\EnrichmentServer 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. 

Configuration

This section describes the configuration options for the Insight Enrichment Server.

General settings

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

Setting Required? Description
URL yes The URL of your CSE portal, for example, https://XXXX.portal.jask.ai
api_key yes Your CSE user API key, which you can copy from your user profile in the CSE portal.  (This is a user API key, not a  Sensor API key.)
To display your profile, click the profile icon profile-icon.png in the upper right corner of the CSE portal.
log_level no Log 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_interval  no How often (in seconds) the Insight Enrichment Server should check for new Insights. 

Default: 10
post_workers no The number of parallel workers (threads) posting enrichment results. 

Default: 6
enrichment_workers no The number of parallel workers (threads) running enrichment tasks. 

Default: 12

Enrichment settings

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

Each enrichment should be given its own 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.  

Setting Required? Description
enrichment_type yes Specifies the type of the enrichment. Currently, the only supported value is:
command
entity_type yes The type of entity to enrich. The supported values are: IP, mac, and hostname.
cache_time no The length of time (in seconds) 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.

Default: none
ip_range no When 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_exe yes The executable to run when enriching the entity.
command_args yes The arguments to pass to the executable specified by command_exe when performing the enrichment. Note the value ${IP} will be replaced by the entity IP address for entity type IP. The value ${HOSTNAME} will be replaced with the entity hostname for hostname entities. The value ${MAC} will be replaced with the entity MAC address entities.
command_timeout  no A 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://<>.portal.jask.ai
api_key = <>
log_level = info

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

[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 = 100000000000

[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 = 1000000000000

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

[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

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. 

Script:  c:\scripts\CB.ps1

param([string]$IP)
"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

carbon-black.png

CrowdStrike enrichment

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

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\Jask\EnrichmentService\CS.ps1 ${IP}
ip_range = 192.168.38.104-192.168.38.105

Enrichment in the UI

crowdstrike.png

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.

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}