This repository is two-folded:
- It holds a Splunk add-on which utilzes MS Defender 365 vulnerabilties data; CIM normalizes the data into the Vulnerabilties data model and creates asset lookup lists for Enterprise Security.
- Holds a python script which can be used to collect that said data to Splunk.
The app also provides an example view of how the data can be presented for a system manager (not so technical role). The view is included both as a Classic XML and also as a Dashboard Studio view. Use this as a starting point and tailor it to your own environment and needs.
Dashboard studio example
To further enchance your investigation options you should also be ingesting Defender for Endpoint events as well. We recommend using this add-on:
Install the latest release package TA-microsoft-365-defender-threat-vulnerability-add-on-<tag>.tar.gz
to the Splunk Search Head/SH Cluster via your usual methods.
Indexer(s) only needs props.conf
, but it doesn't hurt to just install the whole add-on to them.
And if you rely on HFs for the data collection they need props.conf
as well.
Install the add-on via the GUI or using the Splunk ACS API and you're all good!
The included dashboard and reports relies on macros.
ms_defender_index
- needs to be set to where the vulnerability data is being indexed.get_system_from_machinetags(<regex>)
- this macro applies a given regex to the fieldmachineTags
in the lookupms_defender_endpoint_machines_assets.csv
The last macro is needed to filter out unwanted Azure device tags in the dropdown menu of the dashboard, i.e. the inputed text functions as an allow list.
For example. if your tags are named HR, Accounting and IT Services the regex would be get_system_from_machinetags((HR|Accounting|IT\sServices))
.
After data is being indexed, run and enable the reports included. Make sure to have set the macro ms_defender_index
first.
Lookup - MS Defender 365 - DeviceInfo
Lookup - MS Defender 365 - MachineInfo
Lookup - Vulnerabilities description
The provided script collects data from three sources and needs to be set to run periodically , e.g. a cronjob.
Depending on your environment and knowledge, you can select multiple routes of collecting these events.
- Use the script as is on a HF to forward the data.
- Use Azure Functions to the write the json-data to either HEC or an EventHub. It's the function
write_results
that has to be modified towards the desired output. - Use Splunk SOAR / Cribl to query the APIs directly and post the data to Splunk
The collection script uses two of Microsofts APIs:
- Defender 365 API -
https://api.security.microsoft.com
- Defender for Endpoint -
https://api.securitycenter.microsoft.com
Collected data | API call | Permission needed |
---|---|---|
Machine info | GET https://api.securitycenter.microsoft.com/api/machines |
Machine.Read.All |
Full export of vulnerabilities | GET https://api.securitycenter.microsoft.com/api/machines/SoftwareVulnerabilitiesExport |
Vulnerability.Read.All |
Delta export of vulnerabilities | GET https://api.securitycenter.microsoft.com/api/machines/SoftwareVulnerabilityChangesByMachine |
Vulnerability.Read.All |
Description of vulnerabilities | POST https://api.security.microsoft.com/api/advancedhunting/run |
AdvancedHunting.Read.All |
Click for a detailed walkthrough!
Start of by registering the app that will be used in the script, for authentication.
![1](https://user-images.githubusercontent.com/50480144/169120546-dce5724a-8d5d-4b63-a0f5-92e0c1e3ca2d.png)
The secret will act as a password for the application in the OAuth flow. Make sure to copy the value of the secret when creating it - this will only be shown once.
![2](https://user-images.githubusercontent.com/50480144/169120617-a64b10dc-6af7-492a-83b6-4a9a5aab50b7.png)
![3](https://user-images.githubusercontent.com/50480144/169120630-3ea833fc-a8ea-4ff4-ab10-9abde4ccd0d1.png)
![4](https://user-images.githubusercontent.com/50480144/169120635-90240e41-f884-4021-b44f-07b2ce72bdb3.png)
![5](https://user-images.githubusercontent.com/50480144/169120650-5365c518-54b3-4fbd-a4c3-4a49faca3e47.png)
![6](https://user-images.githubusercontent.com/50480144/169120659-0283cfc1-0681-4f2a-9b41-bd8f3f49c09f.png)
Needed permission AdvancedHunting.Read.All
![7](https://user-images.githubusercontent.com/50480144/169120666-979b6227-a0d3-4af9-bf0e-116d8896f500.png)
![8](https://user-images.githubusercontent.com/50480144/169120673-019ac4cf-57e0-486c-88dc-252d562da8f1.png)
![9](https://user-images.githubusercontent.com/50480144/169120679-95eab735-8743-49b2-bf11-8f937426194e.png)
Needed permissions Machine.Read.All
and Vulnerability.Read.All
![10](https://user-images.githubusercontent.com/50480144/169120683-4c9cdbfb-881a-4315-850a-9d505034da76.png)
![11](https://user-images.githubusercontent.com/50480144/169120690-b6bc28e8-ab19-4a77-9527-44162a8d9834.png)
![12](https://user-images.githubusercontent.com/50480144/169120694-769314e3-5117-484e-9a40-20f191f22dc8.png)
![13](https://user-images.githubusercontent.com/50480144/169120696-fb0837aa-ff72-425f-998e-b974a3f90ba8.png)
![14](https://user-images.githubusercontent.com/50480144/169125882-5528de41-f8bc-4830-8597-cb00073d3817.png)
![15](https://user-images.githubusercontent.com/50480144/169125903-0b4f4d94-ace3-44b1-9680-c8af5147a4b1.png)
![16](https://user-images.githubusercontent.com/50480144/169125916-4d90f4dd-2391-473d-8bb2-029fd73d9024.png)
In the config script either uncomment and use a Key Vault, or fill in hardcoded values (not recommended)
![17](https://user-images.githubusercontent.com/50480144/169125925-68fd656b-d41b-428e-9d59-7166028cb127.png)
Setting custom tags on the devices lets us categorize which business system a device belongs to, if this information isn't coming to Splunk from some other place.
A tag can be e.g. HR
or IT Support
, and they can be set using GPO / Powershell / Intune / API.
Using the API is probably preferable since it can be used regardless of the machine OS.
There are a couple of points to be aware of when you are using the registry to tag a machine:
- The tag is fixed and cannot be changed through the portal, it can only be changed by modifying the registry.
- Only one tag can be specified in the registry.
See below links for guides and code
- How to use tagging effectively (Part 1)
- How to use tagging effectively (Part 2)
- How to use tagging effectively (Part 3) - Scripting tags
- Open the Defender 365 portal and select Device Inventory
- Select a device and assign it a tag
- How the device tag is shown in Splunk
You can use jwt.ms to validate that your returned auth token has the correct roles
If the delta export is set to run too often (e.g. every hour) it's been observed that the output file is blank. Defender doesn't update its tables in real time.