Merge pull request #1416 from vpiserchia/msdefender-indicators-update

Update MS Defender Responders

Author: nusantara-self

responders/MSDefenderEndpoints/MSDefenderEndpoints.py

@@ -6,6 +6,32 @@
 import json
 import datetime
 
+# https://learn.microsoft.com/en-us/defender-endpoint/indicators-overview
+IP_HOSTNAME_ACTIONS = [
+  'isolateMachine',
+  'unisolateMachine',
+  'runFullVirusScan',
+  'restrictAppExecution',
+  'unrestrictAppExecution',
+  'startAutoInvestigation'
+]
+URL_DOMAIN_ACTIONS = [
+  'pushIOCAllowed',
+  'pushIOCAudit',
+  'pushIOCWarn',
+  'pushIOCBlock',
+  'pushIOCAlert'  # Deprecated: maps to Audit internally
+]
+
+ACTIONS = {
+  'hash': URL_DOMAIN_ACTIONS + ['pushIOCBlockAndRemediate'],
+  'ip': URL_DOMAIN_ACTIONS + IP_HOSTNAME_ACTIONS,
+  'url': URL_DOMAIN_ACTIONS,
+  'domain': URL_DOMAIN_ACTIONS,
+  'fqdn': URL_DOMAIN_ACTIONS,
+  'hostname': IP_HOSTNAME_ACTIONS,
+}
+
 class MSDefenderEndpoints(Responder):
     def __init__(self):
         Responder.__init__(self)
@@ -48,10 +74,8 @@ def run(self):
         try:
             response = urllib.request.urlopen(req)
         except urllib.error.HTTPError as e:
-            #print("message: HTTP ErrorCode {}. Reason: {}".format(e.code,e.reason))
             self.error({'message': "HTTP ErrorCode {}. Reason: {}".format(e.code,e.reason)})
         except urllib.error.URLError as e:
-            #print("message: URL Error: {}".format(e.reason))
             self.error({'message': "URL Error: {}".format(e.reason)})
 
         jsonResponse = json.loads(response.read())
@@ -69,8 +93,10 @@ def getMachineId(id):
 
             if self.observableType == "ip":
                 url = "{}/machines/findbyip(ip='{}',timestamp={})".format(self.msdefenderApiBaseUrl, id, time)
-            else:
+            elif self.observableType == "hostname":
                 url = "{}/machines?$filter=computerDnsName+eq+'{}'".format(self.msdefenderApiBaseUrl, id)
+            else:
+                self.error({'message': f"Data type {self.observableType} not supported, accepted types are: 'ip', 'hostname'."})
 
             try:
                 response = self.msdefenderSession.get(url=url)
@@ -223,13 +249,12 @@ def startAutoInvestigation(machineId):
                 self.error({'message': e})
 
 
-        def pushCustomIocAlert(observable):
-
+        def pushCustomIoc(observable, mode='Block', severity='Medium', alert=True):
             if self.observableType == 'ip':
                 indicatorType = 'IpAddress'
             elif self.observableType == 'url':
                 indicatorType = 'Url'
-            elif self.observableType == 'domain':
+            elif self.observableType in ('domain', 'fqdn'):
                 indicatorType = 'DomainName'
             elif self.observableType == 'hash':
                 if len(observable) == 32:
@@ -241,83 +266,69 @@ def pushCustomIocAlert(observable):
                 else:
                     self.report({'message':"Observable is not a valid hash"})
             else:
-                self.error({'message':"Observable type must be ip, url, domain or hash"})
+                self.error({'message': "Observable type must be 'ip', 'url', 'domain', 'fqdn' or 'hash'"})
 
             url = '{}/indicators'.format(self.msdefenderApiBaseUrl)
             body = {
                 'indicatorValue': observable,
                 'indicatorType': indicatorType,
-                'action': 'Alert',
+                'action': mode,
                 'title': "TheHive IOC: {}".format(self.caseTitle),
-                'severity': 'High',
+                'severity': severity,
                 'description': "TheHive case: {} - caseId {}".format(self.caseTitle,self.caseId),
-                'recommendedActions': 'N/A'
+                'recommendedActions': 'N/A',
+                'generateAlert': alert
             }
 
             try:
                 response = self.msdefenderSession.post(url=url, json=body)
                 if response.status_code == 200:
-                    self.report({'message': "Added IOC to Defender with Alert mode: " + self.observable })
+                    self.report({'message': "Added IOC to Defender with %s mode: " % mode + self.observable })
             except requests.exceptions.RequestException as e:
                 self.error({'message': e})
 
-        def pushCustomIocBlock(observable):
-
-            if self.observableType == 'ip':
-                indicatorType = 'IpAddress'
-            elif self.observableType == 'url':
-                indicatorType = 'Url'
-            elif self.observableType == 'domain':
-                indicatorType = 'DomainName'
-            elif self.observableType == 'hash':
-                if len(observable) == 32:
-                    indicatorType = 'FileMd5'
-                elif len(observable) == 40:
-                    indicatorType = 'FileSha1'
-                elif len(observable) == 64:
-                    indicatorType = 'FileSha256'
-                else:
-                    self.report({'message':"Observable is not a valid hash"})
-            else:
-                self.error({'message':"Observable type must be ip, url, domain or hash"})
-
-            url = '{}/indicators'.format(self.msdefenderApiBaseUrl)
-            body = {
-                'indicatorValue' : observable,
-                'indicatorType' : indicatorType,
-                'action' : 'AlertAndBlock',
-                'title' : "TheHive IOC: {}".format(self.caseTitle),
-                'severity' : 'High',
-                'description' : "TheHive case: {} - caseId {}".format(self.caseTitle,self.caseId),
-                'recommendedActions' : 'N/A'
-            }
-
-            try:
-                response = self.msdefenderSession.post(url=url, json=body)
-                if response.status_code == 200:
-                    self.report({'message': "Added IOC to Defender with Alert and Block mode: " + self.observable })
-            except requests.exceptions.RequestException as e:
-                self.error({'message': e})
 
+        # validate the observable type and service requested upon it
+        # Note: "certificate thumbprint" is not supported by this responder
+        #       since it would require a custom observable type for it.
+        #
+        if self.observableType not in ACTIONS:
+            self.error({'message': "Observable type must be 'hostname', 'ip', 'url', 'domain', 'fqdn', 'hash'"})
+        elif self.service not in ACTIONS.get(self.observableType, []):
+            self.error(
+              {'message': f"Action '{self.service}' not supported for type '{self.observableType}'.\n"
+                          f"Valid actions are {ACTIONS[self.observableType]}" })
 
-        if self.service == "isolateMachine":
-            isolateMachine(getMachineId(self.observable))
-        elif self.service == "unisolateMachine":
-            unisolateMachine(getMachineId(self.observable))
-        elif self.service == "runFullVirusScan":
-            runFullVirusScan(getMachineId(self.observable))
-        elif self.service == "restrictAppExecution":
-            restrictAppExecution(getMachineId(self.observable))
-        elif self.service == "unrestrictAppExecution":
-            unrestrictAppExecution(getMachineId(self.observable))
-        elif self.service == "startAutoInvestigation":
-            startAutoInvestigation(getMachineId(self.observable))
-        elif self.service == "pushIOCBlock":
-            pushCustomIocBlock(self.observable)
-        elif self.service == "pushIOCAlert":
-            pushCustomIocAlert(self.observable)
-        else:
-            self.error({'message': "Unidentified service"})
+        # run action
+        try:
+            if self.service == "isolateMachine":
+                isolateMachine(getMachineId(self.observable))
+            elif self.service == "unisolateMachine":
+                unisolateMachine(getMachineId(self.observable))
+            elif self.service == "runFullVirusScan":
+                runFullVirusScan(getMachineId(self.observable))
+            elif self.service == "restrictAppExecution":
+                restrictAppExecution(getMachineId(self.observable))
+            elif self.service == "unrestrictAppExecution":
+                unrestrictAppExecution(getMachineId(self.observable))
+            elif self.service == "startAutoInvestigation":
+                startAutoInvestigation(getMachineId(self.observable))
+            elif self.service == "pushIOCBlock":
+                pushCustomIoc(self.observable, 'Block', 'Low', False)
+            elif self.service == "pushIOCAlert":
+                pushCustomIoc(self.observable, 'Audit', 'Informational', True)
+            elif self.service == "pushIOCAudit":
+                pushCustomIoc(self.observable, 'Audit', 'Informational', True)
+            elif self.service == "pushIOCAllowed":
+                pushCustomIoc(self.observable, 'Allowed', 'Informational', False)
+            elif self.service == "pushIOCBlockAndRemediate":
+                pushCustomIoc(self.observable, 'BlockAndRemediate', 'High', True)
+            elif self.service == "pushIOCWarn":
+                pushCustomIoc(self.observable, 'Warn', 'Medium', True)
+            else:
+                self.error({'message': "Unidentified service"})
+        except Exception as e:
+            self.error({'message': e})
 
     def operations(self, raw):
         self.build_operation('AddTagToCase', tag='MSDefenderResponder:run')
@@ -331,7 +342,18 @@ def operations(self, raw):
             return [self.build_operation("AddTagToArtifact", tag="MsDefender:restrictedAppExec")]
         elif self.service == "unrestrictAppExecution":
             return [self.build_operation("AddTagToArtifact", tag="MsDefender:unrestrictedAppExec")]
+        elif self.service == "pushIOCBlock":
+            return [self.build_operation("AddTagToArtifact", tag="MsDefender:pushIOCBlock")]
+        elif self.service == "pushIOCAudit":
+            return [self.build_operation("AddTagToArtifact", tag="MsDefender:pushIOCAudit")]
+        elif self.service == "pushIOCAllowed":
+            return [self.build_operation("AddTagToArtifact", tag="MsDefender:pushIOCAllowed")]
+        elif self.service == "pushIOCBlockAndRemediate":
+            return [self.build_operation("AddTagToArtifact", tag="MsDefender:pushIOCBlockAndRemediate")]
+        elif self.service == "pushIOCWarn":
+            return [self.build_operation("AddTagToArtifact", tag="MsDefender:pushIOCWarn")]
 
-if __name__ == '__main__':
 
+if __name__ == '__main__':
   MSDefenderEndpoints().run()
+

responders/MSDefenderEndpoints/MSDefenderEndpoints_AutoInvestigation.json

@@ -38,7 +38,7 @@
       },
       {
         "name": "resourceAppIdUri",
-        "description": "Security Center URI, usually doens't need to change",
+        "description": "Security Center URI, usually doesn't need to change",
         "type": "string",
         "multi": false,
         "required": true,

responders/MSDefenderEndpoints/MSDefenderEndpoints_Isolate.json

@@ -38,7 +38,7 @@
     },
     {
       "name": "resourceAppIdUri",
-      "description": "Security Center URI, usually doens't need to change",
+      "description": "Security Center URI, usually doesn't need to change",
       "type": "string",
       "multi": false,
       "required": true,

responders/MSDefenderEndpoints/MSDefenderEndpoints_PushIOCAlert.json

@@ -4,7 +4,7 @@
   "author": "Keijo Korte, Louis-Maximilien Dupouy",
   "url": "https://github.com/TheHive-Project/Cortex-Analyzers",
   "license": "AGPL-V3",
-  "description": "Push IOC to Defender client. Alert mode",
+  "description": "Push IOC to Defender client. Alert mode. This mode is Deprecated and Audit should be used instead.",
   "dataTypeList": ["thehive:case_artifact"],
   "command": "MSDefenderEndpoints/MSDefenderEndpoints.py",
   "baseConfig": "MSDefenderforEndpoints",
@@ -38,7 +38,7 @@
     },
     {
       "name": "resourceAppIdUri",
-      "description": "Security Center URI, usually doens't need to change",
+      "description": "Security Center URI, usually doesn't need to change",
       "type": "string",
       "multi": false,
       "required": true,

responders/MSDefenderEndpoints/MSDefenderEndpoints_PushIOCAllowed.json

@@ -0,0 +1,60 @@
+{
+  "name": "MSDefender-PushIOC-Allowed",
+  "version": "1.0",
+  "author": "Vito Piserchia",
+  "url": "https://github.com/TheHive-Project/Cortex-Analyzers",
+  "license": "AGPL-V3",
+  "description": "Push IOC to Defender client. Allowed mode",
+  "dataTypeList": ["thehive:case_artifact"],
+  "command": "MSDefenderEndpoints/MSDefenderEndpoints.py",
+  "baseConfig": "MSDefenderforEndpoints",
+  "config": {
+    "service": "pushIOCAllowed"
+  },
+  "configurationItems": [
+    {
+      "name": "tenantId",
+      "description": "Azure tenant ID",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "abcdef12-ab12-abc12-ab12-abcdef123456"
+    },
+    {
+      "name": "appId",
+      "description": "Azure app ID",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "abcdef12-ab12-abc12-ab12-abcdef123456"
+    },
+    {
+      "name": "appSecret",
+      "description": "Azure app secret",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890="
+    },
+    {
+      "name": "resourceAppIdUri",
+      "description": "Security Center URI, usually doesn't need to change",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "https://api.security.microsoft.com"
+    },
+    {
+      "name": "oAuthUri",
+      "description": "Azure oAuth2 authentication endpoint",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "https://login.microsoftonline.com"
+    }
+  ],
+  "registration_required": true,
+  "subscription_required": true,
+  "free_subscription": false,
+  "service_homepage": "https://securitycenter.windows.com"
+}

responders/MSDefenderEndpoints/MSDefenderEndpoints_PushIOCAudit.json

@@ -0,0 +1,60 @@
+{
+  "name": "MSDefender-PushIOC-Audit",
+  "version": "1.0",
+  "author": "Vito Piserchia",
+  "url": "https://github.com/TheHive-Project/Cortex-Analyzers",
+  "license": "AGPL-V3",
+  "description": "Push IOC to Defender client. Audit mode",
+  "dataTypeList": ["thehive:case_artifact"],
+  "command": "MSDefenderEndpoints/MSDefenderEndpoints.py",
+  "baseConfig": "MSDefenderforEndpoints",
+  "config": {
+    "service": "pushIOCAudit"
+  },
+  "configurationItems": [
+    {
+      "name": "tenantId",
+      "description": "Azure tenant ID",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "abcdef12-ab12-abc12-ab12-abcdef123456"
+    },
+    {
+      "name": "appId",
+      "description": "Azure app ID",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "abcdef12-ab12-abc12-ab12-abcdef123456"
+    },
+    {
+      "name": "appSecret",
+      "description": "Azure app secret",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890="
+    },
+    {
+      "name": "resourceAppIdUri",
+      "description": "Security Center URI, usually doesn't need to change",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "https://api.security.microsoft.com"
+    },
+    {
+      "name": "oAuthUri",
+      "description": "Azure oAuth2 authentication endpoint",
+      "type": "string",
+      "multi": false,
+      "required": true,
+      "defaultValue": "https://login.microsoftonline.com"
+    }
+  ],
+  "registration_required": true,
+  "subscription_required": true,
+  "free_subscription": false,
+  "service_homepage": "https://securitycenter.windows.com"
+}