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

The Create custom rule API uses Sigma security rule formatting to create a custom rule. For information on how to write a rule in Sigma format, see information provided at Sigma’s GitHub repository.

  1. POST /_plugins/_security_analytics/rules?category=windows

Sample request

  1. Header:
  2. Content-Type: application/json
  3. Body:
  4. title: Moriya Rootkit
  5. id: 25b9c01c-350d-4b95-bed1-836d04a4f324
  6. description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
  7. status: experimental
  8. author: Bhabesh Raj
  9. date: 2021/05/06
  10. modified: 2021/11/30
  11. references:
  12. - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
  13. tags:
  14. - attack.persistence
  15. - attack.privilege_escalation
  16. - attack.t1543.003
  17. logsource:
  18. product: windows
  19. service: system
  20. detection:
  21. selection:
  22. Provider_Name: 'Service Control Manager'
  23. EventID: 7045
  24. ServiceName: ZzNetSvc
  25. condition: selection
  26. level: critical
  27. falsepositives:
  28. - Unknown

Sample response

Sample 1:

  1. {
  2. "_id": "M1Rm1IMByX0LvTiGvde2",
  3. "_version": 1,
  4. "rule": {
  5. "category": "windows",
  6. "title": "Moriya Rootkit",
  7. "log_source": "",
  8. "description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
  9. "tags": [
  10. {
  11. "value": "attack.persistence"
  12. },
  13. {
  14. "value": "attack.privilege_escalation"
  15. },
  16. {
  17. "value": "attack.t1543.003"
  18. }
  19. ],
  20. "references": [
  21. {
  22. "value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
  23. }
  24. ],
  25. "level": "critical",
  26. "false_positives": [
  27. {
  28. "value": "Unknown"
  29. }
  30. ],
  31. "author": "Bhabesh Raj",
  32. "status": "experimental",
  33. "last_update_time": "2021-05-06T00:00:00.000Z",
  34. "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"
  35. }
  36. }

Sample 2:

  1. {
  2. "error": {
  3. "root_cause": [
  4. {
  5. "type": "security_analytics_exception",
  6. "reason": "{\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}"
  7. }
  8. ],
  9. "type": "security_analytics_exception",
  10. "reason": "{\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}",
  11. "caused_by": {
  12. "type": "exception",
  13. "reason": "java.util.Arrays$ArrayList: {\"error\":\"Sigma rule must have a log source\",\"error\":\"Sigma rule must have a detection definitions\"}"
  14. }
  15. },
  16. "status": 400
  17. }

Update Custom Rule (not forced)

Sample request

  1. PUT /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?category=windows
  2. Content-Type: application/json
  3. Body:
  4. title: Moriya Rooskit
  5. id: 25b9c01c-350d-4b95-bed1-836d04a4f324
  6. description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
  7. status: experimental
  8. author: Bhabesh Raj
  9. date: 2021/05/06
  10. modified: 2021/11/30
  11. references:
  12. - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
  13. tags:
  14. - attack.persistence
  15. - attack.privilege_escalation
  16. - attack.t1543.003
  17. logsource:
  18. product: windows
  19. service: system
  20. detection:
  21. selection:
  22. Provider_Name: 'Service Control Manager'
  23. EventID: 7045
  24. ServiceName: ZzNetSvc
  25. condition: selection
  26. level: critical
  27. falsepositives:
  28. - Unknown

Sample response

  1. {
  2. "error": {
  3. "root_cause": [
  4. {
  5. "type": "security_analytics_exception",
  6. "reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true"
  7. }
  8. ],
  9. "type": "security_analytics_exception",
  10. "reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true",
  11. "caused_by": {
  12. "type": "exception",
  13. "reason": "org.opensearch.OpenSearchStatusException: Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Update can be forced by setting forced flag to true"
  14. }
  15. },
  16. "status": 500
  17. }

Update Custom Rule (forced)

Sample request

  1. PUT /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?category=windows&forced=true
  2. Content-Type: application/json
  3. Body:
  4. title: Moriya Rooskit
  5. id: 25b9c01c-350d-4b95-bed1-836d04a4f324
  6. description: Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report
  7. status: experimental
  8. author: Bhabesh Raj
  9. date: 2021/05/06
  10. modified: 2021/11/30
  11. references:
  12. - https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831
  13. tags:
  14. - attack.persistence
  15. - attack.privilege_escalation
  16. - attack.t1543.003
  17. logsource:
  18. product: windows
  19. service: system
  20. detection:
  21. selection:
  22. Provider_Name: 'Service Control Manager'
  23. EventID: 7045
  24. ServiceName: ZzNetSvc
  25. condition: selection
  26. level: critical
  27. falsepositives:
  28. - Unknown

Sample response

  1. {
  2. "_id": "ZaFv1IMBdLpXWBiBa1XI",
  3. "_version": 1,
  4. "rule": {
  5. "category": "windows",
  6. "title": "Moriya Rooskit",
  7. "log_source": "",
  8. "description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
  9. "tags": [
  10. {
  11. "value": "attack.persistence"
  12. },
  13. {
  14. "value": "attack.privilege_escalation"
  15. },
  16. {
  17. "value": "attack.t1543.003"
  18. }
  19. ],
  20. "references": [
  21. {
  22. "value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
  23. }
  24. ],
  25. "level": "critical",
  26. "false_positives": [
  27. {
  28. "value": "Unknown"
  29. }
  30. ],
  31. "author": "Bhabesh Raj",
  32. "status": "experimental",
  33. "last_update_time": "2021-05-06T00:00:00.000Z",
  34. "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"
  35. }
  36. }

Search Pre-Packaged Rules

Sample request

  1. POST /_plugins/_security_analytics/rules/_search?pre_packaged=true
  2. {
  3. "from": 0,
  4. "size": 20,
  5. "query": {
  6. "nested": {
  7. "path": "rule",
  8. "query": {
  9. "bool": {
  10. "must": [
  11. { "match": { "rule.category": "windows" } }
  12. ]
  13. }
  14. }
  15. }
  16. }
  17. }

Sample response

  1. {
  2. "took": 3,
  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": 1580,
  13. "relation": "eq"
  14. },
  15. "max_score": 0.25863406,
  16. "hits": [
  17. {
  18. "_index": ".opensearch-pre-packaged-rules-config",
  19. "_id": "6KFv1IMBdLpXWBiBelZg",
  20. "_version": 1,
  21. "_seq_no": 386,
  22. "_primary_term": 1,
  23. "_score": 0.25863406,
  24. "_source": {
  25. "category": "windows",
  26. "title": "Change Outlook Security Setting in Registry",
  27. "log_source": "registry_set",
  28. "description": "Change outlook email security settings",
  29. "references": [
  30. {
  31. "value": "https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/T1137/T1137.md"
  32. },
  33. {
  34. "value": "https://docs.microsoft.com/en-us/outlook/troubleshoot/security/information-about-email-security-settings"
  35. }
  36. ],
  37. "tags": [
  38. {
  39. "value": "attack.persistence"
  40. },
  41. {
  42. "value": "attack.t1137"
  43. }
  44. ],
  45. "level": "medium",
  46. "false_positives": [
  47. {
  48. "value": "Administrative scripts"
  49. }
  50. ],
  51. "author": "frack113",
  52. "status": "experimental",
  53. "last_update_time": "2021-12-28T00:00:00.000Z",
  54. "queries": [
  55. {
  56. "value": "((TargetObject: *\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\*) AND (TargetObject: *\\\\Outlook\\\\Security\\\\*)) AND (EventType: \"SetValue\")"
  57. }
  58. ],
  59. "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"
  60. }
  61. }
  62. ]
  63. }
  64. }

Search Custom Rules

Sample request

  1. POST /_plugins/_security_analytics/rules/_search?pre_packaged=false
  2. Body:
  3. {
  4. "from": 0,
  5. "size": 20,
  6. "query": {
  7. "nested": {
  8. "path": "rule",
  9. "query": {
  10. "bool": {
  11. "must": [
  12. { "match": { "rule.category": "windows" } }
  13. ]
  14. }
  15. }
  16. }
  17. }
  18. }

Sample response

  1. {
  2. "took": 1,
  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": 0.2876821,
  16. "hits": [
  17. {
  18. "_index": ".opensearch-custom-rules-config",
  19. "_id": "ZaFv1IMBdLpXWBiBa1XI",
  20. "_version": 2,
  21. "_seq_no": 1,
  22. "_primary_term": 1,
  23. "_score": 0.2876821,
  24. "_source": {
  25. "category": "windows",
  26. "title": "Moriya Rooskit",
  27. "log_source": "",
  28. "description": "Detects the use of Moriya rootkit as described in the securelist's Operation TunnelSnake report",
  29. "references": [
  30. {
  31. "value": "https://securelist.com/operation-tunnelsnake-and-moriya-rootkit/101831"
  32. }
  33. ],
  34. "tags": [
  35. {
  36. "value": "attack.persistence"
  37. },
  38. {
  39. "value": "attack.privilege_escalation"
  40. },
  41. {
  42. "value": "attack.t1543.003"
  43. }
  44. ],
  45. "level": "critical",
  46. "false_positives": [
  47. {
  48. "value": "Unknown"
  49. }
  50. ],
  51. "author": "Bhabesh Raj",
  52. "status": "experimental",
  53. "last_update_time": "2021-05-06T00:00:00.000Z",
  54. "queries": [
  55. {
  56. "value": "(Provider_Name: \"Service_ws_Control_ws_Manager\") AND (event_uid: 7045) AND (ServiceName: \"ZzNetSvc\")"
  57. }
  58. ],
  59. "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"
  60. }
  61. }
  62. ]
  63. }
  64. }

Delete Custom Rule (not forced)

Sample request

  1. DELETE /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI

Sample response

  1. {
  2. "error": {
  3. "root_cause": [
  4. {
  5. "type": "security_analytics_exception",
  6. "reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true"
  7. }
  8. ],
  9. "type": "security_analytics_exception",
  10. "reason": "Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true",
  11. "caused_by": {
  12. "type": "exception",
  13. "reason": "org.opensearch.OpenSearchStatusException: Rule with id ZaFv1IMBdLpXWBiBa1XI is actively used by detectors. Deletion can be forced by setting forced flag to true"
  14. }
  15. },
  16. "status": 500
  17. }

Delete Custom Rule (forced)

Sample request

  1. DELETE /_plugins/_security_analytics/rules/ZaFv1IMBdLpXWBiBa1XI?forced=true

Sample response

  1. {
  2. "_id": "ZaFv1IMBdLpXWBiBa1XI",
  3. "_version": 1
  4. }