Link Search Menu Expand Document Documentation Menu
Documentation

You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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

POST _plugins/_security_analytics/threat_intel/sources
PUT _plugins/_security_analytics/threat_intel/sources/<source_id>

Request fields

Field Type Description
type String The type of threat intelligence source, such as S3_CUSTOM or IOC_UPLOAD.
name String The name of the threat intelligence source.
format String The format of the threat intelligence data, such as STIX2.
description String A description of the threat intelligence source.
enabled Boolean Indicates whether the scheduled refresh of IOCs from the source is enabled.
ioc_types Array of strings The STIX2 types of IOCs that the source supports, for example, hashes, domain-name, ipv4-addr, or ipv6-addr.
source Object The source information for the threat intelligence data.
source.ioc_upload Object Information about the IOC upload. Applicable to the IOC_UPLOAD type.
source.ioc_upload.file_name String The name of the file containing IOCs, such as test. Applicable to theIOC_UPLOAD type.
source.ioc_upload.iocs Array of objects A list of IOCs in STIX2 format. Applicable to the IOC_UPLOAD type.
source_config.source.s3 Object Information about the Amazon Simple Storage Service (Amazon S3) source. Applicable to the S3_CUSTOM type.
source_config.source.s3.bucket_name String The name of the S3 bucket, such as threat-intel-s3-test-bucket. Applicable to the S3_CUSTOM type.
source_config.source.s3.object_key String The key for the object in the S3 bucket, such alltypess3object. Applicable to the S3_CUSTOM type.
source_config.source.s3.region String The AWS Region in which the S3 bucket is located. Example: us-west-2. Applicable to the S3_CUSTOM type.
source_config.source.s3.role_arn String The 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.

Field Type Description
id String A unique identifier for the IOC, such as 1.
name String A human-readable name for the IOC, such as ioc-name.
type String The type of IOC, such as hashes.
value String The value of the IOC, which can be a hash value, such as gof.
severity String The severity level of the IOC. Example: thvvz.
created Integer/String The 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.
modified Integer/String The 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.
description String A description of the IOC.
labels Array of strings Any labels or tags associated with the IOC.
feed_id String A unique identifier for the feed to which the IOC belongs.
spec_version String The specification version used for the IOC.
version Integer A version number for the IOC.

Response fields

Field Data type Description
_id String The unique identifier for the threat intelligence source.
_version Integer The version number of the threat intelligence source.
source_config Object The configuration details of the threat intelligence source.
source_config.name String The name of the threat intelligence source.
source_config.format String The format of the threat intelligence data.
source_config.type String The type of the threat intelligence source.
source_config.ioc_types Array of strings The types of IOCs supported by the source.
source_config.description String A description of the threat intelligence source.
source_config.created_by_user String or null The user who created the threat intelligence source.
source_config.created_at String (DateTime) The date and time when the threat intelligence source was created.
source_config.source Object Contains information about the source of the threat intelligence data.
source_config.source.ioc_upload Object Information about the IOC upload.
source_config.source.ioc_upload.file_name String The name of the uploaded file. Example: test.
source_config.source.ioc_upload.iocs Array of objects Any additional information about the IOC upload. When the IOC is stored successfully, this appears as an empty array.
source_config.enabled Boolean Indicates whether the threat intelligence source is enabled.
source_config.enabled_time String or null The date and time when the source was enabled.
source_config.last_update_time String (DateTime) The date and time when the threat intelligence source was last updated.
source_config.schedule String or null The schedule for the threat intelligence source.
source_config.state String The current state of the threat intelligence source.
source_config.refresh_type String The type of refresh applied to the source.
source_config.last_refreshed_user String or null The user who last refreshed the source.
source_config.last_refreshed_time String (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

POST _plugins/_security_analytics/threat_intel/sources/
{
  "type": "IOC_UPLOAD",
  "name": "my_custom_feed",
  "format": "STIX2",
  "description": "this is the description",
  "store_type": "OS",
  "enabled": "false",
  "ioc_types": [
    "hashes"
  ],
  "source": {
    "ioc_upload": {
      "file_name": "test",
      "iocs": [
        {
          "id": "1",
          "name": "uldzafothwgik",
          "type": "hashes",
          "value": "gof",
          "severity": "thvvz",
          "created": 1719519073,
          "modified": 1719519073,
          "description": "first one here",
          "labels": [
            "ik"
          ],
          "feed_id": "jl",
          "spec_version": "gavvnespe",
          "version": -4356924786557562654
        },
        {
          "id": "2",
          "name": "uldzafothwgik",
          "type": "hashes",
          "value": "example-has00001",
          "severity": "thvvz",
          "created": "2024-06-20T01:06:20.562008Z",
          "modified": "2024-06-20T02:06:20.56201Z",
          "description": "first one here",
          "labels": [
            "ik"
          ],
          "feed_id": "jl",
          "spec_version": "gavvnespe",
          "version": -4356924786557562654
        }
      ]
    }
  }
}

S3_CUSTOM type source

POST _plugins/_security_analytics/threat_intel/sources/
{
 "type": "S3_CUSTOM",
 "name": "example-ipv4-from-SAP-account",
 "format": "STIX2",
 "store_type": "OS",
 "enabled": "true",
 "schedule": {
  "interval": {
   "start_time": 1717097122,
   "period": "10",
   "unit": "DAYS"
  }
 },
 "source": {
  "s3": {
   "bucket_name": "threat-intel-s3-test-bucket",
   "object_key": "alltypess3object",
   "region": "us-west-2",
   "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  }
 },
 "ioc_types": [
  "domain-name",
  "ipv4-addr"
 ]
}

Example responses

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

IOC_UPLOAD type

{
  "_id": "2c0u7JAB9IJUg27gcjUp",
  "_version": 2,
  "source_config": {
    "name": "my_custom_feed",
    "format": "STIX2",
    "type": "IOC_UPLOAD",
    "ioc_types": [
      "hashes"
    ],
    "description": "this is the description",
    "created_by_user": null,
    "created_at": "2024-07-25T23:16:25.257697Z",
    "source": {
      "ioc_upload": {
        "file_name": "test",
        "iocs": []
      }
    },
    "enabled": false,
    "enabled_time": null,
    "last_update_time": "2024-07-25T23:16:26.011774Z",
    "schedule": null,
    "state": "AVAILABLE",
    "refresh_type": "FULL",
    "last_refreshed_user": null,
    "last_refreshed_time": "2024-07-25T23:16:25.522735Z"
  }
}

S3_CUSTOM type source

{
 "id": "rGO5zJABLVyN2kq1wbFS",
 "version": 206,
 "name": "example-ipv4-from-SAP-account",
 "format": "STIX2",
 "type": "S3_CUSTOM",
 "ioc_types": [
  "domain-name",
  "ipv4-addr"
 ],
 "created_by_user": {
  "name": "admin",
  "backend_roles": [],
  "roles": [
   "security_manager",
   "all_access"
  ],
  "custom_attribute_names": []
 },
 "created_at": "2024-07-19T20:40:44.114Z",
 "source": {
  "s3": {
   "bucket_name": "threat-intel-s3-test-bucket",
   "object_key": "alltypess3object",
   "region": "us-west-2",
   "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  }
 },
 "enabled": true,
 "enabled_time": "2024-07-19T20:40:44.114Z",
 "last_update_time": "2024-07-25T20:58:18.213Z",
 "schedule": {
  "interval": {
   "start_time": 1717097122,
   "period": 10,
   "unit": "Days"
  }
 },
 "state": "AVAILBLE",
 "refresh_type": "FULL",
 "last_refreshed_user": {
  "name": "admin",
  "backend_roles": [],
  "roles": [
   "security_manager",
   "all_access"
  ],
  "custom_attribute_names": [],
  "user_requested_tenant": null
 },
 "last_refreshed_time": "2024-07-25T20:58:17.131Z"
}

Get threat intelligence source configuration details

Retrieves the threat intelligence source configuration details.

Path and HTTP methods

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

Example request

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

Example response

{
  "_id": "a-jnfjkAF_uQjn8Weo4",
  "_version": 2,
  "source_config": {
    "name": "my_custom_feed_2",
    "format": "STIX2",
    "type": "S3_CUSTOM",
    "ioc_types": [
      "ipv4_addr",
      "hashes"
    ],
    "description": "this is the description",
    "created_by_user": null,
    "created_at": "2024-06-27T00:52:56.373Z",
    "source": {
      "s3": {
        "bucket_name": "threat-intel-s3-test-bucket",
        "object_key": "bd",
        "region": "us-west-2",
        "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
      }
    },
    "enabled": true,
    "enabled_time": "2024-06-27T00:52:56.373Z",
    "last_update_time": "2024-06-27T00:52:57.824Z",
    "schedule": {
      "interval": {
        "start_time": 1717097122,
        "period": 1,
        "unit": "Days"
      }
    },
    "state": "AVAILABLE",
    "refresh_type": "FULL",
    "last_refreshed_user": null,
    "last_refreshed_time": "2024-06-27T00:52:56.533Z"
  }
}

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

POST /_plugins/_security_analytics/threat_intel/sources/_search

Example request

POST /_plugins/_security_analytics/threat_intel/sources/_search
{
    "query": {
        "match": {
            "source_config.type": "S3_CUSTOM"
        }
    }
}

Example response

{
    "took": 20,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 1,
            "relation": "eq"
        },
        "max_score": 1.0,
        "hits": [
            {
                "_index": ".opensearch-sap--job",
                "_id": "YEAuV5ABx0lQn6qhY5C1",
                "_version": 2,
                "_seq_no": 1,
                "_primary_term": 1,
                "_score": 1.0,
                "_source": {
                    "source_config": {
                        "name": "my_custom_feed_2",
                        "format": "STIX2",
                        "type": "S3_CUSTOM",
                        "description": "this is the description",
                        "created_by_user": null,
                        "source": {
                            "s3": {
                                "bucket_name": "threat-intelligence-s3-test-bucket",
                                "object_key": "bd",
                                "region": "us-west-2",
                                "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
                            }
                        },
                        "created_at": 1719449576373,
                        "enabled_time": 1719449576373,
                        "last_update_time": 1719449577824,
                        "schedule": {
                            "interval": {
                                "start_time": 1717097122,
                                "period": 1,
                                "unit": "Days"
                            }
                        },
                        "state": "AVAILABLE",
                        "refresh_type": "FULL",
                        "last_refreshed_time": 1719449576533,
                        "last_refreshed_user": null,
                        "enabled": true,
                        "ioc_types": [
                            "ip",
                            "hash"
                        ]
                    }
                }
            }
        ]
    }
}

Delete Threat Intelligence Source API

Deletes a threat intelligence source.

Path and HTTP methods

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

Example request

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

Example response

{
  "_id": "2c0u7JAB9IJUg27gcjUp"
}

Refresh the source

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

Path and HTTP methods

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

Example request

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

Example response

{
 "acknowledged": true
}
350 characters left

Have a question? .

Want to contribute? or .