Configuring the Microsoft Defender Scanner Connector

As an administrator, you can configure different types of scanners to scan security risks and vulnerabilities across your IT infrastructure. 

Microsoft Defender (MS Defender) is a comprehensive vulnerability management solution that provides complete visibility of the security risks across your IT infrastructure. With this integration, you can retrieve the vulnerability scan results from multiple MS Defender instances and process the vulnerabilities to map the remediation content. You can then create operations to remediate vulnerabilities. 

After you configure and run this connector, the scan files that contain the MS Defender assets and vulnerabilities are automatically imported into Automation Console.

Before you begin

Review the following prerequisites that help you plan and configure a connection with MS Defender:

MS Defender prerequisites

The following are the minimum requirements for MS Defender:

• Make sure that you have a valid MS Defender license.
• Register an application.
  The following information is displayed:
  • Client ID
  • Tenant ID
• Register the client secret.
• Grant Admin permissions to the following APIs:
  • Microsoft Graph
    • ThreatHunting.Read.All
  • WindowsDefenderAPT
    • Machine.Read.All
    • Vulnerability.Read.All

For more information, see the Microsoft identity platform documentation.

BMC Helix Automation Console prerequisites

• Make sure one or more configured Microsoft Defender instances are running in your environment.
• Minimum configuration requirements for the connector's virtual machine:
  • A stable Windows or Linux operating system
  • Minimum RAM: 4GB RAM
  • Number of core-CPUs: 2
  • Hard disk storage: 40 GB
• Install and run the connector on Windows or Linux operating systems based on the following criteria:
  • AdoptOpenJDK Runtime Environment 17 is installed on the connector host.
  • Port requirements:

    Port	Protocol	From	To	Notes
    443	HTTPS	Connector	HAC SaaS and Internet	Outbound
    443 OR <Customer configured port>	HTTPS	Connector	Microsoft Defender Server	Outbound
    443	HTTPS	Microsoft Defender Server	Connector	Inbound

  • Connector's Outbound port 443 should be opened for ifm url specified in the creds.json file available in the <connectorDirectory>/config/ folder. For example, 

    "endpoints": {        "ifm": "https://<url>"
        }

To configure the Microsoft Defender scanner connector

1. In BMC Helix Automation Console, click Configuration and then click Connectors.
2. On the Manage Connectors page, click Add Connector.
3. On the Add Connector page, from the list of available Connector types, select Scanner Connector.
4. Click Add Configuration.
5. On the Add configuration page, provide the following details:
   1. In the Vendor field, select Microsoft from the list.
   2. In the Connector details section, provide the following information:
      1. In the Configuration Name field, specify a unique name which is assigned to the scan files imported into Automation Console.
      2. (Optional) In the Configuration Description field, provide a description of the connector.
      3. In the Roles field, specify one or more roles in a comma-separated list that can access the scan results.
         If you do not specify a role, all roles can access the scan files imported from Microsoft Defender.
         Information

         Important

         If you have configured both TrueSight Server Automation and TrueSight Network Automation endpoint managers, specify the name of the appropriate role. If you specify a role, BMC Helix Automation Console does not fetch any data from Microsoft Defender.

   3. In the Connector Configuration section, perform the following steps:
      1. Select the Cloud Environment: Select the cloud type according to your security requirements
         • Public
         • GCC: Government Community Cloud
         • GCC High: Government Community Cloud High
         • DoD: Department of Defense
      2. (Optional) Enter the Custom API URL: If you have created a custom domain with the tenant ID
      3. (Optional) Enter the Custom OAuth Scope: The URL that is generated when you define a role-based scope in Azure and assign it to users
   4. In the Authentication Details section, perform the following steps:
      1. Enter the Tenant ID set: The Organization ID created in Azure for the tenant
      2. Enter the Client ID set: The Application ID created in Azure for your account with Microsoft
      3. Enter the Client Secret: The secret key used for authentication when you request a token in Azure
   5. In the Filters section, provide values to fetch the specific scanned data:
      1. In the Severity field, select the required values for the Severity level of the vulnerabilities.
      2. In the NetworkIPv4 field, enter either an IP range such as [192.168.10.100 - 192.168.10.200] or a single Network IP such as 192.168.1.100, to fetch more precise data. You cannot enter multiple Network IP addresses as comma-separated values.
      3. In the Additional Filters field, enter the required asset level values for the following filter categories:
         • OS Platform
         • Device tags
           • Manual tags
           • Dynamic tags
         • Exposure levels
   6. (Optional) In the Auto-close vulnerabilities section, select the Enable Auto-close check box to enable the system to automatically close vulnerabilities that were fixed in the previous scan and are no longer present in the subsequent scan.
6. Click Save.
   The newly added configuration is listed in the Configurations table.
7. (Optional) Repeat steps 4 to 6 to have multiple configurations of the MS Defender instance, with different filters specified for each configuration.
8. On the Manage Connectors page, in the Configuration Schedule section, specify a frequency at which you want to run the connector, and save the schedule.
   Information

   Important

   If you enable auto-close, then the schedule should be less than 13 days.

9. Click Continue and download the connector zip file on a local host. 
10. From the connector location on the server where the connector file is downloaded and extracted, run the following command to install and start the connector:
    • Windows: run.bat
    • Linux: run.sh 
      You can view the connector status on the Connectors page.
11. (Optional) To configure the Scanner connector as a service, perform the following steps:
    1. Make sure the scanner-connector.xml file is available in a folder where the connector zip file is unzipped.
    2. Run the scanner-connector.exe install command. 
    3. A new service named BMC Scanner Connector is created on the host and can be used as any other available service.
       Information

       Important

       The minimum duration for data collection between the consecutive schedules is 10 minutes.

       Vulnerability scan files are created with the specified configuration names. BMC Helix Automation Console processes each configuration sequentially.

To update the connector

1. On the Manage Connectors page, click Action against the Scanner connector and then click Disable.
2. Click Action against the Scanner connector and then click Edit.
   The available configurations are displayed.
3. To quickly locate the required configuration, search or sort the configurations by the various columns, such as Status and Vendor.
4. Edit the information according to your requirements and click Update. 

To enable debug mode

1. If the connector is already running, press CTRL+C twice to stop the connector.

2. Navigate to <ConnectorLocation>/config, open the application.properties file, add the following parameter, and set it to debug:

   #
   #Logging related Properties
   logging.level.com.bmc.truesight.scannerconnector=debug
3. Save the file.
4. Restart the connector.

Troubleshooting

If data retrieval from Microsoft Defender fails, the Connector tile on the Manage Connectors page displays the configuration name with error messages. The related exceptions are logged in the log file. For troubleshooting issues, see Troubleshooting connectors.