You're viewing version 3.8 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.
Rule APIs
The following APIs can be used for a number of tasks related to rules, from searching for pre-packaged rules to creating and updating custom rules.
Create custom rule
Creates a custom rule using Sigma security rule formatting. For information about how to write a rule in Sigma format, see information provided at Sigma’s GitHub repository.
POST /_plugins/_security_analytics/rules?category=windows
Example request
Header:
Content-Type: application/json
Body:
title: Moriya Rootkit
id: 25b9c01c-350d-4b95-bed1-836d04a4f324
description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
status: experimental
author: Bhabesh Raj
date: 2021/05/06
modified: 2021/11/30
references:
- https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
tags:
- attack.persistence
- attack.privilege_escalation
- attack.t1543.003
logsource:
product: windows
service: system
detection:
selection:
Provider_Name: 'Service Control Manager'
EventID: 7045
ServiceName: ZzNetSvc
condition: selection
level: critical
falsepositives:
- Unknown
Example response
Sample 1:
{
"_id": "M1Rm1IMByX0LvTiGvde2",
"_version": 1,
"rule": {
"category": "windows",
"title": "Moriya Rootkit",
"log_source": "",
"description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
"tags": [
{
"value": "attack.persistence"
},
{
"value": "attack.privilege_escalation"
},
{
"value": "attack.t1543.003"
}
],
"references": [
{
"value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
}
],
"level": "critical",
"false_positives": [
{
"value": "Unknown"
}
],
"author": "Bhabesh Raj",
"status": "experimental",
"last_update_time": "2021-05-06T00:00:00.000Z",
"rule": "title: Moriya Rootkit\nid: 25b9c01c-350d-4b95-bed1-836d04a4f324\ndescription: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report\nstatus: experimental\nauthor: Bhabesh Raj\ndate: 2021/05/06\nmodified: 2021/11/30\nreferences:\n - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831\ntags:\n - attack.persistence\n - attack.privilege_escalation\n - attack.t1543.003\nlogsource:\n product: windows\n service: system\ndetection:\n selection:\n Provider_Name: 'Service Control Manager'\n EventID: 7045\n ServiceName: ZzNetSvc\n condition: selection\nlevel: critical\nfalsepositives:\n - Unknown"
}
}
Sample 2:
{
"error": {
"root_cause": [
{
"type": "security_analytics_exception",
"reason": "{\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}"
}
],
"type": "security_analytics_exception",
"reason": "{\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}",
"caused_by": {
"type": "exception",
"reason": "{\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}"
}
},
"status": 400
}
Update custom rule (not forced)
Updates a custom rule. If the rule is actively used by detectors, the update is rejected unless the forced flag is set to true.
Example request
PUT /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?category=windows
Content-Type: application/json
Body:
title: Moriya Rooskit
id: 25b9c01c-350d-4b95-bed1-836d04a4f324
description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
status: experimental
author: Bhabesh Raj
date: 2021/05/06
modified: 2021/11/30
references:
- https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
tags:
- attack.persistence
- attack.privilege_escalation
- attack.t1543.003
logsource:
product: windows
service: system
detection:
selection:
Provider_Name: 'Service Control Manager'
EventID: 7045
ServiceName: ZzNetSvc
condition: selection
level: critical
falsepositives:
- Unknown
Example response
{
"error": {
"root_cause": [
{
"type": "security_analytics_exception",
"reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true"
}
],
"type": "security_analytics_exception",
"reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true",
"caused_by": {
"type": "exception",
"reason": "org.opensearch.OpenSearchStatusException: Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true"
}
},
"status": 500
}
Update custom rule (forced)
Forces an update to a custom rule, even if it is actively used by detectors.
Example request
PUT /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?category=windows&forced=true
Content-Type: application/json
Body:
title: Moriya Rooskit
id: 25b9c01c-350d-4b95-bed1-836d04a4f324
description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
status: experimental
author: Bhabesh Raj
date: 2021/05/06
modified: 2021/11/30
references:
- https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
tags:
- attack.persistence
- attack.privilege_escalation
- attack.t1543.003
logsource:
product: windows
service: system
detection:
selection:
Provider_Name: 'Service Control Manager'
EventID: 7045
ServiceName: ZzNetSvc
condition: selection
level: critical
falsepositives:
- Unknown
Example response
{
"_id": "ZaFv1IMBdLpXWBiBa1XI",
"_version": 1,
"rule": {
"category": "windows",
"title": "Moriya Rooskit",
"log_source": "",
"description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
"tags": [
{
"value": "attack.persistence"
},
{
"value": "attack.privilege_escalation"
},
{
"value": "attack.t1543.003"
}
],
"references": [
{
"value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
}
],
"level": "critical",
"false_positives": [
{
"value": "Unknown"
}
],
"author": "Bhabesh Raj",
"status": "experimental",
"last_update_time": "2021-05-06T00:00:00.000Z",
"rule": "title: Moriya Rooskit\nid: 25b9c01c-350d-4b95-bed1-836d04a4f324\ndescription: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report\nstatus: experimental\nauthor: Bhabesh Raj\ndate: 2021/05/06\nmodified: 2021/11/30\nreferences:\n - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831\ntags:\n - attack.persistence\n - attack.privilege_escalation\n - attack.t1543.003\nlogsource:\n product: windows\n service: system\ndetection:\n selection:\n Provider_Name: 'Service Control Manager'\n EventID: 7045\n ServiceName: ZzNetSvc\n condition: selection\nlevel: critical\nfalsepositives:\n - Unknown"
}
}
Search pre-packaged rules
Searches for pre-packaged rules by category or other criteria.
Example request
POST /_plugins/_security_analytics/rules/_search?pre_packaged=true
{
"from": 0,
"size": 20,
"query": {
"nested": {
"path": "rule",
"query": {
"bool": {
"must": [
{ "match": { "rule.category": "windows" } }
]
}
}
}
}
}
Example response
{
"took": 3,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1580,
"relation": "eq"
},
"max_score": 0.25863406,
"hits": [
{
"_index": ".opensearch-pre-packaged-rules-config",
"_id": "6KFv1IMBdLpXWBiBelZg",
"_version": 1,
"_seq_no": 386,
"_primary_term": 1,
"_score": 0.25863406,
"_source": {
"category": "windows",
"title": "Change Outlook Security Setting in Registry",
"log_source": "registry_set",
"description": "Change outlook email security settings",
"references": [
{
"value": "https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/T1137/T1137.md"
},
{
"value": "https://docs.microsoft.com/en-us/outlook/troubleshoot/security/information-about-email-security-settings"
}
],
"tags": [
{
"value": "attack.persistence"
},
{
"value": "attack.t1137"
}
],
"level": "medium",
"false_positives": [
{
"value": "Administrative scripts"
}
],
"author": "frack113",
"status": "experimental",
"last_update_time": "2021-12-28T00:00:00.000Z",
"queries": [
{
"value": "((TargetObject: *\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\*) AND (TargetObject: *\\\\Outlook\\\\Security\\\\*)) AND (EventType: \"SetValue\")"
}
],
"rule": "title: Change Outlook Security Setting in Registry\nid: c3cefdf4-6703-4e1c-bad8-bf422fc5015a\ndescription: Change outlook email security settings\nauthor: frack113\ndate: 2021/12/28\nmodified: 2022/03/26\nstatus: experimental\nreferences:\n - https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/T1137/T1137.md\n - https://docs.microsoft.com/en-us/outlook/troubleshoot/security/information-about-email-security-settings\nlogsource:\n category: registry_set\n product: windows\ndetection:\n selection:\n TargetObject|contains|all:\n - '\\SOFTWARE\\Microsoft\\Office\\'\n - '\\Outlook\\Security\\'\n EventType: SetValue\n condition: selection\nfalsepositives:\n - Administrative scripts\nlevel: medium\ntags:\n - attack.persistence\n - attack.t1137\n"
}
}
]
}
}
Search custom rules
Searches for custom rules by category or other criteria.
Example request
POST /_plugins/_security_analytics/rules/_search?pre_packaged=false
Body:
{
"from": 0,
"size": 20,
"query": {
"nested": {
"path": "rule",
"query": {
"bool": {
"must": [
{ "match": { "rule.category": "windows" } }
]
}
}
}
}
}
Example response
{
"took": 1,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 0.2876821,
"hits": [
{
"_index": ".opensearch-custom-rules-config",
"_id": "ZaFv1IMBdLpXWBiBa1XI",
"_version": 2,
"_seq_no": 1,
"_primary_term": 1,
"_score": 0.2876821,
"_source": {
"category": "windows",
"title": "Moriya Rooskit",
"log_source": "",
"description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
"references": [
{
"value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
}
],
"tags": [
{
"value": "attack.persistence"
},
{
"value": "attack.privilege_escalation"
},
{
"value": "attack.t1543.003"
}
],
"level": "critical",
"false_positives": [
{
"value": "Unknown"
}
],
"author": "Bhabesh Raj",
"status": "experimental",
"last_update_time": "2021-05-06T00:00:00.000Z",
"queries": [
{
"value": "(Provider_Name: \"Service_ws_Control_ws_Manager\") AND (event_uid: 7045) AND (ServiceName: \"ZzNetSvc\")"
}
],
"rule": "title: Moriya Rooskit\nid: 25b9c01c-350d-4b95-bed1-836d04a4f324\ndescription: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report\nstatus: experimental\nauthor: Bhabesh Raj\ndate: 2021/05/06\nmodified: 2021/11/30\nreferences:\n - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831\ntags:\n - attack.persistence\n - attack.privilege_escalation\n - attack.t1543.003\nlogsource:\n product: windows\n service: system\ndetection:\n selection:\n Provider_Name: 'Service Control Manager'\n EventID: 7045\n ServiceName: ZzNetSvc\n condition: selection\nlevel: critical\nfalsepositives:\n - Unknown"
}
}
]
}
}
Delete custom rule (not forced)
Deletes a custom rule. If the rule is actively used by detectors, the deletion is rejected unless the forced flag is set to true.
Example request
DELETE /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI
Example response
{
"error": {
"root_cause": [
{
"type": "security_analytics_exception",
"reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true"
}
],
"type": "security_analytics_exception",
"reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true",
"caused_by": {
"type": "exception",
"reason": "org.opensearch.OpenSearchStatusException: Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true"
}
},
"status": 500
}
Delete custom rule (forced)
Forces deletion of a custom rule, even if it is actively used by detectors.
Example request
DELETE /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?forced=true
Example response
{
"_id": "ZaFv1IMBdLpXWBiBa1XI",
"_version": 1
}