splunk
SOLACE Splunk API CIM Model
Overview
Details
The SOLACE: Splunk API CIM Model standardizes API transaction audit data within Splunk, enabling better visibility and detection of API-related attacks and vulnerabilities. This model enables the effective capture of API events which enables effective operational and security reporting. This extension to the CIM Model closes a gap in capturing important events that can be critical to an organization's security posture.
This model is leveraged by the separately available SOLACE: ServiceInsights application to facilitate dozens of security use cases and operational dashboards. The model helps capture and structure detailed API information that can highlight critical security events often missed by default logging configurations.
For organizations looking to extend their API security and operational capabilities, or needing further support, contact us to learn more about how our experienced team can help implement advanced API security solutions.
This model is leveraged by the separately available SOLACE: ServiceInsights application to facilitate dozens of security use cases and operational dashboards. The model helps capture and structure detailed API information that can highlight critical security events often missed by default logging configurations.
For organizations looking to extend their API security and operational capabilities, or needing further support, contact us to learn more about how our experienced team can help implement advanced API security solutions.
API Transaction
The fields and tags in this model describe an API transaction audit event that is logged after the completion of an API transaction or single operation. These may be transaction logs received from an API Transaction, proxy, an API implementation itself.
General note: Any field with ‘ID’ in the name is designed to be a unique identifier, whereas the equivalent field without ID is designed to be a human-readable name. The ID field need not be numeric, however, and if there’s an alpha-numeric string which is unique this can be populated into the ID field and the equivalent human-readable name field.
Tags used with API Transaction event datasets
The following tags act as constraints to identify your events as being relevant to this data model.
| Dataset name | Tag name |
|---|---|
| API Transaction | api_gw |
Fields for API event datasets
The following table lists the extracted and calculated fields for the event datasets in the model. The table does not include any inherited fields.
General Fields
| Dataset name | Field name | Data type | Description | Notes |
|---|---|---|---|---|
| API Transaction | time | Datetime | Date and timestamp for when the request or response arrives at the platform (gateway/container). | Required |
| API Transaction | src_ip | String | The IP address of the source. The IP the request originated from such as a load balancer or gateway that proxies the request to the server receiving it (the TCP/IP IP address of the request). Could be IPv6 or IPv4. | Required |
| API Transaction | client_ip | String | The IP request of the originating requester/API consumer (if known). This should be the original client if available (such as x-forward-for or x-real-ip header value). This must be populated with an IP, and should contain src_ip if client_ip is unknown. Could be IPv6 or IPv4. | Required |
| API Transaction | service | String | Maps to the service name (protected service in a gateway). | Conditional |
| API Transaction | service_id | String | Maps to the service identifier (protected service in a gateway). | Conditional |
| API Transaction | operation | String | Maps to the operation name in the service (protected service operation in a gateway). | Conditional |
| API Transaction | operation_id | String | Maps to the operation identifier in the service (protected service operation in a gateway). | Conditional |
| API Transaction | service_ver | String | The version of the service accessed. Examples are: v1, v1.0, 1.0, 1_1. | Recommended |
| API Transaction | service_root | String | The name used to correlate multiple versions of a single API. For example, accounts_v1, accounts_v2, and accounts_v2.1 may have the shared service_root of accounts, in that they are different versions of the same service for the same functions. Service and service_Id are unique whereas service_root will be identical across services. | Recommended |
| API Transaction | service_root_id | String | The ID used to correlate multiple versions of a single API. For example, accounts_v1, accounts_v2, and accounts_v2.1 may have the shared service_root of accounts, in that they are different versions of the same service for the same functions. Service and service_Id are unique whereas service_root will be identical across services. | Recommended |
| API Transaction | service_type | Field | The major protocol of the service in terms of standard/classification type. Examples are: soap, rest, graphQL | Required |
| API Transaction | error_code | String | The error code provided to the client if the request has been deemed to have failed (ie: anything but a 200 series HTTP response code, typically. This code is service or platform specific and not the same as the HTTP status returned). In a gateway, this will be provided by the gateway in the event of a gateway blocking or failing to respond to a request. | Required |
| API Transaction | error_message | String | The error message provided to the client if the request has been deemed to have failed (ie: anything other than a 200-series HTTP response code, typically, but this message is service or platform specific and NOT the same as the HTTP status code message returned). In a gateway, this will be provided by the gateway in the event of a gateway blocking or failing to respond to a request. | Recommended |
| API Transaction | error_class | String | The error classification or grouping of the error_code. This can be useful to report on error groupings. For example, client_authn for client authentication issues. | Optional |
| API Transaction | error_source | String | If an error is provided to the client from a gateway, this is the source of the error in broad terms (ie: a problem with the request leg, or the response leg, or internal). | Optional |
| API Transaction | site_id | String | An ID for a site. A site is typically a particular datacenter or datacenter zone - usually a locally grouped logical service entry point for a gateway. | Recommended |
| API Transaction | site | String | This is the human-readable name for a site. Site is typically a particular datacenter or datacenter zone - usually a locally grouped logical service entry point for a gateway. | Recommended |
| API Transaction | correlation_id | String | An ID provided by the consumer used to correlate multiple API transactions. It is typically used to correlate several API calls or actions rather than one logical action. Typically from the X-Correlator-ID header, but may be from other sources. The field should be returned to the consumer as passed. | Recommended |
| API Transaction | internal_trace_id | String | Any unique transaction or trace ID that allows any internal logs or events to be correlated. Should be different from request_id and correlation_id unless a gateway generated the request_id. | Optional |
| API Transaction | auth_type | String | This field should record the authentication or authorization mechanism(s) used to secure this API request. This might be a multi-value field. Try to map to a common set for your organization. Examples: oauth1, oauth2cc (Oauth2 client credential), oauth2auth (OAuth2 authentication token), apikey, userpass (where the API key string is made up of a base64 user/password combo), none, token, jwttoken, sslclient (SSL client certificate), bio (biological indicator). | Required |
| API Transaction | uri | String | Originally requested URI portion from the request URL (excludes protocol, host, and port). | Required |
| API Transaction | final_url | String | Final URL if modified by the gateway. | Required |
| API Transaction | status | Numeric | HTTP response code provided to the client. | Yes - Protocol |
| API Transaction | http_ver | Field | The version of HTTP used for the request (downstream HTTP protocol version may differ in the case of a transformation in a gateway and should be logged seperately). | Recommended |
| API Transaction | http_final_ver | Field | The version of HTTP used for the downstream request is modified by a gateway. Missing if not changed. | Recommended |
| API Transaction | http_method | Field | Note, for the extension method, the http_method_ext field should contain the value provided in the request. | Yes - Protocol |
| API Transaction | http_method_ext | String | The extension HTTP method provided by the client in the request. Must be logged if the method is 'ext'. | Yes - Protocol |
| API Transaction | final_method | Field | Final HTTP method sent downstream by the gateway. Note, for the extension method, the final_method_ext field should contain the value provided in the request. | Yes - Protocol |
| API Transaction | final_method_ext | String | Final HTTP extension method sent downstream by the gateway. The extension HTTP method is provided by the client in the request. Must be logged if the method is 'ext'. | Yes - Protocol |
| API Transaction | accept_type | String | Logged if provided by the client, but may not be included. | Optional |
| API Transaction | final_accept_type | String | Logged if the request accept type is modified by the gateway. Missing if not changed. | Optional |
| API Transaction | tags | Multiple | One or multiple tags used to identify categories of APIs for reporting purposes. For example: sensitive,time-specific, or admin-only endpoints. | Optional |
| API Transaction | app_uuid | String | A unique identifier for the consumer application identity, when an application identity is involved in the request (ie: B2B). | Optional |
| API Transaction | user_uuid | String | A unique identifier for the verified user accessing the endpoint when a personal identity is involved in the API request. | Recommended |
Request Fields
| Dataset name | Field name | Data type | Description | Notes |
|---|---|---|---|---|
| API Transaction | req_content_type | String | Content type of the request, if provided. | Recommended |
| API Transaction | req_final_content_type | String | Content type of the final HTTP request. | Recommended |
| API Transaction | req_bytes | Numeric | Total size of the HTTP response (excluding headers) in bytes. | Recommended |
| API Transaction | req_final_bytes | Numeric | Total size of the final HTTP response (including headers) in bytes. Logged only if the response is modified by the gateway. | Recommended |
| API Transaction | req_payload_bytes | Numeric | Total size of the HTTP response (excluding headers) in bytes. | Recommended |
| API Transaction | req_charset | String | Character set encoding of the request, ie: UTF-8. | Optional |
| API Transaction | req_final_charset | String | Character set encoding of the final request, ie: UTF-8. Logged only if the request is modified by the gateway. | Optional |
| API Transaction | req_final_payload_bytes | Numeric | Total final size of HTTP payload in the request. Logged only if the payload is modified by the gateway. | Recommended |
Response Fields
| Dataset name | Field name | Data type | Description | Notes |
|---|---|---|---|---|
| API Transaction | res_content_type | String | Content type of the request, if provided. | Recommended |
| API Transaction | res_final_content_type | String | Content type of the response. Logged if the response content type is modified by the gateway. Logged only if the response content type is modified by the gateway. | Recommended |
| API Transaction | res_bytes | Numeric | Total size of the HTTP response (excluding headers) in bytes. | Recommended |
| API Transaction | res_final_bytes | Numeric | Total size of the final HTTP response (including headers) in bytes. Logged only if the response is modified by the gateway. | Recommended |
| API Transaction | res_payload_bytes | Numeric | Total size of the HTTP response (excluding headers) in bytes. | Recommended |
| API Transaction | res_final_payload_bytes | Numeric | Final payload size (excluding headers) in bytes. Logged only if the response is modified by the gateway. Zero if the gateway removes the payload. | Recommended |
| API Transaction | res_status | Numeric | The response HTTP status code provided by the backend. Will only be present if a downstream call was made and the downstream server responded. Must be logged if a downstream request was made. May be different from the http_status. | Required |
| API Transaction | res_charset | String | Character set encoding of the response, ie: UTF-8 received from the backend (and sent to the client, if not modified by a gateway). | Optional |
| API Transaction | res_final_charset | String | Logged if the response character encoding type of the payload is modified by the gateway. Missing if not changed. Character set encoding of the response, ie: UTF-8 | Optional |
| API Transaction | response_time | Numeric | Overall time in milliseconds taken to respond to the request from the moment it was received until the response was returned to the requestor/client. | Required |
| API Transaction | response_time_internal | Numeric | Total time, in milliseconds spent by the gateway processing the request. Specific to API Transactions/proxies. | Optional |
| API Transaction | response_time_backend | Numeric | Total time, in milliseconds, spent waiting for the backend(s) to respond. Typically used by API Transactions/proxies, but could be used in an API implementation to indicate downstream API, database (or other) calls. | Recommended |
Release Notes
Version 1.0.0
Nov. 14, 2024