Microsoft Graph collector

Service description

Microsoft Graph provides many services such as Microsoft 365, Office 365, Outlook, and others. At this moment, the Microsoft Graph collector only deals with security alerts and scores retrieved from the Microsoft products. This empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph collector includes the two key entities described in the following sections:

• Alerts
• Secure Scores

Alerts

Alerts are potential security issues within a customer's tenant that Microsoft or partner security solutions have identified and flagged for action or notification. With the Microsoft Graph alerts entity, you can unify and streamline management of security issues across all integrated solutions.

Alerts Security Providers:

• Azure Security Center

• Azure Active Directory Identity Protection

• Microsoft Cloud App Security

• Microsoft Defender Advanced Threat Protection

• Azure Advanced Threat Protection

• Cloud App Security (Update coming soon form MS Graph)

• Azure Information Protection

• Azure Sentinel

Secure Scores

Microsoft Secure Score is a security analytics solution that gives you visibility into your security portfolio and how to improve it. With a single score, you can better understand what you have done to reduce your risk in Microsoft solutions. You can also compare your score with other organizations and see how your score has been trending over time.

The Microsoft Graph secure score and secureScoreControlProfile entities help you balance your organization's security and productivity needs while enabling the appropriate mix of security features. You can also project what your score would be after you adopt security features.

Data source description

Currently, the Microsoft Graph collector generates security activities for these resources. The collector processes the Microsoft Graph responses and sends them to the Devo platform, which will categorize all the information received on tables along rows and columns on your Devo domain.

Microsoft Graph resources

Listed in the table below are the application names, details, and how the Devo platform treats the data and to which tables sends it:

Setup

The Microsoft Graph data collector works over the Microsoft products, such as Microsoft Azure Directory. To active the alerts and secure score resources from the Microsoft Graph API, a subscription on Microsoft Azure Directory followed by an app registration should be created, as well as configuring the resources with the right permissions for the best performance of the collector.

Setting up permissions on the subscription

1. Go to the Azure portal and click Azure Activity Directory.

2. Click App registrations → New registration to create a new app.

   

3. On the Register an Application page, give your application a name.

   • On Supported Accounts Type, select the third option (Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) )

   • On Redirect URI (optional), leave it blank (as default) and click Register.

4. After registering the app, it will be displayed in a list on the App registration page. Click your app to give it permissions and configure it. You’ll see the app on the dashboard with some important information, docs, and endpoints.

5. On the left menu, click Authentication → Add a platform → Mobile and desktop applications.

   

6. Mark the 3 redirect URIs and click configure.

   

7. On the left menu, click API permissions and check if you already have Microsoft Graph on the API/ Permission list. If not, click Add permission and add Microsoft Graph.

   

8. Now select Delegated permission and search for Security. Check all the boxes available for the service. Click Add a permission again, select Application permissions and check all the boxes available. If everything is correctly configured, your permissions will display as shown in the green square of the capture below. Then, click Grant admin consent for the applications. Repeat the same process with Application permissions.

   

Authentication

After applying the permissions, select Certificates & secrets →  New client secret, enter the desired name, and copy the token.

Getting the credentials

After creating the token, go to Overview to get your Tenant ID and Client ID. This information will be used on the collector server to run the application.

Run the 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 Microsoft Graph collector:

<any_directory>
└── devo-collectors/
    └── msgraph/
        ├── certs/
        │   ├── chain.crt
        │   ├── <your_domain>.key
        │   └── <your_domain>.crt
        └── config/ 
            └── config-msgraph.yaml

Devo credentials

In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <any directory>/devo-collectors/msgraph/certs. Learn more about security credentials in Devo here.

Editing the config-msgraph.yaml file

In the config-msgraph.yaml file, replace the <short_unique_identifier>, <tenant_id_value>, <client_id_value>, and <client_secret_value> values and enter the ones that you got in the previous steps. See inline comments to better understand the file.

globals:
  debug: False
  id: not_used
  name: microsoft_graph
  persistence:
#    type: redis                                               # Redis persistence (uncomment lines to activate it and set the proper values, also comment the filesystem)
#    config:
#      host: 192.168.56.10
#      port: 6379
#      password:
#      db: 0
#      socket_timeout: 5
    type: filesystem                                           # File system persistence ON
    config:
      directory_name: state                                    # Directory where the persistence will be saved in case of using filesystem
outputs:
  devo_1:                                                      # Cloud Devo config EU (for US use us.elb.relay.logtrust.net)
    type: devo_platform
    config:        
      address: eu.elb.relay.logtrust.net
      port: 443
      type: SSL
      chain: chain.crt
      cert: <certificate>.crt
      key: <certificate>.key
inputs:
  microsoft_graph:
    id: <short_unique_identifier>                              # The value of this field will be used internally for having independent persistence areas
    enabled: true
    requests_per_second: 5                                     # Setup how many request API por second
    autoconfig:
      enable: true                                             # Autoconfig always True for this collector
      refresh_interval_in_seconds: 60                          # Setting up the time for executing autoconfig interval. 60sec is recommended.
    credentials:
      tenant_id: <tenant_id_value>                             # Azure Directory Tenant ID
      client_id: <client_id_value>                             # Application client ID
      client_secret: <client_secret_value>                     # Application client secret
    services:                                                  # Services available for this collector are Alerts, Secure Score and Secure score control profile
      alerts:                                           
        request_period_in_seconds: 60                          # Setting up time interval between API requests. 60sec is recommended.                
#        start_time: "9999-12-31T23:59:59.999Z"                 # Collector Initial time. if this is blank or the data format is not valid, "time now" will be auto filled. 
      secure_scores:
        request_period_in_seconds: 86400                       # 86400 seconds => 1day in seconds, this is the recommended value, but it can be changed
#        start_time: "9999-12-31T23:59:59Z"
      secure_score_control_profile:
        request_period_in_seconds: 86400                       # 86400 seconds => 1day in seconds, this is the recommended value, but it can be changed

Download the Docker image

The collector should be deployed as a Docker container. Click here to download the Docker image of the collector as a .tgz file.

Use the following command to add the Docker image to the system:

gunzip -c collector-msgraph-docker-image-<version>.tgz | docker load

The Docker image can be deployed on the following services:

• Docker

• Docker Compose

Docker

Execute the following command on the root directory <any_directory>/devo-collectors/msgraph/

docker run \
--name collector-msgraph \
--volume $PWD/certs:/devo-collector/certs \
--volume $PWD/config:/devo-collector/config \
--volume $PWD/state:/devo-collector/state \
--env CONFIG_FILE=config-msgraph.yaml \
--rm -it docker.devo.internal/collector/msgraph:<version>

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/msgraph/ directory.

version: '3'
services:
  collector-msgraph:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker.devo.internal/collector/msgraph:${IMAGE_VERSION:-latest}
    container_name: collector-msgraph
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config-msgraph.yaml}

To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/msgraph/ directory:

IMAGE_VERSION=<version> docker-compose up -d