Mapping Keywords
There are keywords which need to be specified in the to-stix mappings in order to perform specific operations on the datasource fields. There are two types of keywords:
Required
Optional
The below table contains the keywords and their usages:
Required Keywords
| Keywords | Type | Descriptions | Usage | Example | key | String | The STIX object and properties whose path is defined in dot notation. | "key": "stix-object.stix-object-property.sub-property" |
{
"sha256hash": {
"key": "file.hashes.SHA-256",
"object": "fl"
}
}
|
object | String | The name specified in the object is used to add properties of same the object. | "object": "src_ip" |
{
"sourceip": {
"key": "ipv4-addr.value",
"object": "src_ip"
}
}
|
|---|
Optional Keywords
| Keywords | Type | Descriptions | Usage |
|---|---|---|---|
| references | String/List(string) | Specifies named objects to reference in another object. | "references": "src_ip" "references": ["dst_mac"] |
| transformer | String | The function applied to the datasource value when writting data to STIX. | "transformer": "ToInteger" |
| value | Any | A constant (literal) value to assign to the target STIX property. | "value": "test" |
| unwrap | Boolean | Unwrap an array of STIX values to separate STIX objects if the keyword value is set to True | "unwrap": true |
| group | Boolean | Combine the references into a list | "group" : true |
| group_ref | Boolean | This keyword needs to be used when there is a nested list of dictionaries and each dictionary item creates an object. This keyword groups together references in a list and sets where the object is mapped. To do that, create a mapping field under same nested dictionary as the datasource field and specify the mappings. See the group_ref Examples section for more details. | "group_ref": true | ds_key | String | This keyword is used when datasource results are formatted to modify some field names. The value assigned to the keyword determines the mapping of a STIX object. This keyword is only used in the aws_athena and aws_cloud_watch_logs modules to resolve nested dictionary mappings. This keyword has been deprecated since nested dictionary mappings are now handled by the JSON to STIX translation utility. | "ds_key": "resource_instancedetails" |
Examples of Optional keywords:
unwrap
Mapping:
"resolved_ip": [
{
"key": "ipv4-addr.value",
"object": "resolved_ip",
"unwrap": true
}
]
}
Datasource Result:
{
"resolved_ip": [
"40.116.120.16", "1.2.3.4"
]
}
STIX Translation
This STIX bundle contains two ipv4-addr objects which are created based on unwrap keyword:
{
"type": "bundle",
"id": "bundle--f3b77b73-f21f-49b8-be6b-6034b47f5b60",
"objects": [
{
"type": "identity",
"id": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"name": "elastic_ecs",
"identity_class": "events",
"spec_version": "2.0",
"created": "2022-03-23T14:15:56.519Z",
"modified": "2022-03-23T14:15:56.519Z"
},
{
"id": "observed-data--ad31fb85-7723-4923-bb68-fa52e101e9b9",
"type": "observed-data",
"created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created": "2023-07-20T14:36:18.711Z",
"modified": "2023-07-20T14:36:18.711Z",
"objects": {
"0": {
"type": "ipv4-addr",
"value": "40.116.120.16"
},
"1": {
"type": "ipv4-addr",
"value": "1.2.3.4"
}
},
"first_observed": "2019-04-21T11:05:07.000Z",
"last_observed": "2019-04-21T11:05:07.000Z",
"number_observed": 1
}
],
"spec_version": "2.0"
}
group
Mapping:
{
"sourceip": [
{
"key": "ipv4-addr.value",
"object": "host_ip"
},
{
"key": "x-oca-asset.ip_refs",
"object": "host",
"references": ["host_ip"],
"group": true
}
],
"identityip": [
{
"key": "ipv4-addr.value",
"object": "host_ip_addr_v4"
},
{
"key": "x-oca-asset.ip_refs",
"object": "host",
"references": ["host_ip"],
"group": true
}
]
}
Datasource Result:
{
"identityip": "127.0.0.1",
"sourceip": "10.10.10.10",
"identityhostname": "host.com"
}
STIX Translation
ip_refs STIX property contains two reference objects which is grouped together in a list when group keyword is used:
{
"type": "bundle",
"id": "bundle--8d3b18d9-cbc4-4788-83e7-dd1e6a9026c9",
"objects": [
{
"type": "identity",
"id": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"name": "qradar",
"identity_class": "events",
"spec_version": "2.0",
"created": "2022-03-23T14:15:56.519Z",
"modified": "2022-03-23T14:15:56.519Z"
},
{
"id": "observed-data--9b7896ba-7a1a-4417-a61b-61b15b017721",
"type": "observed-data",
"created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created": "2023-07-20T18:06:32.907Z",
"modified": "2023-07-20T18:06:32.907Z",
"objects": {
"0": {
"type": "ipv4-addr",
"value": "127.0.0.1"
},
"1": {
"type": "x-oca-asset",
"ip_refs": [
"0",
"3"
],
"hostname": "host.com"
},
"3": {
"type": "ipv4-addr",
"value": "10.10.10.10"
}
},
"first_observed": "2023-07-20T18:06:32.907Z",
"last_observed": "2023-07-20T18:06:32.907Z",
"number_observed": 1
}
],
"spec_version": "2.0"
}
group_ref
Mapping:
A custom field needs to be created to use the group_ref keyword. The name of the field can be anything. Make sure the mapping is defined under same nested dictionary as datasource fields. In this example, groupReference is the custom field. The reference object is target hence groupReference is placed under "target":{}. The x_target_refs property will store the references of target objects in x-oca-event object. You must specify "group_ref": true in the mapping for groupReference custom field.
{
"eventType": {
"key": "x-oca-event.action",
"object": "event"
},
"target": {
"id": {
"key": "x-okta-target.target_id",
"object": "target"
},
"type": {
"key": "x-okta-target.target_type",
"object": "target"
},
"groupReference": {
"key": "x-oca-event.x_target_refs",
"object": "event",
"references": [
"target"
],
"group_ref": true
}
}
}
Datasource Result:
“target” datasrouce field contains nested dictionaries. The above mapping will create two x-okta-target objects and a x-oca-event object from the below datasource result.
{
"eventType": "user.authentication.auth_via_mfa",
"target": [
{
"id": "00u7rkrly9sNvp7sa5d7",
"type": "User",
"alternateId": "user1@login.com",
"displayName": "user1"
},
{
"id": "pfd7rkr4nqHLoMqI85d7",
"type": "AuthenticatorEnrollment",
"alternateId": "unknown",
"displayName": "Okta Verify",
}
]
}
STIX Translation
Two x-okta-target objects(1 and 2) are referenced in x_target_refs property inside x-oca-event object when group_ref keyword is used in the mapping.
{
"id": "observed-data--c0b44436-3f99-4d39-ade0-509c65e990d4",
"type": "observed-data",
"created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created": "2023-11-29T18:16:13.340Z",
"modified": "2023-11-29T18:16:13.340Z",
"objects": {
"0": {
"type": "x-oca-event",
"action": "user.authentication.auth_via_mfa",
"x_target_refs": [
"1",
"2"
]
},
"1": {
"type": "x-okta-target",
"target_id": "00u7rkrly9sNvp7sa5d7",
"target_type": "User"
},
"2": {
"type": "x-okta-target",
"target_id": "pfd7rkr4nqHLoMqI85d7",
"target_type": "AuthenticatorEnrollment"
}
},
"first_observed": "2023-11-29T18:16:13.340Z",
"last_observed": "2023-11-29T18:16:13.340Z",
"number_observed": 1
}
value
Mapping:
{
"event": {
"original": [
{
"key": "artifact.payload_bin",
"transformer": "ToBase64",
"object": "artifact"
},
{
"key": "artifact.mime_type",
"object": "artifact",
"value" : "text/plain"
}
]
}
}
Datasource Result:
{
"@timestamp": "2019-04-21T11:05:07.000Z",
"event": {
"original": "10.42.42.42 - - [07/Dec/2018:11:05:07 +0100] \"GET /blog HTTP/1.1\" 200 2571 \"-\" \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36\""
}
}
STIX Translation
mime_type value has been set from the mapping value keyword:
{
"id": "observed-data--fb592d78-942b-4829-9a3e-aacb14f9eb27",
"type": "observed-data",
"created_by_ref": "identity--3532c56d-ea72-48be-a2ad-1a53f4c9c6d3",
"created": "2023-07-20T19:08:18.458Z",
"modified": "2023-07-20T19:08:18.458Z",
"objects": {
"0": {
"type": "artifact",
"payload_bin": "MTAuNDIuNDIuNDIgLSAtIFswNy9EZWMvMjAxODoxMTowNTowNyArMDEwMF0gIkdFVCAvYmxvZyBIVFRQLzEuMSIgMjAwIDI1NzEgIi0iICJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMF8xNF8wKSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvNzAuMC4zNTM4LjEwMiBTYWZhcmkvNTM3LjM2Ig==",
"mime_type": "text/plain"
}
},
"first_observed": "2019-04-21T11:05:07.000Z",
"last_observed": "2019-04-21T11:05:07.000Z",
"number_observed": 1
}
references
Mapping:
{
"sourceip": [
{
"key": "ipv4-addr.value",
"object": "src_ip"
},
{
"key": "network-traffic.src_ref",
"object": "nt",
"references": "src_ip"
}
],
"protocol": {
"key": "network-traffic.protocols",
"object": "nt"
}
}
Datasource Result:
"sourceip": "10.10.10.10",
"protocol": "TCP"
}
STIX Translation
Source ipv4-addr object number is referenced in network-traffic object:
{
"type": "bundle",
"id": "bundle--7c70d70e-e6a1-4e31-8f21-78efee48737a",
"objects": [
{
"type": "identity",
"id": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"name": "qradar",
"identity_class": "events",
"spec_version": "2.0",
"created": "2022-03-23T14:15:56.519Z",
"modified": "2022-03-23T14:15:56.519Z"
},
{
"id": "observed-data--f353936e-ec99-4975-b0c3-498b22bf10fb",
"type": "observed-data",
"created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created": "2023-07-21T13:37:32.811Z",
"modified": "2023-07-21T13:37:32.811Z",
"objects": {
"0": {
"type": "ipv4-addr",
"value": "10.10.10.10"
},
"1": {
"type": "network-traffic",
"src_ref": "0",
"protocols": [
"tcp"
]
}
},
"first_observed": "2023-07-21T13:37:32.811Z",
"last_observed": "2023-07-21T13:37:32.811Z",
"number_observed": 1
}
],
"spec_version": "2.0"
}
transformer
Mapping:
{
"sourceip": [
{
"key": "ipv4-addr.value",
"object": "src_ip"
},
{
"key": "network-traffic.src_ref",
"object": "nt",
"references": "src_ip"
}
],
"protocol": {
"key": "network-traffic.protocols",
"object": "nt"
},
"sourceport": {
"key": "network-traffic.src_port",
"object": "nt",
"transformer": "ToInteger"
}
}
Datasource Result:
{
"sourceip": "10.10.10.10",
"protocol": "TCP",
"sourceport": "3000"
}
STIX Translation
Port value is transformed from string to integer when ToInteger transformer is set in the mapping:
{
"type": "bundle",
"id": "bundle--0aee4703-bf5b-4830-9a4a-de29c8b526fd",
"objects": [
{
"type": "identity",
"id": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"name": "qradar",
"identity_class": "events",
"spec_version": "2.0",
"created": "2022-03-23T14:15:56.519Z",
"modified": "2022-03-23T14:15:56.519Z"
},
{
"id": "observed-data--9d80b67b-b2df-49a7-b16a-5f197b98d437",
"type": "observed-data",
"created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
"created": "2023-07-21T13:54:25.088Z",
"modified": "2023-07-21T13:54:25.088Z",
"objects": {
"0": {
"type": "ipv4-addr",
"value": "10.10.10.10"
},
"1": {
"type": "network-traffic",
"src_ref": "0",
"protocols": [
"tcp"
],
"src_port": 3000
}
},
"first_observed": "2023-07-21T13:54:25.088Z",
"last_observed": "2023-07-21T13:54:25.088Z",
"number_observed": 1
}
],
"spec_version": "2.0"
}