Merge pull request #1317 from DebLanger/US302646_3P_Main

Us302646 3 p main

Author: DebLanger

exposure-management/Qualys-data-connector.md

@@ -0,0 +1,75 @@
+---
+title: Integrate Qualys data connector in Microsoft Security Exposure Management
+description: Learn how to the Qualys data connector in Microsoft Security Exposure Management.
+ms.author: dlanger
+author: dlanger
+manager: rayne-wiselman
+ms.topic: overview
+ms.service: exposure-management
+ms.date: 09/24/2024
+---
+
+# Qualys data connector
+
+To integrate with Qualys, you have to provide basic credentials for a Qualys user with **Manager** role or a **Reader** role with full scope.
+
+## Qualys configuration
+
+1. To set up the Qualys integration, you need the API_URL of your Qualys instance, such as “qualysapi.qg1.apps.qualys.co.uk”. You can find it [here](https://www.qualys.com/platform-identification/).
+   1. If you can't find it:
+      1. Log in to your Qualys account.
+      2. Go to **Help** → **About**.
+      3. You'll see the required information under **Security Operations Center** (SOC).
+1. You'll need credentials of a user with at least **Read Asset** permissions to successfully retrieve data from the connector. To create a user with a Read Asset role:
+   1. Log in to Qualys.
+   2. Go to **Administration** area.
+   3. Go to the **Role Management** section.
+   4. Select New Role.
+   5. Provide a role name, for example, "Read Asset".
+   6. For the Role permissions, check API Access.
+   7. From the **Modules** drop down, choose Asset View.
+   8. To limit the permissions, choose the **Change** option within the **Asset View** selected module.
+   9. Make sure to enable, at least, **Read Asset** under **Asset Management Permissions**.
+1. Add the newly created role to the user you intend to authenticate with in the Exposure Management Qualys Connector.
+   1. Under **Administration** go to **User** **Management**.
+   2. Select the user you onboarded with the Exposure Management Qualys Connector and choose **Edit**.
+   3. Under **Roles and Scopes**, add the Read Asset role created in previous sections to the user assigned roles.
+   4. Under **Edit** scope, select **Allow user view access to all objects** to allow this user full scope.
+   5. Save the **Read Asset** role assignment to the user.
+
+## Establish Qualys connection in Exposure Management
+
+To establish a connection with Qualys in Exposure Management, follow these steps:
+
+1. Open the [Data Connectors](https://security.microsoft.com/exposure-data-connectors) from the Exposure Management navigation and select **Connect** in the Qualys tile.
+1. Enter your Qualys API URL and authentication credentials and select **Connect**.
+
+## Retrieved data
+
+Qualys connector retrieves data on compute devices, including machines and virtual machines, and vulnerability findings from Qualys on those assets. It also retrieves some networking data to identify those devices.
+
+Only devices that were modified in the last 90 days are retrieved, based on assessing the "modified" field in the Qualys asset.
+
+| **Category**            | **Properties**                                                                 |
+|-------------------------|--------------------------------------------------------------------------------|
+| **Assets/devices**      | - Gateway address<br>- FQDN<br>- IP address<br>- MAC address<br>- OS information<br>- Qualys criticality data |
+| **Vulnerability findings** | Qualys retrieves CVE findings on the assets that it ingests.                    |
+
+## Troubleshooting the Qualys data connector
+
+Here are some common issues that might arise when configuring the Qualys Connector, and suggestions for how to resolve them.
+
+| **Error Type**                                               | **Troubleshooting Action**                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| **Error code** 401: Authorization failure                    | An authorization failure indicates that credentials might not be correct, or there might not be sufficient permissions to access the Qualys data. Check your credentials and make sure they're correct and valid. Also check that your credentials have the required permissions. See the Qualys [configuration section](#qualys-configuration) for details on how to assign the appropriate role and scope. <br>You can validate your user credentials by running the following:<br>curl -u "user:password" -H "X-Requested-With: Curl" -X "POST"-d "action=list" "[https://qualysapi.qg1.apps.qualys.ca/qps/rest/2.0/search/am/hostasset](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fqualysapi.qg1.apps.qualys.ca%2Fqps%2Frest%2F2.0%2Fsearch%2Fam%2Fhostasset&data=05\|02\|[email protected]\|16df3effc63244b6236808dcfe9c61d1\|72f988bf86f141af91ab2d7cd011db47\|1\|0\|638665194889139624\|Unknown\|TWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D\|0\|\|\|&sdata=cnChKl0R%2BvXdnHEyWXwtokJXLWfJTBEkZksbJEvqiqA%3D&reserved=0)" >output.txt |
+| **Error code** 409: Possible insufficient permissions        | Qualys connector utilizes the knowledge_base API which requires specific permissions. You can see more details in the KnowledgeBase section of [this Qualys API document](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcdn2.qualys.com%2Fdocs%2Fqualys-api-vmpc-user-guide.pdf&data=05\|02\|[email protected]\|16df3effc63244b6236808dcfe9c61d1\|72f988bf86f141af91ab2d7cd011db47\|1\|0\|638665194889160705\|Unknown\|TWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D\|0\|\|\|&sdata=6VlESEXXIudzrf3WFAqAqXu775Q72%2FynZxGt75W0%2BVk%3D&reserved=0). <br>To validate the provided user has sufficient permissions, run the following command and verify it succeeds:<br>curl -u "user:password" -H "X-Requested-With: Curl" -X "POST"-d "action=list""[https://qualysapi.qg1.apps.qualys.ca/api/2.0/fo/knowledge_base/vuln/](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fqualysapi.qg1.apps.qualys.ca%2Fapi%2F2.0%2Ffo%2Fknowledge_base%2Fvuln%2F&data=05\|02\|[email protected]\|16df3effc63244b6236808dcfe9c61d1\|72f988bf86f141af91ab2d7cd011db47\|1\|0\|638665194889173173\|Unknown\|TWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D\|0\|\|\|&sdata=g8%2BzcLq3rI%2B2%2F6ii9WNiyKBsHzGU7vQPfMKT232C5f4%3D&reserved=0)" >output.txt <br>In case it fails, refer to Qualys documentation to mitigate. |
+| **Error code 403:** Access forbidden error                   | This error indicates that the provided credentials lack the necessary permissions to run the requested APIs. Update your credentials with the proper permissions as described in the [configuration section](#qualys-configuration), and make sure they have at minimum the Read Asset permissions. |
+| **Error code 404:** Not found error                          | This error indicates that the requested endpoint wasn't found to be reachable. Verify that your Qualys API endpoint is correct, see the [configuration section](#qualys-configuration) for details. |
+| **Error code 429** 'Too many requests"                       | The system periodically pulls data from the configured external providers, which might have a limit on the number of concurrent requests. We recommend creating a dedicated user or account for the connector to avoid reaching this limit. |
+| 'Temporary disconnected' or 'Temporary failure' error message | In the case where this error message appears without any additional information, verify the connector configuration (API endpoint and credentials). If these are valid and the issue doesn't resolve on its own, contact Support. |
+| Not seeing my assets or the vulnerabilities reported by Qualys in the ingested data | See [Retrieved data](#retrieved-data) for a description of the data expected to be retrieved by the Qualys connector. If there's still missing data, contact Support. |
+| Qualys allowed IPs need to be configured to enable Exposure Management connectors to access Qualys | Read how to add the set of IPs to add to your allowlist here: [Allowlist IP addresses](configure-data-connectors.md#allowlist-ip-addresses). |
+
+## Next steps
+
+[Getting value from your data connectors](value-data-connectors.md).

exposure-management/Rapid7-data-connector.md

@@ -0,0 +1,57 @@
+---
+title: Integrate Rapid7 data connector in Microsoft Security Exposure Management
+description: Learn how to the Rapid7 data connector in Microsoft Security Exposure Management.
+ms.author: dlanger
+author: dlanger
+manager: rayne-wiselman
+ms.topic: overview
+ms.service: exposure-management
+ms.date: 11/06/2024
+---
+
+# Rapid7 data connector
+
+To set up the Rapid7 integration, you need the endpoint of your Rapid7 Platform API, such as “us.api.insight.rapid7.com”. The connector authenticates with API Key Auth using an Endpoint and API Key.
+
+## Rapid7 configuration
+
+1. **Endpoint** - Find your Rapid7 endpoint. Follow the instructions [here](https://docs.rapid7.com/insight/api-overview#endpoint )
+2. **API Key** – This integration needs a user API key for a user that has permissions to fetch assets. To generate an API key, see details at [this link.](https://docs.rapid7.com/insight/managing-platform-api-keys/#api-keys-based-on-your-insight-account-role)
+
+   > **Note:** *We have found that connecting with an organization key has been more successful than connecting with a user key. We recommend you opt for an organization key to increase the likelihood of a successful connection.*
+
+## Establish Rapid7 connection in Exposure Management
+
+To establish a connection with Rapid7 in Exposure Management, follow these steps:
+
+1. Open the [Data Connectors](https://security.microsoft.com/exposure-data-connectors) from the Exposure Management navigation and select **Connect** in the Rapid7 tile.
+1. Enter your Rapid7 Endpoint and API key details and select **Connect**.
+
+## Retrieved data
+
+Exposure Management retrieves data on compute devices from Rapid7, including machines and virtual machines. It also retrieves vulnerabilities reported by Rapid7 on those devices.
+
+Only devices that were actively scanned in the last 90 days are retrieved, based on assessing the "last_scan_end" field in the Rapid7 asset.
+
+| Category               | Properties                                                                 |
+|------------------------|----------------------------------------------------------------------------|
+| **Assets/devices, and data per each identifier** | - Rapid7 ID<br>- Hostname<br>- IP address<br>- mac Address<br>- OS information<br>- Rapid7 risk score<br>- Tags<br>- Rapid7 criticality data<br>- Cloud platform |
+| **Vulnerability findings** | Rapid7 retrieves CVE findings on the assets that it ingests.             |
+
+## Troubleshooting the Rapid7 data connector
+
+Here are some common issues that might arise when configuring the Rapid7 Connector, and suggestions for how to resolve them.
+
+| **Error Type**                                                    | **Troubleshooting Action**                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| 'The remote server name couldn't be resolved' error message | Verify the Rapid7 endpoint. Learn more about how to determine your Rapid7 API endpoint [here](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.rapid7.com%2Finsight%2Fapi-overview%23endpoint&data=05\|02\|[email protected]\|16df3effc63244b6236808dcfe9c61d1\|72f988bf86f141af91ab2d7cd011db47\|1\|0\|638665194889184920\|Unknown\|TWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D\|0\|\|\|&sdata=s1lGW1eKqmNLGqe%2FNxbMZvszhRwRzGM6AD6Gv0w26IU%3D&reserved=0). |
+| **Error code 401**: Authorization failure                    | An authorization failure indicates that credentials might not be correct, or there might not be sufficient permissions to access the Rapid7 data. Check your API key and verify that it's valid, and that the account isn't locked. In some cases, we have found that using an organization key works more successfully than generating a user key. <br>Try testing the connection with an organization key. You can test your credentials by running the following commands:<br>`curl -l --request POST --location 'https://\<region\>.api.insight.rapid7.com/vm/v4/integration/assets?size=2&includeSame=true' --header 'X-API-Key:\<key\>' --header 'Content-Type: application/json' –header ‘Accept: application/json’`<br> `curl -l --request POST --location 'https://\<region\>.api.insight.rapid7.com/vm/v4/integration/vulnerabilities?size=2’ --header 'X-API-Key:\<key\>' --header 'Content-Type: application/json' –header ‘Accept: application/json’`<br>If these fail and describe the error, refer to the Rapid7 documentation to mitigate. |
+| **Error code 403:** Access forbidden error                   | This error indicates that the provided credentials lack the necessary permissions to run the requested APIs. Ensure that your API key is generated with a user that has sufficient permissions to access the Rapid7 data. |
+| **Error code 404:** Not found error                          | This error indicates that the requested endpoint wasn't found to be reachable. Verify that your Rapid7 endpoint is correct. Learn more about how to determine your Rapid7 API endpoint [here](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.rapid7.com%2Finsight%2Fapi-overview%23endpoint&data=05\|02\|[email protected]\|16df3effc63244b6236808dcfe9c61d1\|72f988bf86f141af91ab2d7cd011db47\|1\|0\|638665194889196555\|Unknown\|TWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D\|0\|\|\|&sdata=2aWPJYDlYwjkR6RFf3hrzT0daw%2BmFGE53W4rLf3zpY8%3D&reserved=0). |
+| 'Temporary connectivity issues' error message                | Check the configuration details (endpoint URL and API Key) and make sure they're valid. Review the Rapid7 the [configuration section](#rapid7-configuration) for details. |
+| Not seeing my assets or the vulnerabilities reported by Rapid7 in the ingested data | See [Retrieved data](#retrieved-data) for a description of the expected data to be retrieved by the Rapid7 connector. If there's still missing data, contact Support. |
+| Rapid7 allowed IPs need to be configured to enable Exposure Management connectors to access Rapid7 | Read how to add the set of IPs to add to your allowlist here: [Allowlist IP addresses](configure-data-connectors.md#allowlist-ip-addresses). |
+
+## Next steps
+
+[Getting value from your data connectors](value-data-connectors.md).