Version: 6.x-21
This is an older version of Search Guard. Switch to Latest version
Compliance

Elasticsearch configuration tracking

To use the compliance features please install the Search Guard Compliance Edition

Search Guard is able to monitor the integrity of your Elasticsearch installation and emit events describing your current configuration.

These features help to detect any changes to your Elasticsearch or Search Guard installation and for proofing that you applied critical fixes and upgrades in time.

The way Elasticsearch can be configured includes

  • Setting in elasticsearch.yml
  • Environment variables used in elasticsearch.yml
  • Java properties
  • Files used by Search Guard like PEM certificates, keystores or Kerberos keytabs

On node startup, Search Guard will emit an event that contains these settings and their respective sha256 checksum.

Enabling and disabling

The elasticsearch configuration monitoring can be switched on an off by the following entry in elasticsearch.yml:

Name Description
searchguard.compliance.history.external_config_enabled boolean, whether to enable or disable elasticsearch configuration logging. Default: true

Audit log category

The Elasticsearch configuration events are logged in the COMPLIANCE_EXTERNAL_CONFIGcategory.

Field reference

Format, timestamp and category attributes

Name Description
audit_format_version Audit log message format version, current: 3
audit_utc_timestamp UTC timestamp when the event was generated
audit_category Audit log category, COMPLIANCE_EXTERNAL_CONFIG for all events

Cluster and node attributes

Name Description
audit_cluster_name Name of the cluster this event was emitted on.
audit_node_id The ID of the node where the event was generated.
audit_node_name The name of the node where the event was generated.
audit_node_host_address The host address of the node where the event was generated.
audit_node_host_name The host address of the node where the event was generated.

Configuration attributes

Name Description
audit_compliance_file_infos All external files referenced in the configuration, with modification date and sha256 checksum.
audit_request_body Detailed configuration information as JSON string.

File information

The audit_compliance_file_infos key contains an array that lists all files used by Search Guard that are configured in elasticsearch.yml. Example:

"audit_compliance_file_infos" : [
   {
     "path" : "/etc/elasticsearch/truststore.jks",
     "sha256" : "502be6ca9080666271ee9122998e6793e19fda080be095da60bab5aae8243f17",
     "last_modified" : "2018-03-13T12:10:29.000+00:00",
     "key" : "searchguard.ssl.http.truststore_filepath"
   },
   {
     "path" : "/etc/elasticsearch/CN=sgssl-0.example.com,OU=SSL,O=Test,L=Test,C=DE-keystore.jks",
     "sha256" : "9a5058ca0efb0068aeafc307f86d4af48274dab315702e014e1cdaf4bcc32f3b",
     "last_modified" : "2018-03-13T12:10:29.000+00:00",
     "key" : "searchguard.ssl.transport.keystore_filepath"
   },
   {
     "path" : "/etc/elasticsearch/sgssl-0.example.com.http_srv.keytab",
     "sha256" : "bb12b7483d9c449ac27cf6e6c698172bf227dc1ea1892d9e27732071731b9f8c",
     "last_modified" : "2018-03-15T16:27:50.522+00:00",
     "key" : "searchguard.kerberos.acceptor_keytab_filepath"
   }
   ... 
]
Name Description
path Absolute path to the file
sha256 SHA256 checksum of the file
last_modified Last modification date of the file
key The configuration key in elasticsearch.yml this file is referenced by.

Configuration information

The detailed configuration settings can be found in the audit_request_body field of the generated event. The value is a JSON string with three keys:

Name Description
external_configuration The content of the elasticsearch.yml on node startup
os_environment Environment variables on node startup
java_properties Java properties on node startup
sha256_checksum SHA256 checksum of the combined external_configuration, os_environment and java_properties. Can be used to detect any changes to your Elasticsearch installation.

External configuration

The external_configuration contains the elasticsearch.yml settings on node startup as JSON String. Example:

{
	"external_configuration": {
		"elasticsearch_yml": {
			"searchguard": {
				"compliance": {
					"disable_anonymous_authentication": "true",
					"history": {
						"external_config_enabled": "true",
						"read": {
							"watched_fields": ["humanresources,Designation,FirstName,LastName"],
							"ignore_users": ["admin"]
						},
						"write": {
							"diffs_only": "true",
							"ignore_users": ["finance_trainee"],
							"watched_indices": ["finance"]
						},
						"metadata_only": "false"
					}
				},
				"kerberos": {
					"acceptor_principal": "HTTP/sgssl-0.example.com",
					"krb5_filepath": "/etc/krb5.conf",
					"acceptor_keytab_filepath": "sgssl-0.example.com.http_srv.keytab"
				},
				...
			}
		}
	}
}

Note: Since the JSON object is stored as String, the quotation marks are escaped in the originl output. Depending on your JSON parser you might need to remove them first.

Environment variables

The os_environment key contains all environment variables as String. Example:

"LANGUAGE=en_US:en, 
PATH=/usr/share/elasticsearch/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:
-Dsun.security.krb5.debug=false
-Dsun.security.spnego.debug=false
..."

Java properties

The java_environment key contains all java properties as String. Example:

"java.version=1.8.0_151
java.vendor.url=http://java.oracle.com/
-Enetwork.host=sgssl-0.example.com
-Esearchguard.ssl.http.keystore_filepath=keystore.jks
-Esearchguard.kerberos.acceptor_keytab_filepath=sgssl-0.example.com.http_srv.keytab
..."