Source API

The threat intelligence Source API updates and returns information about tasks related to threat intelligence source configurations.

Create or update a threat intelligence source

Creates or updates a threat intelligence source and loads indicators of compromise (IOCs) from that source.

Path and HTTP methods

  1. POST _plugins/_security_analytics/threat_intel/sources
  2. PUT _plugins/_security_analytics/threat_intel/sources/<source_id>

Request fields

FieldTypeDescription
typeStringThe type of threat intelligence source, such as S3_CUSTOM or IOC_UPLOAD.
nameStringThe name of the threat intelligence source.
formatStringThe format of the threat intelligence data, such as STIX2.
descriptionStringA description of the threat intelligence source.
enabledBooleanIndicates whether the scheduled refresh of IOCs from the source is enabled.
ioc_typesArray of stringsThe STIX2 types of IOCs that the source supports, for example, hashes, domain-name, ipv4-addr, or ipv6-addr.
sourceObjectThe source information for the threat intelligence data.
source.ioc_uploadObjectInformation about the IOC upload. Applicable to the IOC_UPLOAD type.
source.ioc_upload.file_nameStringThe name of the file containing IOCs, such as test. Applicable to theIOC_UPLOAD type.
source.ioc_upload.iocsArray of objectsA list of IOCs in STIX2 format. Applicable to the IOC_UPLOAD type.
source_config.source.s3ObjectInformation about the Amazon Simple Storage Service (Amazon S3) source. Applicable to the S3_CUSTOM type.
source_config.source.s3.bucket_nameStringThe name of the S3 bucket, such as threat-intel-s3-test-bucket. Applicable to the S3_CUSTOM type.
source_config.source.s3.object_keyStringThe key for the object in the S3 bucket, such alltypess3object. Applicable to the S3_CUSTOM type.
source_config.source.s3.regionStringThe AWS Region in which the S3 bucket is located. Example: us-west-2. Applicable to the S3_CUSTOM type.
source_config.source.s3.role_arnStringThe Amazon Resource Name (ARN) of the role used to access the S3 bucket, such as arn:aws:iam::248279774929:role/threat_intel_s3_test_role. Applicable to the S3_CUSTOM type.

IOC fields (STIX2)

The following fields modify the ioc_types option.

FieldTypeDescription
idStringA unique identifier for the IOC, such as 1.
nameStringA human-readable name for the IOC, such as ioc-name.
typeStringThe type of IOC, such as hashes.
valueStringThe value of the IOC, which can be a hash value, such as gof.
severityStringThe severity level of the IOC. Example: thvvz.
createdInteger/StringThe timestamp indicating when the IOC was created, either in UNIX epoch format or ISO_8601 format, for example, 1719519073 or 2024-06-20T01:06:20.562008Z.
modifiedInteger/StringThe timestamp indicating when the IOC was last modified, either in UNIX epoch format or ISO_8601 format, for example, 1719519073 or 2024-06-20T01:06:20.562008Z.
descriptionStringA description of the IOC.
labelsArray of stringsAny labels or tags associated with the IOC.
feed_idStringA unique identifier for the feed to which the IOC belongs.
spec_versionStringThe specification version used for the IOC.
versionIntegerA version number for the IOC.

Response fields

FieldData typeDescription
_idStringThe unique identifier for the threat intelligence source.
_versionIntegerThe version number of the threat intelligence source.
source_configObjectThe configuration details of the threat intelligence source.
source_config.nameStringThe name of the threat intelligence source.
source_config.formatStringThe format of the threat intelligence data.
source_config.typeStringThe type of the threat intelligence source.
source_config.ioc_typesArray of stringsThe types of IOCs supported by the source.
source_config.descriptionStringA description of the threat intelligence source.
source_config.created_by_userString or nullThe user who created the threat intelligence source.
source_config.created_atString (DateTime)The date and time when the threat intelligence source was created.
source_config.sourceObjectContains information about the source of the threat intelligence data.
source_config.source.ioc_uploadObjectInformation about the IOC upload.
source_config.source.ioc_upload.file_nameStringThe name of the uploaded file. Example: test.
source_config.source.ioc_upload.iocsArray of objectsAny additional information about the IOC upload. When the IOC is stored successfully, this appears as an empty array.
source_config.enabledBooleanIndicates whether the threat intelligence source is enabled.
source_config.enabled_timeString or nullThe date and time when the source was enabled.
source_config.last_update_timeString (DateTime)The date and time when the threat intelligence source was last updated.
source_config.scheduleString or nullThe schedule for the threat intelligence source.
source_config.stateStringThe current state of the threat intelligence source.
source_config.refresh_typeStringThe type of refresh applied to the source.
source_config.last_refreshed_userString or nullThe user who last refreshed the source.
source_config.last_refreshed_timeString (DateTime)The date and time when the source was last refreshed.

Example requests

The following example requests show you how to use the Source API.

IOC_UPLOAD type

  1. POST _plugins/_security_analytics/threat_intel/sources/
  2. {
  3.   "type": "IOC_UPLOAD",
  4.   "name": "my_custom_feed",
  5.   "format": "STIX2",
  6.   "description": "this is the description",
  7.   "store_type": "OS",
  8.   "enabled": "false",
  9.   "ioc_types": [
  10.     "hashes"
  11.   ],
  12.   "source": {
  13.     "ioc_upload": {
  14.       "file_name": "test",
  15.       "iocs": [
  16.         {
  17.           "id": "1",
  18.           "name": "uldzafothwgik",
  19.           "type": "hashes",
  20.           "value": "gof",
  21.           "severity": "thvvz",
  22.           "created": 1719519073,
  23.           "modified": 1719519073,
  24.           "description": "first one here",
  25.           "labels": [
  26.             "ik"
  27.           ],
  28.           "feed_id": "jl",
  29.           "spec_version": "gavvnespe",
  30.           "version": -4356924786557562654
  31.         },
  32.         {
  33.           "id": "2",
  34.           "name": "uldzafothwgik",
  35.           "type": "hashes",
  36.           "value": "example-has00001",
  37.           "severity": "thvvz",
  38.           "created": "2024-06-20T01:06:20.562008Z",
  39.           "modified": "2024-06-20T02:06:20.56201Z",
  40.           "description": "first one here",
  41.           "labels": [
  42.             "ik"
  43.           ],
  44.           "feed_id": "jl",
  45.           "spec_version": "gavvnespe",
  46.           "version": -4356924786557562654
  47.         }
  48.       ]
  49.     }
  50.   }
  51. }

copy

S3_CUSTOM type source

  1. POST _plugins/_security_analytics/threat_intel/sources/
  2. {
  3.  "type": "S3_CUSTOM",
  4.  "name": "example-ipv4-from-SAP-account",
  5.  "format": "STIX2",
  6.  "store_type": "OS",
  7.  "enabled": "true",
  8.  "schedule": {
  9.   "interval": {
  10.    "start_time": 1717097122,
  11.    "period": "10",
  12.    "unit": "DAYS"
  13.   }
  14.  },
  15.  "source": {
  16.   "s3": {
  17.    "bucket_name": "threat-intel-s3-test-bucket",
  18.    "object_key": "alltypess3object",
  19.    "region": "us-west-2",
  20.    "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  21.   }
  22.  },
  23.  "ioc_types": [
  24.   "domain-name",
  25.   "ipv4-addr"
  26.  ]
  27. }

copy

Example responses

The following example responses show what OpenSearch returns after a successful request.

IOC_UPLOAD type

  1. {
  2.   "_id": "2c0u7JAB9IJUg27gcjUp",
  3.   "_version": 2,
  4.   "source_config": {
  5.     "name": "my_custom_feed",
  6.     "format": "STIX2",
  7.     "type": "IOC_UPLOAD",
  8.     "ioc_types": [
  9.       "hashes"
  10.     ],
  11.     "description": "this is the description",
  12.     "created_by_user": null,
  13.     "created_at": "2024-07-25T23:16:25.257697Z",
  14.     "source": {
  15.       "ioc_upload": {
  16.         "file_name": "test",
  17.         "iocs": []
  18.       }
  19.     },
  20.     "enabled": false,
  21.     "enabled_time": null,
  22.     "last_update_time": "2024-07-25T23:16:26.011774Z",
  23.     "schedule": null,
  24.     "state": "AVAILABLE",
  25.     "refresh_type": "FULL",
  26.     "last_refreshed_user": null,
  27.     "last_refreshed_time": "2024-07-25T23:16:25.522735Z"
  28.   }
  29. }

S3_CUSTOM type source

  1. {
  2.  "id": "rGO5zJABLVyN2kq1wbFS",
  3.  "version": 206,
  4.  "name": "example-ipv4-from-SAP-account",
  5.  "format": "STIX2",
  6.  "type": "S3_CUSTOM",
  7.  "ioc_types": [
  8.   "domain-name",
  9.   "ipv4-addr"
  10.  ],
  11.  "created_by_user": {
  12.   "name": "admin",
  13.   "backend_roles": [],
  14.   "roles": [
  15.    "security_manager",
  16.    "all_access"
  17.   ],
  18.   "custom_attribute_names": []
  19.  },
  20.  "created_at": "2024-07-19T20:40:44.114Z",
  21.  "source": {
  22.   "s3": {
  23.    "bucket_name": "threat-intel-s3-test-bucket",
  24.    "object_key": "alltypess3object",
  25.    "region": "us-west-2",
  26.    "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  27.   }
  28.  },
  29.  "enabled": true,
  30.  "enabled_time": "2024-07-19T20:40:44.114Z",
  31.  "last_update_time": "2024-07-25T20:58:18.213Z",
  32.  "schedule": {
  33.   "interval": {
  34.    "start_time": 1717097122,
  35.    "period": 10,
  36.    "unit": "Days"
  37.   }
  38.  },
  39.  "state": "AVAILBLE",
  40.  "refresh_type": "FULL",
  41.  "last_refreshed_user": {
  42.   "name": "admin",
  43.   "backend_roles": [],
  44.   "roles": [
  45.    "security_manager",
  46.    "all_access"
  47.   ],
  48.   "custom_attribute_names": [],
  49.   "user_requested_tenant": null
  50.  },
  51.  "last_refreshed_time": "2024-07-25T20:58:17.131Z"
  52. }

Get threat intelligence source configuration details

Retrieves the threat intelligence source configuration details.

Path and HTTP methods

  1. GET /_plugins/_security_analytics/threat_intel/sources/<source-id>

Example request

  1. GET /_plugins/_security_analytics/threat_intel/sources/<source-id>

copy

Example response

  1. {
  2.   "_id": "a-jnfjkAF_uQjn8Weo4",
  3.   "_version": 2,
  4.   "source_config": {
  5.     "name": "my_custom_feed_2",
  6.     "format": "STIX2",
  7.     "type": "S3_CUSTOM",
  8.     "ioc_types": [
  9.       "ipv4_addr",
  10.       "hashes"
  11.     ],
  12.     "description": "this is the description",
  13.     "created_by_user": null,
  14.     "created_at": "2024-06-27T00:52:56.373Z",
  15.     "source": {
  16.       "s3": {
  17.         "bucket_name": "threat-intel-s3-test-bucket",
  18.         "object_key": "bd",
  19.         "region": "us-west-2",
  20.         "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
  21.       }
  22.     },
  23.     "enabled": true,
  24.     "enabled_time": "2024-06-27T00:52:56.373Z",
  25.     "last_update_time": "2024-06-27T00:52:57.824Z",
  26.     "schedule": {
  27.       "interval": {
  28.         "start_time": 1717097122,
  29.         "period": 1,
  30.         "unit": "Days"
  31.       }
  32.     },
  33.     "state": "AVAILABLE",
  34.     "refresh_type": "FULL",
  35.     "last_refreshed_user": null,
  36.     "last_refreshed_time": "2024-06-27T00:52:56.533Z"
  37.   }
  38. }

Search for a threat intelligence source

Searches for threat intelligence source matches based on the search query. The request body expects a search query. For query options, see Query DSL.

Path and HTTP methods

  1. POST /_plugins/_security_analytics/threat_intel/sources/_search

Example request

  1. POST /_plugins/_security_analytics/threat_intel/sources/_search
  2. {
  3.     "query": {
  4.         "match": {
  5.             "source_config.type": "S3_CUSTOM"
  6.         }
  7.     }
  8. }

copy

Example response

  1. {
  2.     "took": 20,
  3.     "timed_out": false,
  4.     "_shards": {
  5.         "total": 1,
  6.         "successful": 1,
  7.         "skipped": 0,
  8.         "failed": 0
  9.     },
  10.     "hits": {
  11.         "total": {
  12.             "value": 1,
  13.             "relation": "eq"
  14.         },
  15.         "max_score": 1.0,
  16.         "hits": [
  17.             {
  18.                 "_index": ".opensearch-sap--job",
  19.                 "_id": "YEAuV5ABx0lQn6qhY5C1",
  20.                 "_version": 2,
  21.                 "_seq_no": 1,
  22.                 "_primary_term": 1,
  23.                 "_score": 1.0,
  24.                 "_source": {
  25.                     "source_config": {
  26.                         "name": "my_custom_feed_2",
  27.                         "format": "STIX2",
  28.                         "type": "S3_CUSTOM",
  29.                         "description": "this is the description",
  30.                         "created_by_user": null,
  31.                         "source": {
  32.                             "s3": {
  33.                                 "bucket_name": "threat-intelligence-s3-test-bucket",
  34.                                 "object_key": "bd",
  35.                                 "region": "us-west-2",
  36.                                 "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
  37.                             }
  38.                         },
  39.                         "created_at": 1719449576373,
  40.                         "enabled_time": 1719449576373,
  41.                         "last_update_time": 1719449577824,
  42.                         "schedule": {
  43.                             "interval": {
  44.                                 "start_time": 1717097122,
  45.                                 "period": 1,
  46.                                 "unit": "Days"
  47.                             }
  48.                         },
  49.                         "state": "AVAILABLE",
  50.                         "refresh_type": "FULL",
  51.                         "last_refreshed_time": 1719449576533,
  52.                         "last_refreshed_user": null,
  53.                         "enabled": true,
  54.                         "ioc_types": [
  55.                             "ip",
  56.                             "hash"
  57.                         ]
  58.                     }
  59.                 }
  60.             }
  61.         ]
  62.     }
  63. }

Delete Threat Intelligence Source API

Deletes a threat intelligence source.

Path and HTTP methods

  1. DELETE /_plugins/_security_analytics/threat_intel/sources/<source-id>

Example request

  1. DELETE /_plugins/_security_analytics/threat_intel/sources/2c0u7JAB9IJUg27gcjUp

copy

Example response

  1. {
  2.   "_id": "2c0u7JAB9IJUg27gcjUp"
  3. }

Refresh the source

Downloads any IOCs from the threat intelligence source. Only supports the S3_CUSTOM type source.

Path and HTTP methods

  1. POST /_plugins/_security_analytics/threat_intel/sources/<source-id>/_refresh

Example request

  1. POST /_plugins/_security_analytics/threat_intel/sources/IJAXz4QBrmVplM4JYxx_/_refresh

copy

Example response

  1. {
  2.  "acknowledged": true
  3. }