Merge pull request #20 from ianwills-splunk/certifcate-based-authentication

Author: grokas-splunk

NOTICE

@@ -1,2 +1,35 @@
 Splunk SOAR App: Microsoft 365 Defender
 Copyright (c) 2022-2025 Splunk Inc.
+Third Party Software Attributions:
+
+@@@@============================================================================
+
+Library: msal - 1.33.0
+Homepage: https://github.com/AzureAD/microsoft-authentication-library-for-python
+License: MIT License
+License Text:
+
+The MIT License (MIT)
+
+Copyright (c) Microsoft Corporation.
+All rights reserved.
+
+This code is licensed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files(the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions :
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,9 +1,9 @@
 # Microsoft 365 Defender
 
-Publisher: Splunk \
-Connector Version: 1.4.3 \
-Product Vendor: Microsoft \
-Product Name: Microsoft 365 Defender \
+Publisher: Splunk <br>
+Connector Version: 1.4.3 <br>
+Product Vendor: Microsoft <br>
+Product Name: Microsoft 365 Defender <br>
 Minimum Product Version: 6.3.0
 
 This app integrates with Microsoft 365 Defender to execute various generic and investigative actions
@@ -98,7 +98,7 @@ are the default ports used by Splunk SOAR.
 
      - offline_access
 
-#### Create a client secret
+#### Create a client secret or jump to next section to use Certificate Based Authentication
 
 17. Select the 'Certificates & secrets' menu from the left-side panel.
 01. Select 'New client secret' button to open a pop-up window.
@@ -107,9 +107,17 @@ are the default ports used by Splunk SOAR.
 01. Click 'Copy to clipboard' to copy the generated secret value and paste it in a safe place. You
     will need it to configure the asset and will not be able to retrieve it later.
 
+#### Using Certificate Based Authentication
+
+21. Select the 'Certificates & secrets' menu from the left-side panel.
+01. Select the 'Certificates' tab.
+01. Click 'Upload Certificate' and choose a '\*.crt' file that contains the server certificate.
+01. Select the 'Thumbprint' for the newly uploaded certificate and copy it somewhere to be
+    used when configuring the SOAR app.
+
 #### Copy your application id and tenant id
 
-21. Select the 'Overview' menu from the left-side panel.
+25. Select the 'Overview' menu from the left-side panel.
 01. Copy the **Application (client) ID** and **Directory (tenant) ID** . You will need these to
     configure the SOAR asset.
 
@@ -124,7 +132,14 @@ When creating an asset for the app,
   ID' field.
 
 - Provide the client secret of the app created during the previous step of app creation in the
-  'Client Secret' field.
+  'Client Secret' field. -or- If using Certificate Based Authenticaion, do not not enter anything
+  in this field, instead, complete the next three steps.
+
+- For Certificate Based Authentication only: Provide the 'Certificate Thumbprint' recorded above from Microsoft Entra.
+
+- For Certificate Based Authentication only: Provide the 'Certificate Private Key' (cut and paste the .pem file contents).
+
+- For Certificate Based Authentication only: Ensure the 'Non-Interactive Auth' checkbox is checked.
 
 - Provide the tenant ID of the app created during the previous step of Azure app creation in the
   'Tenant ID' field. For getting the value of tenant ID, navigate to the Microsoft Entra ID; The value displayed in the 'Tenant ID'.
@@ -268,7 +283,9 @@ VARIABLE | REQUIRED | TYPE | DESCRIPTION
 -------- | -------- | ---- | -----------
 **tenant_id** | required | string | Tenant ID |
 **client_id** | required | string | Client ID |
-**client_secret** | required | password | Client Secret |
+**client_secret** | optional | password | Client Secret |
+**certificate_thumbprint** | optional | password | Certificate Thumbprint (required for CBA) |
+**certificate_private_key** | optional | password | Certificate Private Key (.PEM) |
 **timeout** | optional | numeric | HTTP API timeout in seconds |
 **non_interactive** | optional | boolean | Non-Interactive Auth |
 **max_incidents_per_poll** | optional | numeric | Maximum Incidents for scheduled/interval polling for each cycle |
@@ -277,21 +294,21 @@ VARIABLE | REQUIRED | TYPE | DESCRIPTION
 
 ### Supported Actions
 
-[test connectivity](#action-test-connectivity) - Validate the asset configuration for connectivity using supplied configuration \
-[on poll](#action-on-poll) - Callback action for the on_poll ingest functionality \
-[run query](#action-run-query) - An advanced search query \
-[list incidents](#action-list-incidents) - List all the incidents \
-[list alerts](#action-list-alerts) - List all the alerts \
-[get incident](#action-get-incident) - Retrieve specific incident by its ID \
-[update incident](#action-update-incident) - Update the properties of an incident object \
-[get alert](#action-get-alert) - Retrieve specific alert by its ID \
+[test connectivity](#action-test-connectivity) - Validate the asset configuration for connectivity using supplied configuration <br>
+[on poll](#action-on-poll) - Callback action for the on_poll ingest functionality <br>
+[run query](#action-run-query) - An advanced search query <br>
+[list incidents](#action-list-incidents) - List all the incidents <br>
+[list alerts](#action-list-alerts) - List all the alerts <br>
+[get incident](#action-get-incident) - Retrieve specific incident by its ID <br>
+[update incident](#action-update-incident) - Update the properties of an incident object <br>
+[get alert](#action-get-alert) - Retrieve specific alert by its ID <br>
 [update alert](#action-update-alert) - Update properties of existing alert
 
 ## action: 'test connectivity'
 
 Validate the asset configuration for connectivity using supplied configuration
 
-Type: **test** \
+Type: **test** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -306,7 +323,7 @@ No Output
 
 Callback action for the on_poll ingest functionality
 
-Type: **ingest** \
+Type: **ingest** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -327,7 +344,7 @@ No Output
 
 An advanced search query
 
-Type: **investigate** \
+Type: **investigate** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -359,7 +376,7 @@ summary.total_objects_successful | numeric | | 1 |
 
 List all the incidents
 
-Type: **investigate** \
+Type: **investigate** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -408,7 +425,7 @@ summary.total_objects_successful | numeric | | 1 |
 
 List all the alerts
 
-Type: **investigate** \
+Type: **investigate** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -582,7 +599,7 @@ action_result.data.\*.Intent_odata_type | string | | #Int64 |
 
 Retrieve specific incident by its ID
 
-Type: **investigate** \
+Type: **investigate** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -628,7 +645,7 @@ action_result.data.\*[email protected] | string | | https://graph.test.com/v1.0/$m
 
 Update the properties of an incident object
 
-Type: **generic** \
+Type: **generic** <br>
 Read only: **False**
 
 In this `SecurityIncident.ReadWrite.All` delegated or application permission is required. One of the parameters `status`, `assign_to`, `classification` or `determination` must be specified; otherwise, the action fails.
@@ -680,7 +697,7 @@ action_result.data.\*[email protected] | string | | https://graph.test.com/v1.0/$m
 
 Retrieve specific alert by its ID
 
-Type: **investigate** \
+Type: **investigate** <br>
 Read only: **True**
 
 #### Action Parameters
@@ -837,7 +854,7 @@ action_result.data.\*.evidence.\*.vmMetadata.subscriptionId | string | | |
 
 Update properties of existing alert
 
-Type: **generic** \
+Type: **generic** <br>
 Read only: **False**
 
 #### Action Parameters

manual_readme_content.md

@@ -88,7 +88,7 @@ are the default ports used by Splunk SOAR.
 
      - offline_access
 
-#### Create a client secret
+#### Create a client secret or jump to next section to use Certificate Based Authentication
 
 17. Select the 'Certificates & secrets' menu from the left-side panel.
 01. Select 'New client secret' button to open a pop-up window.
@@ -97,9 +97,17 @@ are the default ports used by Splunk SOAR.
 01. Click 'Copy to clipboard' to copy the generated secret value and paste it in a safe place. You
     will need it to configure the asset and will not be able to retrieve it later.
 
+#### Using Certificate Based Authentication
+
+21. Select the 'Certificates & secrets' menu from the left-side panel.
+01. Select the 'Certificates' tab.
+01. Click 'Upload Certificate' and choose a '\*.crt' file that contains the server certificate.
+01. Select the 'Thumbprint' for the newly uploaded certificate and copy it somewhere to be
+    used when configuring the SOAR app.
+
 #### Copy your application id and tenant id
 
-21. Select the 'Overview' menu from the left-side panel.
+25. Select the 'Overview' menu from the left-side panel.
 01. Copy the **Application (client) ID** and **Directory (tenant) ID** . You will need these to
     configure the SOAR asset.
 
@@ -114,7 +122,14 @@ When creating an asset for the app,
   ID' field.
 
 - Provide the client secret of the app created during the previous step of app creation in the
-  'Client Secret' field.
+  'Client Secret' field. -or- If using Certificate Based Authenticaion, do not not enter anything
+  in this field, instead, complete the next three steps.
+
+- For Certificate Based Authentication only: Provide the 'Certificate Thumbprint' recorded above from Microsoft Entra.
+
+- For Certificate Based Authentication only: Provide the 'Certificate Private Key' (cut and paste the .pem file contents).
+
+- For Certificate Based Authentication only: Ensure the 'Non-Interactive Auth' checkbox is checked.
 
 - Provide the tenant ID of the app created during the previous step of Azure app creation in the
   'Tenant ID' field. For getting the value of tenant ID, navigate to the Microsoft Entra ID; The value displayed in the 'Tenant ID'.

microsoft365defender.json

@@ -42,35 +42,47 @@
         "client_secret": {
             "description": "Client Secret",
             "data_type": "password",
-            "required": true,
+            "required": false,
             "order": 3
         },
+        "certificate_thumbprint": {
+            "description": "Certificate Thumbprint (required for CBA)",
+            "data_type": "password",
+            "order": 4,
+            "required": false
+        },
+        "certificate_private_key": {
+            "description": "Certificate Private Key (.PEM)",
+            "data_type": "password",
+            "required": false,
+            "order": 5
+        },
         "timeout": {
             "description": "HTTP API timeout in seconds",
             "data_type": "numeric",
-            "order": 4
+            "order": 6
         },
         "non_interactive": {
             "description": "Non-Interactive Auth",
             "data_type": "boolean",
             "default": false,
-            "order": 5
+            "order": 7
         },
         "max_incidents_per_poll": {
             "description": "Maximum Incidents for scheduled/interval polling for each cycle",
             "data_type": "numeric",
             "default": 1000,
-            "order": 6
+            "order": 8
         },
         "start_time": {
             "description": "Start time for schedule/interval/manual poll (Use this format: 1970-01-01T00:00:00Z)",
             "data_type": "string",
-            "order": 7
+            "order": 9
         },
         "filter": {
             "description": "Filter incidents based on property (example: status ne 'active')",
             "data_type": "string",
-            "order": 8
+            "order": 10
         }
     },
     "actions": [
@@ -4214,5 +4226,60 @@
             },
             "versions": "EQ(*)"
         }
-    ]
+    ],
+    "pip_dependencies": {
+        "wheel": []
+    },
+    "pip39_dependencies": {
+        "wheel": [
+            {
+                "module": "PyJWT",
+                "input_file": "wheels/py3/PyJWT-2.10.1-py3-none-any.whl"
+            },
+            {
+                "module": "cffi",
+                "input_file": "wheels/py39/cffi-2.0.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl"
+            },
+            {
+                "module": "cryptography",
+                "input_file": "wheels/py3/cryptography-46.0.1-cp38-abi3-manylinux_2_28_x86_64.whl"
+            },
+            {
+                "module": "msal",
+                "input_file": "wheels/py3/msal-1.34.0-py3-none-any.whl"
+            },
+            {
+                "module": "pycparser",
+                "input_file": "wheels/py3/pycparser-2.23-py3-none-any.whl"
+            },
+            {
+                "module": "typing_extensions",
+                "input_file": "wheels/py3/typing_extensions-4.15.0-py3-none-any.whl"
+            }
+        ]
+    },
+    "pip313_dependencies": {
+        "wheel": [
+            {
+                "module": "PyJWT",
+                "input_file": "wheels/py3/PyJWT-2.10.1-py3-none-any.whl"
+            },
+            {
+                "module": "cffi",
+                "input_file": "wheels/py313/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl"
+            },
+            {
+                "module": "cryptography",
+                "input_file": "wheels/py3/cryptography-46.0.1-cp311-abi3-manylinux_2_28_x86_64.whl"
+            },
+            {
+                "module": "msal",
+                "input_file": "wheels/py3/msal-1.34.0-py3-none-any.whl"
+            },
+            {
+                "module": "pycparser",
+                "input_file": "wheels/py3/pycparser-2.23-py3-none-any.whl"
+            }
+        ]
+    }
 }