Single Sensor Multi-tenant Log Ingestion

For multi-tenant deployments, you typically configure a single modular sensor to ingest logs from separate tenants. Optionally, you can consolidate this task to a single sensor. The details below identify which vendors log files are currently supported for this feature, along with the associated configuration steps.

Requirements

The capability for this feature must be specifically enabled. As of v4.3.1 the functionality is off by default and must be toggled on in the Sensor Profile. To enable it, access the Log Forwarder section of your Standard Sensor profile, then locate the toggle for Multi-Tenant Log Ingestion. After it is enabled, you can send data from the following vendors:

• These include the Tenant ID field needed to support this feature:

  • Infocyte (CEF), port 5143 

  • Blackberry Cylance, port 5177

• These are supported for use on port 5564 if submitted in the Stellar Cyber JSON format indicated below.

  • Palo Alto Networks Firewall (syslog, cef, leef)

  • SonicWall Firewall (syslog or cef)

  • Cisco Meraki (syslog)

  • Fortinet Fortigate (syslog)

Stellar Cyber JSON Format for Multi-Tenant Parsing

This required format consists of four parts:

• stellar: This required field is used to specify that the file is in Stellar Cyber format.

• tenantid: Specify the tenant ID. If this value is not present, the Tenant ID associated with the sensor is used.

• msg_origin: This wrapper label is required for parsing on the multi-tenant port. Use the following table for guidance with the relevant fields.

  Vendor	Product	Format
  palo_alto_networks	firewall	syslog cef leef
  sonicwall	firewall	syslog cef
  cisco	meraki	syslog
  fortinet	fortigate	syslog

  • vendor and product: Both of these values in the msg_origin block are required. They are used to identify which Stellar Cyber parser will handle the original log

  • format: If this value is not present, syslog is used

  • srcip: This value should be the IP address of the original log source.  It is optional, but including it results in better log ingestion statistics.

• parser_raw_msg: If this required content is missing, the record is discarded.

  Since the raw data is wrapped in double quotes, ensure that the pre-processor you use to create this record injects an escape before all double quotes in the original log file.

The field labels are illustrated here:

{
  "stellar": {
    "tenantid": " ",
    "msg_origin": {
      "vendor": " ",
      "product": " ",
      "format": " ",
      "srcip": " "
    }
  },
  "parser_raw_msg":"  "
}

An example Stellar Cyber JSON record is shown here (data is truncated)

{
  "stellar": {
    "tenantid": "12345678",
    "msg_origin": {
      "vendor": "palo_alto_networks",
      "product": "firewall",
      "format": "syslog",
      "srcip": "192.168.100.74"
    }
  },
  "parser_raw_msg":"<134>Nov 11 2020 21:55:21 ..."
}

In v5.1.1, Stellar Cyber released a built-in Exium parser that supports multi-tenancy. To set up Exium to provide Stellar Cyber with the tenant ID for the logs it sends, log in to the Exium Admin Console and configure the tenant ID for each tenant and the URL of the Exium parser on the Stellar Cyber sensor to which Exium tenants send logs (https://<sensor_ip_addr>:5200/httpjson). With Multi-Tenant Log Ingestion enabled on the sensor profile, the Stellar Cyber platform associates the logs it ingests with the various Exium tenants that send them. For configuration instructions from Exium, see StellarCyber SIEM Integration.

While some third-party products like Exium have added settings to their systems to integrate with Stellar Cyber and provide tenant IDs with the logs they send, others have not. However, these systems can still support multi-tenancy if you configure the devices that send logs to the multi-tenant parser to add their tenant ID to either JSON payloads or custom HTTP headers before they send their logs. Stellar Cyber v5.2.0 supports both methods. The option you choose depends on the capabilities of the devices sending the logs.

If your devices let you configure the log-forwarder that runs on them to include a tenant ID in the JSON payloads of the logs they send, then configure them to do that. The following is an example log message that includes the tenant ID in the JSON payload.

curl -X POST -d '{"tenantid": "67379250", "Event Type": "Device", "Event Name": "SystemSecurity", "Device Name": "SGI-TWR-B00XQS3", "Agent Version": "3.1.1001.15", "IP Address": "10.1.1.100", "MAC Address": "112233BB12AB", "Logged On Users": "ACME\jsmith", "OS": "Microsoft Windows 10", "Kernel Version": "10.0.19042", "Optics Version": "3.0.1178.0", "Zone Names": "Acme Workstations"}' 10.1.1.25:5200/httpjson

If your devices don’t let you modify the JSON payload like this, consider using custom HTTP headers instead.

If your devices let you add a custom HTTP header with a tenant ID to their HTTP output, then configure the log-forwarder on these devices to include the tenant ID in the custom HTTP header when they send logs to the parser. The following is an example log message that includes the tenant ID in the HTTP header.

curl -X POST -H "Stellar-TenantID: 67379250" -d ‘{"Event Type": "Device", "Event Name": "SystemSecurity", "Device Name": "SGI-TWR-B00XQS3", "Agent Version": "3.1.1001.15", "IP Address": "10.1.1.100", "MAC Address": "112233BB12AB", "Logged On Users": "ACME\jsmith", "OS": "Microsoft Windows 10", "Kernel Version": "10.0.19042", "Optics Version": "3.0.1178.0", "Zone Names": "Acme Workstations"}' 10.1.1.25:5200/httpjson

If your devices don’t let you add an HTTP custom header to logs like this, you can configure them to forward logs to an NGINX server. Configure that to add a custom HTTP header with a tenant ID based on information identifying the source of the logs it receives, such as the source IP address, before forwarding them to the parser.

The following is a configuration example for an NGINX server to add a custom HTTP header with the parser URL and tenant ID to logs based on source IP address.

server {
	listen 80;
	set $stellar_tenantid "default_tenantid";
	if ($remote_addr = "10.1.1.1") {
		set $stellar_tenantid "tenantid_a";
	}
	if ($remote_addr = "10.2.1.1") {
		set $stellar_tenantid "tenantid_b";
	}
	location / {
		proxy_pass http://<stellar-device-sensor>:<http-parser-port>;
		proxy_set header Stellar-TenantID $stellar_tenantid;
	}
}

When a log reaches the NGINX server from 10.1.1.1, the server sets the Stellar-TenantID header as tenantid_a and forwards it to the specified URL and port number of the multi-tenant parser. When a log reaches the NGINX server from 10.2.1.1, it sets the Stellar-TenantID header as tenantid_b and forwards it to the same URL and port number of the parser. Finally, if a log reaches the NGINX server from any other IP address, it sets the Stellar-TenantID header as default_tenantid and forwards it to the same destination as the others. In this way, Stellar Cyber can distinguish logs from different tenants using a single sensor with a multi-tenant parser.

Multi-Tenant Log Ingestion must be enabled in the sensor profile (System | Collection | Sensor Profiles) for Stellar Cyber to recognize the tenant ID included in logs. If this isn’t enabled, Stellar Cyber uses the tenant ID of the sensor instead.