Versions Compared

Old Version 23

changes.mady.by.user Former user

Saved on

compared with

New Version 24

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
typeflat

...

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

  1. Go to Azure portal and click on Azure Active Directory.

  2. Click on App registration on the left-menu side. Then click on + New registration.

  3. On the Register and Application page:

    1. Name the application.

    2. Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) in Supported Accounts type.

    3. In Redirect URI (optional) leave it as default (blank).

    4. Click Register.

  4. 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.

  5. Click Authentication on the left-menu side, then choose + Add a platform and select Mobile and desktop application.

  6. Select the three redirects URIs:

    • https://login.microsoftonline.com/common/oauth2/nativeclient

    • https://login.live.com/oauth20_desktop.srf

    • msale36f3a02-3eef-437b-874e-8a0aa29a2bf0://auth

  7. Click Configure.

2

Grant the required permissions

  1. Go to API permissions on the left-menu side.

  2. Click + Add permission in case you don’t have Microsoft Graph in the API/Permission list.

  3. Select Application permissions and search for Security. Check SecurityEvents.Read.All.

  4. Repeat the same step 3 for AuditLog.Read.All,Directory.Read.All and User.Read. If you did everything correctly, permissions will display.

  5. 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

  1. Go to Certificates & Secrets, select + New client secret . Named it and copy the token value.

  2. 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
titleOn-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:

Code Block
<any_directory>
└── devo-collectors/
    └── <product_name>/
        ├── certs/
        │   ├── chain.crt
        │   ├── <your_domain>.key
        │   └── <your_domain>.crt
        ├── state/
        └── config/ 
            └── config.yaml
Note

Replace <product_name> with the proper value.

Devo credentials

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.

Note

Replace <product_name> with the proper value.

Editing the config.yaml file

Code Block
globals:
  debug: false
  id: <short_unique_id>
  name: microsoft_graph
  persistence:
    type: filesystem
    config:
      directory_name: state
outputs:
  devo_1:
    type: devo_platform
    config:
      address: collector-us.devo.io
#      address: collector-eu.devo.io
      port: 443
      type: SSL
      chain: chain.crt
      cert: <devo_domain.crt>
      key: <devo_domain.key>
inputs:
  microsoft_graph:
    id: 1
    enabled: true
    request_per_second: 5
    credentials:
      tenant_id: <tenant_id_value>
      client_id: <client_id_value>
      client_secret: <client_secret_value>
    services:
      audit:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      provisioning:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      signIn:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      signIn_nonInteractive:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      signIn_servicePrincipal:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      signIn_managedIdentity:
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      secure_score_control_profile:
        tag_version: v2
        request_period_in_seconds: <request_period_in_seconds_value>
        start_time: <start_time_value>
      alerts:
        tag_version: v2
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
      secure_scores:
        tag_version: v2
        request_period_in_seconds: <request_period_in_seconds_value>
        reset_persistence_auth: <reset_persistence_auth_value>
        start_time: <start_time_value>
Info

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.

The detailed table destination depending on the tag_version's value is available in the Devo categorization and destination section.

Info

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:

Collector Docker image

SHA-256 hash

collector-ms-graph-collector-if-docker-image-1.4.01

85b0bf43a7c5eb31874f7c6bc24811ec28a9e3e72ffb26a69ff6bf2452b236bf275474aa932a2aa63983bdbde26fef3fe2194d7375ac1a4264b732a8efdc2b7d

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

Code Block
gunzip -c <collector-ms-graph-collector-if-docker-image>-<1.2.0>.tgz | docker load
Note

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>/

Code Block
docker run 
--name collector-<product_name> 
--volume $PWD/certs:/devo-collector/certs 
--volume $PWD/config:/devo-collector/config 
--volume $PWD/state:/devo-collector/state 
--env CONFIG_FILE=config.yaml 
--rm 
--interactive 
--tty 
<image_name>:<version>
Note

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.

Code Block
version: '3'
services:
  collector-<product_name>:
    image: <image_name>:${IMAGE_VERSION:-latest}
    container_name: collector-<product_name>
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./credentials:/devo-collector/credentials
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config.yaml}

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
titleCloud 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.

...

Expand
titleTroubleshooting

This collector has different security layers that detect both an invalid configuration and abnormal operation. This table will help you detect and resolve the most common errors.

Common for all services

Error type

Error ID

Error message

Cause

Solution

MicrosoftGraphPullerCredentialsException

1

Invalid tenant. This may happen if there are no active subscriptions for the tenant

The tenant is not valid according to Microsoft AD. Probably, the setup has not been correctly followed.

Revisit the setup instructions and check that all the steps have been correctly followed.

1

Access Token validation has been failed, code: {status_code}, text: {text_str}

There was a problem obtaining the authentication token.

Read the exact error to understand what is the real cause.

2

Access Token not valid or client_id does not exist

There was an unknown problem during the authentication..

Check that the credentials have been correctly set up.

MicrosoftGraphPullerCreationException
ModuleDefinitionError

1

"module_properties" property in service definition must exists / "module_properties" mandatory property is missing or empty

This a programming error that we should not except to happen.

Contact Devo Support.

2

"module_properties" property in service definition must be a dictionary

This a programming error that we should not except to happen.

Contact Devo Support.

3

"resource_type" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

4

"resource_type" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

5

"base_url_main" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

6

"base_url_main" property in service definition must be a string.

This a programming error that we should not except to happen.

Contact Devo Support.

7

"base_url_vendor" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

8

"base_url_vendor" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

9

"tag_base" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

10

"tag_base" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

11

"http_status_valid_codes" property in service definition must exists.

This a programming error that we should not except to happen.

Contact Devo Support.

12

"http_status_valid_codes" property in service definition must be a list

This a programming error that we should not except to happen.

Contact Devo Support.

13

"login_url" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

14

"login_url" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

15

"scope" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

16

"scope" property in service definition must be a string.

This a programming error that we should not except to happen.

Contact Devo Support.

MicrosoftGraphPullerCreationException

37

"tag_version" property for {service_name} from configuration file is not valid, expected: v1, v2 or None

This configuration parameter expects a string with value v1, v2 or null but it has parsed a different type of value.

Ensure that the value for this parameter is a string with value v1, v2 or null.

MicrosoftGraphPullerRetrieveException

1

Not defined "next_page_url"

When retrieving data from the MS Graph API, we expect that each paginated response has a next_page_url property in its JSON. This error occurs when this property was not found.

Enable debug mode and inspect the requested URLs. Try to replicate those to see the response obtained.

2

Response text: "{response_text}", HTTP error: {http_error}

When retrieving data from the MS Graph API, we expect that the response code is within the [200-400) range; otherwise (HTTP response code ≥ 400), it will raise this error.

The error will include the response’s text. This should tell you what the problem is. The solution will depend on the type of the problem.

MicrosoftGraphPullerConnectionException

3

Operation timed out: {error_message}

When retrieving data from the MS Graph API, the server took too long to respond and the connection was closed.

Check your network connection and that the MS Graph API is operative.

4

Connection error detected: {error_message}

Some other error regarding the connection with the MS Graph API server occurred.

You should read the actual error message to understand the underlying issue and know how to solve it.

MicrosoftGraphPullerRetrieveException

5

{error_message}

Some unknown error occurred.

You should read the actual error message to understand the underlying issue and know how to solve it.

Non-time-base services (secure_score_control_profiles)

Error type

Error ID

Error message

Cause

Solution

MicrosoftGraphPullerCreationException

17

"request_max_items_per_request" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

18

"request_max_items_per_request" property in service definition must be an intege

This a programming error that we should not except to happen.

Contact Devo Support.

19

"requests_per_minute" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

20

"requests_per_minute" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

21

"requests_per_minute" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

22

"requests_per_minute" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

23

"new_service_name" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

27

"tag" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

28

"credentials" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

29

"credentials" property in configuration must be a dictionary

This configuration parameter expects a JSON object value, but it has parsed a different type of value.

Ensure that the value for this parameter is a JSON object.

30

"tenant_id" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

31

"tenant_id" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

32

"client_id" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

33

"client_id" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

34

"client_secret" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

35

"client_secret" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

Time-based (alerts, secure_scores) & audit (audit, provisioning, signIn, signIn_nonInteractive, signIn_servicePrincipal, signIn_managedIdentity) services

Error Type

Error ID

Error Message

Cause

Solution

ModuleDefinitionError

5

"base_url_main_only_first_page" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

6

"base_url_main_only_first_page" property in service definition must be a boolean

This a programming error that we should not except to happen.

Contact Devo Support.

7

"base_url_vendor_with_sub_provider" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

8

"base_url_vendor_with_sub_provider" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

17

"base_url_main_items_per_request" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

18

"base_url_main_items_per_request" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

19

"base_url_main_items_per_request" property in service definition must be a positive value

This a programming error that we should not except to happen.

Contact Devo Support.

17

"base_url_vendor_items_per_request" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

18

"base_url_vendor_items_per_request" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

19

"base_url_vendor_items_per_request" property in service definition must be a positive value

This a programming error that we should not except to happen.

Contact Devo Support.

20

"max_result_set_size" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

21

"max_result_set_size" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

22

"max_result_set_size" property in service definition must be a positive value

This a programming error that we should not except to happen.

Contact Devo Support.

24

"legacy_provider_mapping_old_new" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

25

"requests_per_minute" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

26

"requests_per_minute" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

27

"requests_per_minute" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

28

"requests_per_minute" property in service definition must be an integer

This a programming error that we should not except to happen.

Contact Devo Support.

29

"timestamp_field" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

30

"timestamp_field" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

31

"start_time_regex" property in service definition must exists

This a programming error that we should not except to happen.

Contact Devo Support.

32

"start_time_regex" property in service definition must be a string

This a programming error that we should not except to happen.

Contact Devo Support.

InputConfigurationError

1

"microsoft_graph" mandatory property is missing or empty

The input configuration is missing.

Ensure that the configuration includes an input configuration.

2

"microsoft_graph" property must be a dictionary

The input configuration expects to have a JSON object value, but it has parsed a different type of value.

Ensure that the configuration for this input is a JSON object.

3

"credentials" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

4

"credentials" property in configuration must be a dictionary

This configuration parameter expects a JSON object value, but it has parsed a different type of value.

Ensure that the value for this parameter is a JSON object.

5

"tenant_id" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

6

"tenant_id" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

7

"client_id" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

8

"client_id" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

9

"client_secret" property in configuration must exists

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

10

"client_secret" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

ServiceConfigurationError

1

"{service_name}" mandatory property is missing or empty

This configuration parameter is missing.

Ensure that this parameter is present and has a value.

ServiceConfigurationError

2

"{service_name}" property must be a dictionary

This configuration parameter expects a JSON object value, but it has parsed a different type of value.

Ensure that the value for this parameter is a JSON object.

MicrosoftGraphPullerCreationException

27

"tag" property in configuration must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

36

"start_time" property in service definition must be a string

This configuration parameter expects a string value, but it has parsed a different type of value.

Ensure that the value for this parameter is a string.

37

"start_time" property from configuration file format is not valid, expected: "{start_time_regex}"

This configuration parameter expects a date that matches the indicated regular expression, but it did not match.

Ensure that the value for this parameter is a valid date according to the indicated regular expression.

38

"tag_version" property for {self.service_name} from configuration file is not valid, received "v2", but there is no "tag_base_v2" property in module definitions

You set the tag_version parameter to v2, but the service does not have a v2 tagging.

Contact Devo Support.

Collector operations

This section is intended to explain how to proceed with specific operations of this collector.

...

Release

Released on

Release type

Details

Recommendations

v1.2.0

Status
colourPurple
titleNEW FEATURE

Status
colourGreen
titleIMPROVEMENT

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.

Upgrade

v1.3.0

Status
colourGreen
titleIMPROVEMENT

Status
colourRed
titleBUG FIX

Improvements:

  • start_time configuration parameter normalization for audit and provisioning services.

  • Upgraded devocollectorsdk from 1.4.0 to 1.4.4b:

    • Added:

      • New "templates" functionality.

      • New controlled stopping condition when any input thread fatally fails.

      • Log traces for knowing the execution environment status (debug mode).

    • Changed:

      • Improved log trace details when runtime exceptions happen

      • Refactored source code structure

      • Fixes in the current puller template version

      • The Docker container exits with the proper error code

Bug fixing:

  • Correct token validation when a Partial Content response is received.

  • Use appropriate destination tag for provisioning events.

Upgrade

v1.4.0

Status
colourGreen
titleIMPROVEMENT

Improvements:

  • Automatic outdated start_time correction for audit-based services.

  • New “reset persistence” functionality.

Recommended version

v1.4.1

Dec 2, 2022

Status
colourRed
titleBUG FIX

Fixed bugs:

  • Fix error with vendor state when checking the reset_persistence_auth parameter.

  • Allow using v2 tags for secure_scores and secure_scores_control_profile tags.

  • Add missing Devo metadata into events.

Recommended version