Censys for Microsoft Sentinel Integration

The Censys for Microsoft Sentinel integration adds playbooks to enrich IPs, web properties, and certificates in Microsoft Sentinel with Censys Platform data. These playbooks can be initiated manually or automatically. It also adds playbooks to initiate a Censys rescan of a host or web property, retrieve event history for an IP address, and find assets related to an IP, web property, or certificate. Additionally, it adds a dashboard that shows all actions executed using the app.

This guide walks through how to set up and use the Censys for Microsoft Sentinel application.

Prerequisites

The following list contains prerequisites for setting up this integration. For more information about configuring Microsoft Sentinel, reference Microsoft's documentation.

• An active Azure subscription.
• An Azure resource group with the Microsoft Sentinel Contributor role at the Subscription level.
• A Logs Analytics Workspace with Microsoft Sentinel enabled in your Azure subscription.
• Your Censys Platform organization ID.
  • To obtain your organization ID:

    1. Open the Platform web console and ensure that your organization account is selected. Go to Settings > Account Management > Personal Access Tokens.

    2. The ID for your organization is shown in the "Current Organization" box. Click Copy to copy it to your clipboard.

       
• A Censys Platform Personal Access Token (PAT). Instructions on how to create and manage PATs are available in the API documentation.

Installation and configuration

Retrieve and install the integration from the Microsoft Marketplace.

During the setup process, configure the integration to use your organization ID and PAT.

Configure Censys for Microsoft Sentinel workbook dashboard

After installing the app, you can set up a workbook dashboard that displays a record of app activity as well as a portal for manually executing app actions.

To configure the workbook:

1. Navigate to the Microsoft Sentinel homepage, then go to the workspace that you installed the Censys for Microsoft Sentinel app in.
2. Go to Workbooks > Templates. Search for "censys" and click on the workbook.
3. Click Save and select the location of your Microsoft Sentinel workspace, then click Yes.

You can now click View saved workbook to use the Censys workbook dashboard.

All of the Censys integration's actions can be executed manually from the workbook dashboard.

Censys for Microsoft Sentinel playbooks

The Censys for Microsoft Sentinel application adds the following playbooks. In addition to the CensysAddIncidentComment playbook, you must configure each one you want to use. See more about playbook setup below.

Playbook setup and configuration

To use the playbooks installed by the app, you must:

1. Set up a key vault configuration for the app
2. Enable and configure the Censys Add Incident Comment playbook
3. Authorize the API connection for the Add Incident Comment playbook
4. Assign the Microsoft Sentinel Contributor to your playbook
5. Set up all other playbooks you want to use

1. Set up a key vault configuration for the app

1. In the Azure portal, go to Key vaults and click Create.
2. Select your subscription, resource group, and enter a unique name for the key vault.
3. On the Access configuration tab, under "Permission model," select Vault access policy and add your user access policy.
4. Select your key vault. Go to Objects > Secrets.
5. Click Generate/Import. In the name field, enter Censys-Access-Token. In the value field, enter your PAT.
6. Click Create.

2. Enable and configure the Censys Add Incident Comment playbook

1. In Microsoft Sentinel, go to the workspace that you installed the app in.
2. Go to Automation > Playbook templates.
3. Select the "Censys Add Incident Comment" playbook. Click Create playbook.
4. In the "Basic" tab, select your subscription and resource group.
5. Click Next: Connections.
6. Click Next: Review + Create.
7. Click Create playbook.

3. Authorize API connection for the Censys Add Incident Comment playbook

1. In Microsoft Sentinel, go to Automation > Development Tools > API connections.
2. Select Azureloganalyticsdatacollector-CensysAddIncidentComment and go to General > Edit API connection.
3. Enter the workspace ID and workspace key where your Censys workbook is available and where the data will be ingested.
   • To locate your Workspace ID, go to Log Analytics Workspace > Your workspace > Properties.
   • You can retrieve your workspace key by using the following Azure CLI command. To access Azure CLI, click the shell or command prompt icon in the top-right corner of the Azure portal and paste command below:

     az monitor log-analytics workspace get-shared-keys  --resource-group resource-group-name --workspace-name workspace-name

4. Click Save.
5. Select Azuresentinel-CensysAddIncidentComment API Connection and go to General > Edit API connection.
6. Click Authorize. An Azure Portal login prompt will open. Log in using your Azure Portal credentials.
7. Click Save.

4. Assign role to Censys Add Incident Comment playbook

1. Go to Log Analytics Workspace > [your workspace] > Access Control (IAM).
2. Click Add > Add role assignment.
3. In Assignment type: Job function roles, search for "Microsoft Sentinel Contributor" and click Next.
4. In Members, select Managed identity for assigned access to the Add Incident Comment logic app.
5. Click Select members and add your logic app as a member.
6. Click Review + Assign.

5. Censys Incident Enrichment and all other playbooks setup and configuration

📘

Note

You must complete all steps in this process for each playbook you want to enable. The process documented here uses the Censys Incident Enrichment playbook as an example.

1. Go to the Microsoft Sentinel workspace in which you have installed Censys.
2. Go to Automation > Playbook templates and select the "Censys Incident Enrichment" playbook.
3. Click Create playbook.
4. On the "Basic" tab, select your subscription and resource group and click Next: Parameters.
5. On the "Parameters" tab, provide the following:
   • Ports: comma separated port numbers for web property enrichment. (eg: 80,443) (default: 80,443).
   • Organization ID: Your Censys organization ID.
   • IncidentEnrichmentPlaybookName: The name of your "CensysAddIncidentComment" playbook, such as CensysAddIncidentComment.
   • KeyVaultName: Azure KeyVault Name where your Censys PAT is stored.
   • TenantId: The Tenant ID of the Azure account. To retrieve your tenant ID, go to Key Vaults > Your Key Vault and select Directory ID.
6. Click Next: Connections.
7. Click Next: Review+Create.
8. Click Create playbook.

Add API connections for the playbook

1. In Microsoft Sentinel, go to Automation > Development Tools > API connections.
2. Click Keyvault-CensysIncidentEnrichment and go to Edit API connection.
3. Click Authorize. An Azure Portal login prompt will open. Log in using your Azure Portal credentials.
4. After successfully authenticating, click Save.
5. Complete this authorization process for each API connection.

Add access policy in key vault

Add access policy for the playbook's managed identity and authorized user to read and write secrets of the key vault.

1. Go to Logic App > [your Logic App] > Settings > Identity > System assigned Managed identity and copy the Object (principal) ID.
2. Make sure that the Status is set to On.
3. Go to Key Vaults > [your key vault] > Access policies > Create.
4. Select all keys & secrets permissions, then click Next.
5. In the principal section, search by the object ID you coped, then click Next.
6. Click Review + Create.

Repeat steps 2 to 5 to add the access policy for each connection.

Assign role to playbook

1. Go to Log Analytics Workspace > [your workspace] > Access Control (IAM).
2. Click Add > Add role assignment.
3. In Assignment type: Job function roles, search for "Microsoft Sentinel Contributor" and click Next.
4. Next to Assign access to, select Managed identity for assigned access to the logic app.
5. Click Select members.
6. Select your subscription, under Managed identity, select Logic app, and select the desired Censys playbook.
7. Click Review + Assign.

Manually run Censys playbooks on incidents or incident entities

After you set up and configure Censys playbooks, you can manually initiate them on incidents or incident entities.

To run a playbook on an incident:

1. Go to Microsoft Sentinel > [your workspace] > Incidents.
2. Select an incident.
3. In the right pane, click Actions. In the dropdown, select Run playbook.
4. Next to the entry for CensysIncidentEnrichment, click Run.

To run a playbook on an incident entity:

1. Go to Microsoft Sentinel > [your workspace] > Incidents.
2. Select an incident.
3. In the right pane, click View full details. Go to the Entities tab.
4. Click ... on an entity entry, then select Run playbook.
5. In the list of playbooks, select the appropriate playbook based on the entity type.
   • For EntityType IP, select CensyEntityEnrichmentHost.
   • For EntityType DNSDomain, select CensysEntityEnrichmentWebProperty.
   • For EntityType FileHash, select CensysEntityEnrichmentCertificate.
6. Click Run.

Set up automation rules with Censys actions

Follow the Microsoft Sentinel documentation to set up an automation rule. When you configure an automation rule to run an action, you can select any Censys playbook added by the app that you have configured.

Related infrastructure playbook

📘

Note

These actions and the playbook are only available to Censys users with access to the Adversary Investigation module.

Use the related infrastructure playbook to discover and map suspicious or malicious internet-facing assets that share parsed Censys data key-value pairs. The playbook leverages the CensEye automated pivoting tool.

Each row of the output table is a Censys data key-value pair or group of key-value pairs, the count of assets in the Censys Internet Map that share that pair or group, and a link to see all assets that feature the pair in the Censys Platform.