Configure the Illumio Technology Add-On for Splunk
After installing the Illumio TA, you will need to configure the Illumio modular input and a TCP receiver for Syslog events from the PCE.
Start by creating a PCE API key to use when setting up the input.
Create a User-Scoped API Key
In the PCE, open the user menu drop-down in the top-right corner of the page, and select My API keys.
Click Add, note the Org ID shown in the dialog, and enter a display name for the key.
Click Create, and then copy or download the API key credentials and store them somewhere secure.
Create a Service Account API Key
The Org ID value is not shown when you create a Service Account key. It is displayed when you create a User API key, as described in Create a User-Scoped API Key.
Note
The Org ID value is not shown when you create a Service Account key. It is displayed when you create a User API key, as described in the preceding procedure.
In the PCE, open the Access submenu on the left side of the screen and select Service Accounts.
Click Add, and enter a display name and one or more Roles to assign to the key. The TA-Illumio Add-On requires only read-only access to policy object endpoints, so the Global Viewer role should be sufficient.
Note
To use the workload quarantine action, the API key that is used for the input must have write permissions for workloads.
Click Save, and then copy or download the API key credentials and store them somewhere secure.
Warning
Service Account API keys have a default lifetime of 90 days. Take note of the expiration data for your key and replace it before it expires.
Configure the Illumio Modular Input
Navigate to Settings > Data inputs and find the Illumio input type.
Click the + Add New action to create a new input.
Enter a display name for the input and the connection details for your PCE. Enter the Organization ID and API key username and secret values copied from the steps above.
(On-prem only) To receive syslog events forwarded from an on-prem PCE, a TCP input must be configured in Splunk. Setting the Syslog Port (TCP) value will automatically create one when the input runs if it does not already exist. The Enable TCP-SSL option determines whether a [tcp-ssl] or [tcp] stanza will be created (See Configure TCP SSL for more information.)
Adjust any of the remaining parameters as needed. Make sure that the index is set correctly. (Check the More settings checkbox to display additional settings.) To enable automated quarantine using the illumio_quarantine action, specify one or more labels that make up a quarantine policy scope in the PCE in the Quarantine Labels field.
Click Next. If an error dialog appears, double-check the field values and refer to the Troubleshooting section.
Parameter | Description | Required | Default Value | Example Value |
|---|---|---|---|---|
Name | Modular input display name. Must be unique. | Y | - | mypce_input |
PCE URL | The full URL of the Illumio PCE to connect to. If a scheme is not provided, https:// is used by default. If a port is not provided, it is assumed to be the default for the given scheme (80 for HTTP, 443 for HTTPS). | Y | - | https://my.pce.com:8443 |
Organization ID | The ID number of the PCE organization to connect to. | Y | 1 | - |
API Key Username | The API key ID to use when connecting to the PCE. | Y | - | api_145a5c788e63c30a3 |
API Key Secret | The API key secret to use when connecting to the PCE. | Y | - | - |
Syslog Port (TCP) | Designates a port on the Splunk server to receive syslog events from the Illumio PCE. There must not be an existing TCP input for the given port. Only used for direct forwarding from the PCE. Syslog events pulled from Amazon S3 must be configured separately using the AWS S3 TA. | N | - | 514 |
Enable TCP SSL | Toggles SSL for the created TCP syslog input. The [SSL] stanza must be configured separately. | N | True | - |
Port Scan Interval | The interval, in seconds, within which Port Scan Threshold scanned ports will trigger an alert. | Y | 60 | - |
Port Scan Threshold | Defines a threshold that will trigger an alert when more than the configured number of ports are scanned within Port Scan Interval seconds. | Y | 10 | - |
Port Scan Allowed IPs | Comma-separated list of source IP addresses to exempt from port scan alerts. | N | - | 10.0.0.1,10.0.0.2 |
Quarantine Labels | Optional comma-separated list of label key:value pairs that represent a quarantine zone scope in the PCE. Configured labels are applied to selected workloads when the illumio_quarantine action is run. The labels must exist in the PCE and any policy that restricts access to the quarantine zone must be defined separately. It must be of the form key1:value1,...,keyN:valueN Keys and values are case-sensitive. | N | - | app:A-Quarantine,env:EQuarantine, loc:L-Quarantine |
CA Certificate Path | Optional path to a custom CA certificate bundle | N | - | $SPLUNK_HOME/etc/ apps/TA-Illumio/certs/ ca.pem |
HTTP Proxy Address | HTTP proxy address. | N | - | http://my.proxy-server. com:8080 |
HTTPS Proxy Address | HTTPS proxy address. | N | - | https://my.proxy-server. com:8443 |
HTTP Retry Count | Number of times to retry the connection to the PCE. | N | 5 | - |
HTTP Retry Interval | The total HTTP request timeout for the PCE in seconds. | N | 30 | - |
Interval | Input run schedule in seconds or as a cron expression. | Y | 1800 | */30 * * * * |
Index | Splunk index for the input to write events to. | Y | default (main) | - |
Configure TCP SSL
To configure syslog forwarding encrypted with TLS, both a [tcp-ssl] stanza and an [ssl] stanza must be configured in $SPLUNK_HOME/etc/apps/TA-Illumio/local/inputs.conf.
The TCP-SSL stanza will be created automatically as described above, but the `[SSL]` stanza must be created manually. This step only needs to be done once for any number of Illumio inputs.
When using an existing certificate authority, generate a server certificate for Splunk with the CN or SAN set to the Splunk instance hostname or IP address.
When using a self-signed certificate, see the How to create and sign your own TLS certificates. Make sure that the root CA certificate is created with extensions and the ca flag is set to true (checked by syslog-ng validation).
Create the SSL stanza with the following fields:
[SSL] serverCert = /path/to/my/splunk_server.crt sslPassword = splunk_server_cert_pass
Restart Splunk.
Note
Do not use the Splunk default certificates when configuring SSL.
Configure Syslog Forwarding for On-Prem PCEs
In the PCE, open the Settings submenu on the left side of the screen and select Event Settings.
Click Add to create a new Event Forwarding rule.
Select the event types to forward to Splunk.
Click Add Repository.
Enter a description for the repository and the Splunk hostname/IP and the port value of the TCP stanza created for the Illumio input. Leave the protocol value as TCP.
If TCP-SSL is configured in Splunk for the target port, set the TLS field to Enabled and upload a certificate bundle containing the root and any intermediate certificates in the chain for your CA.
Note
If you are enabling TLS, the address value must match the CN or SAN of the Splunk server certificate.
Select the Verify TLS option to ensure that your certificates and TLS configuration are valid.
Click Add and select the option for the created repository.
Click Save.
A test event will be sent to Splunk to verify the connection.
In Splunk, run the following search to make sure that the test event arrived:
index=illumio_index sourcetype="illumio:pce" "Testing syslog connection from PCE"
Configure Syslog Forwarding for Cloud PCEs
Reach out to Illumio Customer Support to configure Syslog event forwarding to AWS S3. The target bucket can be internal or managed by Illumio.
After the bucket is configured, make sure the Syslog files are being sent.
Install the AWS S3 TA from Splunkbase.
Follow the configuration instructions for Generic S3 inputs in the AWS S3 TA documentation.
Create two inputs, one for auditable events and one for collector (traffic flow) events.
In each input, specify a Log File/S3 Key Prefix with the path to either auditable or collector event logs within the S3 bucket.