To run this collector, there are some configurations detailed below that you need to consider.
Configuration
Details
Azure account
Azure account with admin level permissions and Azure AD tenant.
Credentials
The credentials configuration block has been filled correctly.
Info
More information
Refer to the Vendor setup section to know more about these configurations.
Overview
The Microsoft Graph Collector provides the ability to collect data and intelligence from services such as Microsoft 365, Windows, and Enterprise Mobility and Security. This data collector is able to ingest security alerts, scores, provisioning, audit, and sign-ins retrieved from Microsoft products, allowing you to empower streamlined security operations and better defend against threats faced in Azure AD and Microsoft 365 environments.
...
Data source
Description
API endpoint
Collector service name
Devo table
Available from release
Alerts
Represents potential security issues within a customer’s tenant that Microsoft or partner security solutions have identified.
Refer to Microsoft documentation about Alert Resource Type for more information.
Represents the directory audit items and its collection.
Refer to the Microsoft documentation for more information about Directory audit.
https://graph.microsoft.com/v1.0/auditLogs/directoryAudits?$filter=activityDateTime ge {start_time}&$orderby=activityDateTime+asc&$top={items_per_main_request}
audit
cloud.azure.ad.audit
v1.2.0
Provisioning
Represents an action performed by the Azure AD Provisioning service and its associated properties.
Refer to the Microsoft documentation for more information about Provisioning.
https://graph.microsoft.com/beta/auditLogs/provisioning?$filter=activityDateTime ge {start_time}&$orderby=activityDateTime+asc&$top={items_per_main_request}
provisioning
cloud.azure.ad.audit
v1.2.0
Sign-in
Details user and application sign-in activity for a tenant (directory).
Refer to the Microsoft documentation for more information about Sign-in.
Microsoft Graph data collector works over Microsoft products. To activate the resources from the Microsoft Graph API, you need:
...
Note
You need the Admin level permissions on the Azure portal as the subscription setup will require admin consent API permissions, authentications, and audits.
Action
Steps
1
Register and configure the application
Go to Azure portal and click on Azure Active Directory.
Click on App registration on the left-menu side. Then click on + New registration.
On the Register and Application page:
Name the application.
Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) in Supported Accounts type.
In Redirect URI (optional) leave it as default (blank).
Click Register.
App registration page will open. Click on your app to configure it and give it permissions. You will see your app’s dashboard with information (docs, endpoints, etc.) when clicking it.
Click Authentication on the left-menu side, then choose + Add a platform and select Mobile and desktop application.
Click + Add permission in case you don’t have Microsoft Graph in the API/Permission list.
Select Application permissions and search for Security. Check SecurityEvents.Read.All.
Repeat the same step 3 for AuditLog.Read.All,Directory.Read.All and User.Read. If you did everything correctly, permissions will display.
Select Grant admin consent for the applications.
Info
You do not need to activate permissions if you are not going to use its corresponding resource. Check the Permissions reference per service section for a detailed breakdown on resource and their needed permissions.
3
Obtain the requires credentials for the collector
Go to Certificates & Secrets, select + New client secret . Named it and copy the token value.
Go to Overview to get your Tenant ID and Client ID and copy both values.
Note
The token will display only once. You will need to create another one if you didn’t copy it the first time.
...
Rw ui tabs macro
Rw tab
title
On-premise collector
This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.
Structure
The following directory structure should be created for being used when running the collector:
In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/. Learn more about security credentials in Devo here.
All defined service entities will be executed by the collector. If you do not want to run any of them, just remove the entity from the services object.
Replace the placeholders with your required values following the description table below:
Parameter
Data type
Type
Value range / Format
Details
<debug_status>
bool
Mandatory
false / true
If the value is true, the debug logging traces will be enabled when running the collector. If the value is false, only the info, warning and error logging levels will be printed.
<collector_id>
int
Mandatory
Minimum length: 1 Maximum length: 5
Use this param to give a unique id to this collector.
<collector_name>
str
Mandatory
Minimum length: 1 Maximum length: 10
Use this param to give a valid name to this collector, like microsoft_graph.
<devo_address>
str
Mandatory
collector-us.devo.io collector-eu.devo.io
Use this param to identify the Devo Cloud where the events will be sent.
<chain_filename>
str
Mandatory
Minimum length: 4 Maximum length: 20
Use this param to identify the chain.cert file downloaded from your Devo domain. Usually this file's name is: chain.crt
<cert_filename>
str
Mandatory
Minimum length: 4 Maximum length: 20
Use this param to identify the file.cert downloaded from your Devo domain.
<key_filename>
str
Mandatory
Minimum length: 4 Maximum length: 20
Use this param to identify the file.key downloaded from your Devo domain.
<input_id>
int
Mandatory
Minimum length: 1 Maximum length: 5
Use this param to give a unique id to this input service.
Note
This parameter is used to build the persistence address, do not use the same value for multiple collectors. It could cause a collision.
<run_service>
bool
Mandatory
false / true
Use this param to enable or disable the given input logic when running the collector. If the value is true, the input will be run. If the value is false, it will be ignored.
<requests_per_second_value>
int
Optional
Minimum value: 1
Customize the maximum number of API requests per second. If not used, the default setting will be used: 60 requests/sec.
Info
This parameter should be removed itf it is not used.
<tenant_id_value>
str
Mandatory
UUID format
This is the Tenant’s ID you created in Azure AD. You can obtain it from the Overview page in your registered application.
<client_id_value>
srt
Mandatory
UUID format
This is the Tenant’s ID you created in Azure AD. You can obtain it from the Overview page in your registered application.
<client_secret_value>
srt
Mandatory
Any non-whitespace character
This is the Client’s secret you created in Azure AD. You can obtain it from the Certificates & secrets page in your registered application.
<request_period_in_seconds_value>
int
Optional
Minimum value: 1
The amount (in seconds) in which the service’s collection is scheduled.
Info
This parameter should be removed itf it is not used.
<start_time_value>
srt
Optional
For the secure_scores service: YYYY-MM-DDTHH:mm:ssZ
For the rest of the services: YYYY-MM-DDTHH:mm:ss.SSSZ
This will allow you to start from a specific date in case you want to ingest historic events. If not set, it will start at the current time.
Info
This parameter should be removed itf it is not used.
<tag_version>
srt
Optional
Only accepts v1 (default) or v2
The tag_version parameter is only implemented for the alerts, secure_scores and secure_score_control_profile(s) services. This parameter configured the destination tables according to their tagging:
v1 will use the original cloud.msgraph... tagging.
v2 will use the new tags cloud.azure... and cloud.office365... introduced in the v1.1.3 release.
It is not necessary to include this parameter in the configuration to maintain backward compatibility. If there is no value, "v1" is assumed to maintain backward compatibility. With this, we can upgrade collectors whose version is previous to v1.1.3 without applying any changes. However, the recommendation is to set it to "v2" for new deployments.
Info
This parameter should be removed itf it is not used.
Download the Docker image
The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:
Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace <image_file> and <version> with a proper value.
The Docker image can be deployed on the following services:
Docker
Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/
Replace <product_name>, <image_name> and <version> with the proper values.
Docker Compose
The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.
To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:
Code Block
IMAGE_VERSION=<version> docker-compose up -d
Note
Replace <product_name>, <image_name> and <version> with the proper values.
Rw tab
title
Cloud collector
We use a piece of software called Collector Server to host and manage all our available collectors. If you want us to host this collector for you, get in touch with us and we will guide you through the configuration.
...
Release
Released on
Release type
Details
Recommendations
v1.2.0
Status
colour
Purple
title
NEW FEATURE
Status
colour
Green
title
IMPROVEMENT
New features:
New supported sources
Sign In (signIn service)
Audit (audit service)
Provisioning (provisioning service)
Previous services modification
The new tagging introduced in the previous v1.1.3 release is now customizable through the tag_version service parameter. The default tagging has been reverted to the original one.
The alerts source, when setting the tag_version to v2, will try to categorize the events by applying different tags based on the event’s provider.
Improvements:
Token validation is now performed against the corresponding endpoint.
Recommended version
v1.3.0
November, 2023
Status
colour
Green
title
IMPROVEMENT
-
-
Configuration checklist
Here you will find a brief checklist of the important configurations that need to be done for deploying this collector: