diff --git a/_security-analytics/threat-intelligence/api/findings.md b/_security-analytics/threat-intelligence/api/findings.md new file mode 100644 index 0000000000..3d1b3e8951 --- /dev/null +++ b/_security-analytics/threat-intelligence/api/findings.md @@ -0,0 +1,267 @@ +--- +layout: default +title: Alerts and Findings API +parent: Threat intelligence APIs +grand_parent: Threat intelligence +nav_order: 50 +--- + + +# Alerts and Findings API + +The threat intelligence Alerts and Findings API retrieves information about alerts and findings from threat intelligence feeds. + + +--- + +## Get threat intelligence alerts + +Retrieves any alerts related to threat intelligence monitors. + +### Path and HTTP methods + +```json +GET /_plugins/_security_analytics/threat_intel/alerts +``` +{% include copy-curl.html %} + + +### Path parameters + +You can specify the following parameters when requesting an alert. + +Parameter | Description +:--- | :---- +`severityLevel` | Filter alerts by severity level. Optional. +`alertState` | Used to filter by alert state. Possible values are `ACTIVE`, `ACKNOWLEDGED`, `COMPLETED`, `ERROR`, or `DELETED`. Optional. +`sortString` | The string Security Analytics uses to sort the alerts. Optional. +`sortOrder` | The order used to sort the list of alerts. Possible values are `asc` or `desc`. Optional. +`missing` | A list of fields for which no alias mappings were found. Optional. +`size` | An optional maximum number of results to be returned in the response. Optional. +`startIndex` | The pagination indicator. Optional. +`searchString` | The alert attribute you want returned in the search. Optional. + +### Example request + +```json +GET /_plugins/_security_analytics/threat_intel/alerts +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "alerts": [{ + "id": "906669ee-56e8-4f40-a12f-ab4c274d7521", + "version": 1, + "schema_version": 0, + "seq_no": 0, + "primary_term": 1, + "trigger_id": "regwarg", + "trigger_name": "regwarg", + "state": "ACTIVE", + "error_message": null, + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "severity": "high", + "finding_ids": [ + "a9c10094-6139-42b3-81a8-867dffbe381d" + ], + "acknowledged_time": 1722038395105, + "last_updated_time": null, + "start_time": 1722038395105, + "end_time": null + }], + "total_alerts": 1 +} +``` + +### Response fields + +A threat intelligence alert can have one of the following states. + +| State | Description | +| :---- | :--- | +| `ACTIVE` | The alert is ongoing and unacknowledged. Alerts remain in this state until they are acknowledged, the trigger associated with the alert is deleted, or the threat intelligence monitor is deleted entirely. | +| `ACKNOWLEDGED` | The alert is acknowledged, but the root cause of the alert has not been addressed. | +| `COMPLETED` | The alert is no longer ongoing. Alerts enter this state after the corresponding trigger evaluates to `false`. | +| `DELETED` | The monitor or trigger for the alert was deleted while the alert was active. | + +--- + +## Update Alerts Status API + +Updates the status of the specified alerts to `ACKNOWLEDGED` or `COMPLETED`. Only alerts in the `ACTIVE` state can be updated. + +### Path and HTTP methods + +```json +PUT /plugins/security_analytics/threat_intel/alerts/status +``` + +### Example requests + +The following example updates the status of the specified alerts to `ACKNOWLEDGED`: + +```json +PUT /plugins/security_analytics/threat_intel/alerts/status?state=ACKNOWLEDGED&alert_ids=, +``` + +The following example updates the status of the specified alerts to `COMPLETED`: + +```json +PUT /plugins/security_analytics/threat_intel/alerts/status?state=COMPLETED&alert_ids=alert_ids=, +``` + +### Example response + +```json +{ + "updated_alerts": [ + { + "id": "906669ee-56e8-4f40-a12f-ab4c274d7521", + "version": 1, + "schema_version": 0, + "seq_no": 2, + "primary_term": 1, + "trigger_id": "regwarg", + "trigger_name": "regwarg", + "state": "ACKNOWLEDGED", + "error_message": null, + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "severity": "high", + "finding_ids": [ + "a9c10094-6139-42b3-81a8-867dffbe381d" + ], + "acknowledged_time": 1722039091209, + "last_updated_time": 1722039091209, + "start_time": 1722038395105, + "end_time": null + }, + { + "id": "56e8-4f40-a12f-ab4c274d7521-906669ee", + "version": 1, + "schema_version": 0, + "seq_no": 2, + "primary_term": 1, + "trigger_id": "regwarg", + "trigger_name": "regwarg", + "state": "ACKNOWLEDGED", + "error_message": null, + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "severity": "high", + "finding_ids": [ + "a9c10094-6139-42b3-81a8-867dffbe381d" + ], + "acknowledged_time": 1722039091209, + "last_updated_time": 1722039091209, + "start_time": 1722038395105, + "end_time": null + } + ], + "failure_messages": [] +} +``` + + + +--- + +## Get findings + +Returns threat intelligence indicator of compromise (IOC) findings. When the threat intelligence monitor finds a malicious IOC during a data scan, a finding is automatically generated. + +### Path and HTTP methods + +```json +GET /_plugins/_security_analytics/threat_intel/findings/ +``` + +### Path parameters + +| Parameter | Description | +|:---------------|:--------------------------------------------------------------------------------------------| +| `sortString` | Specifies which string Security Analytics uses to sort the alerts. Optional. | +| `sortOrder` | The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional. | +| `missing` | A list of fields for which there were no alias mappings found. Optional. | +| `size` | The maximum number of results to be returned in the response. Optional. | +| `startIndex` | The pagination indicator. Optional. | +| `searchString` | The alert attribute you want returned in the search. Optional. | + +### Example request + +```json +GET /_plugins/_security_analytics/threat_intel/findings/_search?size=3 +``` + +```json +{ + "total_findings": 10, + "ioc_findings": [ + { + "id": "a9c10094-6139-42b3-81a8-867dffbe381d", + "related_doc_ids": [ + "Ccp88ZAB1vBjq44wmTEu:windows" + ], + "ioc_feed_ids": [ + { + "ioc_id": "2", + "feed_id": "Bsp88ZAB1vBjq44wiDGo", + "feed_name": "my_custom_feed", + "index": "" + } + ], + "monitor_id": "B8p88ZAB1vBjq44wkjEy", + "monitor_name": "Threat intelligence monitor", + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "timestamp": 1722038394501, + "execution_id": "01cae635-93dc-4f07-9e39-31076b9535d1" + }, + { + "id": "8d87aee0-aaa4-4c12-b4e2-b4b1f4ec80f9", + "related_doc_ids": [ + "GsqI8ZAB1vBjq44wXTHa:windows" + ], + "ioc_feed_ids": [ + { + "ioc_id": "2", + "feed_id": "Bsp88ZAB1vBjq44wiDGo", + "feed_name": "my_custom_feed", + "index": "" + } + ], + "monitor_id": "B8p88ZAB1vBjq44wkjEy", + "monitor_name": "Threat intelligence monitor", + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "timestamp": 1722039165824, + "execution_id": "54899e32-aeeb-401e-a031-b1728772f0aa" + }, + { + "id": "2419f624-ba1a-4873-978c-760183b449b7", + "related_doc_ids": [ + "H8qI8ZAB1vBjq44woDHU:windows" + ], + "ioc_feed_ids": [ + { + "ioc_id": "2", + "feed_id": "Bsp88ZAB1vBjq44wiDGo", + "feed_name": "my_custom_feed", + "index": "" + } + ], + "monitor_id": "B8p88ZAB1vBjq44wkjEy", + "monitor_name": "Threat intelligence monitor", + "ioc_value": "example-has00001", + "ioc_type": "hashes", + "timestamp": 1722039182616, + "execution_id": "32ad2544-4b8b-4c9b-b2b4-2ba6d31ece12" + } + ] +} + +``` diff --git a/_security-analytics/threat-intelligence/api/monitor.md b/_security-analytics/threat-intelligence/api/monitor.md new file mode 100644 index 0000000000..965fd79af3 --- /dev/null +++ b/_security-analytics/threat-intelligence/api/monitor.md @@ -0,0 +1,326 @@ +--- +layout: default +title: Monitor API +parent: Threat intelligence APIs +grand_parent: Threat intelligence +nav_order: 35 +--- + +# Monitor API + +You can use the threat intelligence Monitor API to create, search, and update [monitors](https://opensearch.org/docs/latest/observing-your-data/alerting/monitors/) for your threat intelligence feeds. + + +--- +## Create or update a threat intelligence monitor + +Creates or updates a threat intelligence monitor. + +### Path and HTTP methods + +The `POST` method creates a new monitor. The `PUT` method updates a monitor. + +```json +POST _plugins/_security_analytics/threat_intel/monitors +PUT _plugins/_security_analytics/threat_intel/monitors/ +``` + +### Request fields + +You can specify the following fields in the request body. + +| Field | Type | Description | +| :--- | :--- | :--- | +| `name` | String | The name of the monitor. Required. | +| `schedule` | Object | The schedule that determines how often the monitor runs. Required. | +| `schedule.period` | Object | Information about the frequency of the schedule. Required. | +| `schedule.period.interval` | Integer | The interval at which the monitor runs. Required. | +| `schedule.period.unit` | String | The unit of time for the interval. | +| `enabled` | Object | Information about the user who created the monitor. Required. | +| `user.backend_roles` | Array | The backend roles associated with the user. Optional. | +| `user.roles` | Array | The roles associated with the user. Optional. | +| `user.custom_attribute_names` | Array | Custom attribute names associated with the user. Optional. | +| `user.user_requested_tenant` | String | The tenant requested by the user. Optional. | +| `indices` | Array | The log data sources used for the monitor. Required. | +| `per_ioc_type_scan_input_list` | Array | A list of inputs to scan based on the indicator of compromise (IOC) types. Required. | +| `per_ioc_type_scan_input_list.ioc_type` | String | The type of IOC (for example, hashes). Required. | +| `per_ioc_type_scan_input_list.index_to_fields_map` | Object |The index field mappings that contain values for the given IOC type. Required. | +| `per_ioc_type_scan_input_list.index_to_fields_map.` | Array | A list of fields contained in the specified index. Required. | +| `triggers` | Array | The trigger settings for alerts. Required. | +| `triggers.data_sources` | Array | A list of data sources associated with the trigger. Required. | +| `triggers.name` | String | The name of the trigger. Required. | +| `triggers.severity` | String | The severity level of the trigger (for example, high, medium, or low). Required. | + +### Example requests + +The following section provides example requests for the Monitor API. + + +#### Create a monitor + +```json +{ + "name": "Threat intel monitor", + "schedule": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + }, + "enabled": false, + "user": { + "name": "", + "backend_roles": [], + "roles": [], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "indices": [ + "windows" + ], + "per_ioc_type_scan_input_list": [ + { + "ioc_type": "hashes", + "index_to_fields_map": { + "windows": [ + "file_hash" + ] + } + } + ], + "triggers": [ + { + "data_sources": [ + "windows", + "random" + ], + "name": "regwarg", + "severity": "high" + } + ] +} +``` + +### Update a monitor + +```json +{ + "name": "Threat intel monitor", + "schedule": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + }, + "enabled": false, + "user": { + "name": "", + "backend_roles": [], + "roles": [], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "indices": [ + "windows" + ], + "per_ioc_type_scan_input_list": [ + { + "ioc_type": "hashes", + "index_to_fields_map": { + "windows": [ + "file_hash" + ] + } + } + ], + "triggers": [ + { + "data_sources": [ + "windows", + "random" + ], + "name": "regwarg", + "severity": "high" + } + ] +} +``` + + +### Example response + +```json +{ + "id": "B8p88ZAB1vBjq44wkjEy", + "name": 1, + "seq_no": 0, + "primary_term": 1, + "monitor": { + "id": "B8p88ZAB1vBjq44wkjEy", + "name": "Threat intel monitor", + "per_ioc_type_scan_input_list": [ + { + "ioc_type": "hashes", + "index_to_fields_map": { + "windows": [ + "file_hash" + ] + } + } + ], + "schedule": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + }, + "enabled": false, + "user": { + "name": "", + "backend_roles": [], + "roles": [], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "indices": [ + "windows" + ], + "triggers": [ + { + "data_sources": [ + "windows", + "random" + ], + "ioc_types": [], + "actions": [], + "id": "afdd80cc-a669-4487-98a0-d84bea8e1e39", + "name": "regwarg", + "severity": "high" + } + ] + } +} +``` +--- + +## Delete a monitor + +Deletes an existing threat intelligence monitor. + +### Path and HTTP methods + +```json +DELETE /_plugins/_security_analytics/threat_intel/monitors/ +``` + +### Example request + +```json +DELETE /_plugins/_security_analytics/threat_intel/monitors/B8p88ZAB1vBjq44wkjEy +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "_id" : "B8p88ZAB1vBjq44wkjEy", + "_version" : 1 +} +``` + +## Search for a monitor + +Searches for an existing monitor using a query. The request body expects a search query. For query options, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). + +### Example request + +The following example request using a match query with the monitor's ID to search for the monitor: + +```json +POST /_plugins/_security_analytics/detectors/_search +{ + "query": { + "match": { + "_id": "HMqq_5AB1vBjq44wpTIN" + } + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "took": 11, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 2.0, + "hits": [ + { + "_index": ".opendistro-alerting-config", + "_id": "HMqq_5AB1vBjq44wpTIN", + "_version": 1, + "_seq_no": 8, + "_primary_term": 1, + "_score": 2.0, + "_source": { + "id": "HMqq_5AB1vBjq44wpTIN", + "name": "Threat intel monitor", + "per_ioc_type_scan_input_list": [ + { + "ioc_type": "hashes", + "index_to_fields_map": { + "windows": [ + "file_hash" + ] + } + } + ], + "schedule": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + }, + "enabled": false, + "user": { + "name": "", + "backend_roles": [], + "roles": [], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "indices": [ + "windows" + ], + "triggers": [ + { + "data_sources": [ + "windows", + "random" + ], + "ioc_types": [], + "actions": [], + "id": "63426758-c82d-4c87-a52c-f86ee6a8a06d", + "name": "regwarg", + "severity": "high" + } + ] + } + } + ] + } +} +``` \ No newline at end of file diff --git a/_security-analytics/threat-intelligence/api/source.md b/_security-analytics/threat-intelligence/api/source.md new file mode 100644 index 0000000000..7cfadfd813 --- /dev/null +++ b/_security-analytics/threat-intelligence/api/source.md @@ -0,0 +1,488 @@ +--- +layout: default +title: Source API +parent: Threat intelligence APIs +grand_parent: Threat intelligence +nav_order: 50 +--- + +# 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 + +```json +POST _plugins/_security_analytics/threat_intel/sources +PUT _plugins/_security_analytics/threat_intel/sources/ +``` + +### 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 the`IOC_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 + +```json +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 + } + ] + } + } +} +``` +{% include copy-curl.html %} + +#### S3_CUSTOM type source + +```json +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" + ] +} +``` +{% include copy-curl.html %} + +### Example responses + +The following example responses show what OpenSearch returns after a successful request. + + +#### IOC_UPLOAD type + +```json +{ + "_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 + +```json +{ + "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 + + +```json +GET /_plugins/_security_analytics/threat_intel/sources/ +``` + +### Example request + +```json +GET /_plugins/_security_analytics/threat_intel/sources/ +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "_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]({{site.url}}{{site.baseurl}}/query-dsl/). + + +### Path and HTTP methods + +```json +POST /_plugins/_security_analytics/threat_intel/sources/_search +``` + +### Example request + +```json +POST /_plugins/_security_analytics/threat_intel/sources/_search +{ + "query": { + "match": { + "source_config.type": "S3_CUSTOM" + } + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "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 + +```json +DELETE /_plugins/_security_analytics/threat_intel/sources/ +``` + +### Example request + +```json +DELETE /_plugins/_security_analytics/threat_intel/sources/2c0u7JAB9IJUg27gcjUp +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "_id": "2c0u7JAB9IJUg27gcjUp" +} +``` +--- + +## Refresh the source + +Downloads any IOCs from the threat intelligence source. Only supports the `S3_CUSTOM` type source. + +### Path and HTTP methods + +```json +POST /_plugins/_security_analytics/threat_intel/sources//_refresh +``` + +### Example request + +```json +POST /_plugins/_security_analytics/threat_intel/sources/IJAXz4QBrmVplM4JYxx_/_refresh +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "acknowledged": true +} +``` diff --git a/_security-analytics/threat-intelligence/api/threat-intel-api.md b/_security-analytics/threat-intelligence/api/threat-intel-api.md new file mode 100644 index 0000000000..c87133b700 --- /dev/null +++ b/_security-analytics/threat-intelligence/api/threat-intel-api.md @@ -0,0 +1,14 @@ +--- +layout: default +title: Threat intelligence APIs +nav_order: 50 +parent: Threat intelligence +has_children: true +has_toc: true +--- + +# Threat intelligence APIs + +OpenSearch provides several APIs that allow you to set up and interact with your threat intelligence feeds. + + diff --git a/_security-analytics/threat-intelligence/getting-started.md b/_security-analytics/threat-intelligence/getting-started.md new file mode 100644 index 0000000000..366bc2674c --- /dev/null +++ b/_security-analytics/threat-intelligence/getting-started.md @@ -0,0 +1,85 @@ +--- +layout: default +title: Getting started +parent: Threat intelligence +nav_order: 41 +--- + +# Getting started + +To get started with threat intelligence, you'll need to set up your threat intelligence sources and set up monitors to scan your log sources. The following tutorial shows you how to get started using OpenSearch Dashboards. Alternatively, you can use the [API](({{site.url}}{{site.baseurl}}/security-analytics/threat-intelligence/api/threat-intel-api/). + +## Threat intelligence view + +To access threat intelligence, log in to OpenSearch Dashboards and select **Security Analytics** > **Threat Intelligence**. + +In the threat intelligence view, you can access the following tabs: + +- **Threat intel sources**: Shows a list of all active and inactive threat intelligence sources, including the default IP reputation feed, [AlienVault OTX](https://otx.alienvault.com/), which comes prepackaged when downloading OpenSearch. +- **Scan configuration**: Shows an overview of your scan configuration, including the configured **Log sources**, **Scan schedule**, and **Alert triggers**. From the **Actions** dropdown list, you can also **Stop scan**, **Edit scan configuration**, or **Delete scan configuration**. + + +## Step 1: Set up threat intelligence sources + +To add a threat intelligence source, select **Add threat intel source** from the threat intelligence page. The **Add custom threat intelligence source** page appears. + +On the threat intelligence source page, add the following information: + +- **Name**: A name for the source. +- **Description**: An optional description of the source. +- **Threat intel source type**: The source type determines where the `STIX2` file is stored. You can choose one of the following options: + - **Remote data store location**: Connects to a custom data store. As of OpenSearch 2.16, only the `S3_SOURCE` type is supported. This setting also gives you the ability to set a download schedule, where OpenSearch downloads the newest `STIX2` file from the data store. For more information, see [S3_SOURCE connection details](#s3_source-connection-information). + - **Local file upload**: Uploads a custom threat intelligence IOC file. Custom files cannot be downloaded based on a schedule and must be uploaded manually in order to update the IOCs. For more information, see [Local file upload](#local-file-upload). +- **Types of malicious indicators**: Determines the types of malicious IOCs to pull from the `STIX2` file. The following IOCs are supported: + - IPv4-Address + - IPv6-Address + - Domains + - File hash + +After all the relevant information has been entered, select **Add threat intel source**. + +### Local file upload + +Local files uploaded as the threat intelligence source must use the following specifications: + +- Upload as a JSON file in the `STIX2` format. For an example `STIX2` file, download [this file]({{site.url}}{{site.baseurl}}/assets/examples/all-ioc-type-examples.json), which contains example formatting for all supported IOC types. +- Be less than 500 kB. + + +### S3_SOURCE connection information + +When using the `S3_SOURCE` as a remote store, the following connection information must be provided: + +- **IAM Role ARN**: The Amazon Resource Name (ARN) for an AWS Identity and Access Management (IAM) role. +- **S3 bucket directory**: The name of the Amazon Simple Storage Service (Amazon S3) bucket in which the `STIX2` file is stored. +- **Specify a directory or file**: The object key or directory path for the `STIX2` file in the S3 bucket. +- **Region**: The AWS Region for the S3 bucket. + +You can also set the **Download schedule**, which determines to where OpenSearch downloads an updated `STIX2` file from the connected S3 bucket. The default interval is once a day. Only daily intervals are supported. + +Alternatively, you can check the **Download on demand** option, which prevents new data from the bucket from being automatically downloaded. + + +## Step 2: Set up scanning for your log sources + +You can configure threat intelligence monitors to scan your aliases and data streams. The monitor scans for newly ingested data from your indexes and matches that data against any IOCs present in the threat intelligence sources. The scan applies to all threat intelligence sources added to OpenSearch. By default, the scan runs once each minute. + +To add or edit a scan configuration: + +1. From the threat intelligence view, select **Add scan configuration** or **Edit scan configuration**. +2. Select the indexes or aliases to scan. +3. Select the **fields** from your indexes or aliases to scan based on their IOC type. For example, if an alias has two fields called `src_ip` and `dst_ip` that contain `ipv4` addresses, then those fields must be entered into the `ipv4-addr` section of the monitor request. +4. Determine a **Scan schedule** for the indicated indexes or aliases. By default, OpenSearch scans for IOCs once each minute. +5. Set up any alert triggers and trigger conditions. You can add multiple triggers: + 1. Add a name for the trigger. + 2. Choose an indicator type. The indicator type matches the IOC type. + 3. Select a severity for the alert. + 4. Select whether to send a notification when the alert is triggered. When enabled, you can customize which channels the notification is sent to as well as the notification message. The notification message can be customized using a [Mustache template](https://mustache.github.io/mustache.5.html). +6. Once your settings have been entered, select **Save and start monitoring**. + +When malicious IOCs are found, OpenSearch creates **findings**, which provide information about the threat. You can also configure triggers to create alerts, which send notifications to configured webhooks or endpoints. + + +## Viewing alerts and findings + +You can view the alerts and findings generated by threat intelligence monitors to analyze which malicious indicators have occurred in their security logs. To view alerts or findings, select **View findings** or **View alerts** from the threat intelligence view. diff --git a/_security-analytics/threat-intelligence/index.md b/_security-analytics/threat-intelligence/index.md new file mode 100644 index 0000000000..b116d045c1 --- /dev/null +++ b/_security-analytics/threat-intelligence/index.md @@ -0,0 +1,16 @@ +--- +layout: default +title: Threat intelligence +nav_order: 40 +has_children: true +--- + +# Threat intelligence + +Threat intelligence in Security Analytics offers the capability to integrate your threat intelligence feeds. Feeds comprise indicators of compromise (IOCs), which search for malicious indicators in your data by setting up threat intelligence monitors. These monitors generate findings and can send notifications when malicious IPs, domains, or hashes from the threat intelligence feeds match your data. + + +You can interact with threat intelligence in the following ways: + +- Threat intelligence APsI: To configure threat intelligence using API operations, see [Threat Intelligence APIs]({{site.url}}{{site.baseurl}}/security-analytics/threat-intelligence/api/threat-intel-api/). +- OpenSearch Dashboards: To configure and use threat intelligence through the OpenSearch Dashboards interface, see [Getting started]({{site.url}}{{site.baseurl}}/security-analytics/threat-intelligence/getting-started/). \ No newline at end of file diff --git a/_security-analytics/usage/detectors.md b/_security-analytics/usage/detectors.md index bd7868bc37..1246812a22 100644 --- a/_security-analytics/usage/detectors.md +++ b/_security-analytics/usage/detectors.md @@ -37,7 +37,7 @@ After you select the **Alert triggers** tab, you also have the option to add add ### Threat intelligence feeds -A threat intelligence feed is a real-time, continuous data stream that gathers information related to risks or threats. A piece of information in the tactical threat intelligence feed suggesting that your cluster may have been compromised, such as a login from an unknown user or location or anomalous activity like an increase in read volume, is called an *indicator of compromise* (IoC). These IoCs can be used by investigators to help isolate security incidents. +A threat intelligence feed is a real-time, continuous data stream that gathers information related to risks or threats. A piece of information in the tactical threat intelligence feed suggesting that your cluster may have been compromised, such as a login from an unknown user or location or anomalous activity like an increase in read volume, is called an *indicator of compromise (IOC)*. These IOCs can be used by investigators to help isolate security incidents. As of OpenSearch 2.12, you can enable threat intelligence for Sigma rules related to malicious IP addresses. diff --git a/assets/examples/all-ioc-type-examples.json b/assets/examples/all-ioc-type-examples.json new file mode 100644 index 0000000000..46202f7933 --- /dev/null +++ b/assets/examples/all-ioc-type-examples.json @@ -0,0 +1,20 @@ +{"name":"test-domain-ioc-1","type":"domain-name","value":"example1.com","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-domain-ioc-2","type":"domain-name","value":"example2.com","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-domain-ioc-3","type":"domain-name","value":"example3.com","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-domain-ioc-4","type":"domain-name","value":"example4.com","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-domain-ioc-5","type":"domain-name","value":"example5.com","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-hash-ioc1","type":"hashes","value":"examplehash0000000000000000000000000000000000000000000000000001","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-hash-ioc2","type":"hashes","value":"examplehash0000000000000000000000000000000000000000000000000002","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-hash-ioc3","type":"hashes","value":"examplehash0000000000000000000000000000000000000000000000000003","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-hash-ioc4","type":"hashes","value":"examplehash0000000000000000000000000000000000000000000000000004","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-hash-ioc5","type":"hashes","value":"examplehash0000000000000000000000000000000000000000000000000005","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv4-ioc1","type":"ipv4-addr","value":"1.0.0.0","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv4-ioc2","type":"ipv4-addr","value":"2.0.0.0","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv4-ioc3","type":"ipv4-addr","value":"3.0.0.0","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv4-ioc4","type":"ipv4-addr","value":"4.0.0.0","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv4-ioc5","type":"ipv4-addr","value":"5.0.0.0","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv6-ioc1","type":"ipv6-addr","value":"1000:0000:0000:0000:0000:0000:0000:0000","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv6-ioc2","type":"ipv6-addr","value":"2000:0000:0000:0000:0000:0000:0000:0000","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv6-ioc3","type":"ipv6-addr","value":"3000:0000:0000:0000:0000:0000:0000:0000","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv6-ioc4","type":"ipv6-addr","value":"4000:0000:0000:0000:0000:0000:0000:0000","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"} +{"name":"test-ipv6-ioc5","type":"ipv6-addr","value":"5000:0000:0000:0000:0000:0000:0000:0000","severity":"3","created":"2024-06-24T23:38:59.817536Z","modified":"2024-06-25T00:38:59.81754Z","description":"test ioc description","labels":["label1"],"spec_version":"spec1"}