Cisco Umbrella

FortiSIEM Support Added: 6.3.2

FortiSIEM Last Modification: 6.7.x

Vendor: Cisco

Product Information: https://umbrella.cisco.com/

There are two methods to ingest Cisco Umbrella audit log data:

• Cisco Umbrella publishing logs to an S3 bucket (either Cisco Managed or Customer managed), and FortiSIEM ingests that data.

• Cisco Umbrella Reporting and Management API polling

The method for ingestion via S3 buckets is recommended for high EPS environments.

The method for reporting and management API ingest is an alternative way to ingest the same data using the activity API and users list API.

This feature utilizes the new Generic HTTPS poller in FortiSIEM 6.6.0 and later. It is a demonstrative example of a no-code integration into Cisco Umbrella.

You can follow the Generic Log API Poller (HTTPS Advanced) Integration documentation here on creating your own logging API integrations for other endpoints that provide interesting data to ingest for auditing purposes.

See Configuration for steps on the two methods to ingest Cisco Umbrella audit log data.

• What is Discovered and Monitored

• Configuration

• Sample Events

What is Discovered and Monitored

The following protocols are used to discover and monitor various aspects of Cisco Umbrella.

Protocol	Metrics Collected	Used For
AWS S3 Bucket API	DNS logs, Proxy logs, IP logs, Admin Audit logs	Security Monitoring

Configuration

The following Configuration Options are available:

• Configuring Cisco Umbrella API Endpoints using Generic HTTPS Poller

  • Set up Cisco Umbrella Reporting API - Activity (all) in FortiSIEM

  • Set up Cisco Umbrella Management API - List Users API in FortiSIEM

• Configuration via Amazon S3

Configuring Cisco Umbrella API Endpoints using Generic HTTPS Poller

This integration uses pre-built definition files for specific Cisco Umbrella API endpoints using the HTTPS Advanced credential type. There are two examples provided. One with the Cisco Umbrella Reporting API, and another with the Cisco Umbrella Management API.

Set up Cisco Umbrella Reporting API - Activity (all) in FortiSIEM -- GET https://api.umbrella.com/reports/v2/activity

• Configuring Cisco Umbrella Reporting JSON API

• Configuring FortiSIEM for Umbrella Reporting API

Set up Cisco Umbrella Management API - List Users API in FortiSIEM -- GET https://api.umbrella.com/admin/v2/users

• Configuring Cisco Umbrella Management JSON API

• Configuring FortiSIEM for Cisco Umbrella Management API

Set up Cisco Umbrella Reporting API - Activity (all) in FortiSIEM

Configuring Cisco Umbrella Reporting JSON API

To configure the Cisco Umbrella Activity API Reporting, you must set up the Cisco Umbrella Reporting API credentials.

Take the following steps.

Set up Cisco Umbrella Reporting API Credentials

1. Login to https://login.umbrella.com/.

2. Navigate to Admin > API Keys.

3. Select Umbrella Reporting or click New API Key.

   1. Under Key Scope: Ensure both Admin (Roles and Users) and all Reports scopes are selected. For each scope, ensure it is set to Read-Only.

   2. Set optional expiry date: Never expire OR a defined interval that you will have to re-create and re-enter the key into the SIEM.

4. Click Generate.
   

   The generated values will be an Oauth2.0 client ID and client secret. Copy these values as well as the Oauth2.0 endpoint for later use.
   

   Note: The unified Umbrella API doesn't have a region specific API endpoint so this step can be skipped.
   

Configuring FortiSIEM for Umbrella Reporting API

Note about this API Endpoint:

This credential configuration implements the following API endpoint:

https://developer.cisco.com/docs/cloud-security/#!get-activities-all

This returns all major events for this organization (DNS, Proxy, Firewall, Intrusion, IP, AMP retrospective). Most of this data is duplicate of the AWS S3 Bucket ingestion of Cisco Umbrella logs configured through the actions here.

It is recommended to use the S3 bucket configuration method for high EPS environments.

Setup Cisco Umbrella Reporting API - Activity (all) in FortiSIEM

Note: The /activity API used here has many overlapping/duplicate data that is also generated by the S3 bucket ingestion method.

Take the following steps.

1. Navigate to ADMIN > Setup > Credentials.
2. In Step 1: Enter Credentials, take the following steps.
   1. In the Name field, enter "CiscoUmbrellaActivity".
   2. In the Device Type field, enter "Cisco Umbrella".
   3. From the Access Protocol drop-down list, select/enter HTTPS Advanced.
   4. Download the following file: Umbrella_Report_All_Activity_https_advanced_definition.json

   5. Click Import Definition, and select the file Umbrella_Report_All_Activity_https_advanced_definition.json downloaded from step d.

   6. Click Yes to overwrite.

   7. Only for Multi-Org and Managed Child Organizations:
      

      Note: If you do not do this, the data returned will be for whichever organization the API key was generated for.
      

      Using this method, you can generate one API key in the parent organization, and simply update the child ID in each FortiSIEM organization.
      

      Ensure you configure the credential in the target FortiSIEM organization so that data is not mixed.

      i.e. FortiSIEM Organization ABC -> Create Credential for Umbrella Child Organization 12345

      FortiSIEM Organization XYZ -> Create Credential for Umbrella Child Organization 9876

      Click the Authentication Parameters icon, and take the following steps.

      1. Click the Header tab, then New.

      2. For header Key Name, enter “X-Umbrella-OrgId”.

      3. For header Key Value, enter the target child organization ID you’d like to poll events for.

      4. Click OK.

      5. Click Save.
         

   8. Click the Authentication Parameters icon, and take the following steps.

      1. In the Client ID field, enter the Client ID you generated earlier for Cisco Umbrella Reporting API.
         

         Note: Several Umbrella APIs each use different authentication. This one is for reporting API.

      2. For Client Secret, enter the client secret that was generated earlier.

      3. Click OK.

   9. Click Save to save the entire credential.

3. In Step 2: Enter IP Range to Credential Associations, if you have more than one FortiSIEM collector, select the collector that will do the polling from the drop-down list. Note: A drop-down list will not appear if you only have one collector.
4. Click New.
   1. In the IP/Host Name field, enter "api.umbrella.com".
   2. Click +, and add all relevant Cisco Umbrella credentials that each represent an API call to get data.
   3. Click Save.
   4. Select the Step 2 mapping that was just saved/created.
5. Click the Test drop-down list and select Test Connectivity without Ping to test the connection.
   If you encounter an error, refer to Common Errors for additional information that may help you resolve the issue.
   
6. Observe that the test connectivity and confirm that it is successful.
7. Wait for approximately 5 minutes for the first set of events to get pulled in.
8. Navigate to ANALYTICS, and confirm that events appear by searching for event type containing "CiscoUmbrella".

Set up Cisco Umbrella Management API - List Users API in FortiSIEM

Configuring Cisco Umbrella Management JSON API

To configure the Cisco Umbrella Management API, you must set up the Cisco Umbrella Management API credentials.

Take the following steps.

Set up Cisco Umbrella Management API Credentials

1. Login to https://login.umbrella.com/.

2. Navigate to Admin > API Keys.

3. Select Umbrella Management or click New API Key.

   1. Under Key Scope: Ensure both Admin (Roles and Users) and all Management scopes are selected. For each scope, ensure it is set to Read-Only.

   2. Set optional expiry date: Never expire OR a defined interval that you will have to re-create and re-enter the key into the SIEM.

4. Click Generate.
   

   Copy the API Key and Secret Keys for authentication use later.

Configuring FortiSIEM for Umbrella Management API

This API endpoint continually polls a list of users in the Cisco Umbrella portal, and packages each into a log message in the following format:

Event Type: CiscoUmbrella-User-<status> Active/Inactive etc.

You can define rules to monitor for changes in role / status / and so on. The following data is polled for each user.

Consider configuring this for polling every 1 hour and not every 5 minutes.

                {
        "id": null,
        "firstname": null,
        "lastname": null,
        "email": null,
        "role": null,
        "roleId": null,
        "timezone": null,
        "status": null,
        "lastLoginTime": null,
        "twoFactorEnable": null
    }

Setup Cisco Umbrella Management API - List Users API in FortiSIEM -- GET /v1/organizations/<organization_id>/users

Take the following steps.

1. Navigate to ADMIN > Setup > Credentials.
2. In Step 1: Enter Credentials, take the following steps.
   1. In the Name field, enter "CiscoUmbrellaListUsers".
   2. In the Device Type field, enter "Cisco Umbrella".
   3. From the Access Protocol drop-down list, select/enter HTTPS Advanced.
   4. Download the following file: Umbrella_List_Users_https_advanced_definition.json

   5. Click Import Definition, and select the file Umbrella_List_Users_https_advanced_definition.json downloaded from step d.

   6. Click Yes to overwrite.

   7. Only for Multi-Org and Managed Child Organizations:
      

      Note: If you do not do this, the data returned will be for whichever organization the API key was generated for.
      

      Using this method, you can generate one API key in the parent organization, and simply update the child ID in each FortiSIEM organization.
      

      Ensure you configure the credential in the target FortiSIEM organization so that data is not mixed.

      i.e. FortiSIEM Organization ABC -> Create Credential for Umbrella Child Organization 12345

      FortiSIEM Organization XYZ -> Create Credential for Umbrella Child Organization 9876

      Click the Authentication Parameters icon, and take the following steps.

      1. Click the Header tab, then New.

      2. For header Key Name, enter “X-Umbrella-OrgId”.

      3. For header Key Value, enter the target child organization ID you’d like to poll events for.

      4. Click OK.

      5. Click Save.
         

   8. Click the Authentication Parameters icon, and take the following steps.

      1. In the Username field, enter the API Key generated earlier for Cisco Umbrella Management API.
         

         Note: Several Umbrella APIs each use different authentication. This one is for management API.
         

      2. In the Password field, enter the Secret Key that was generated earlier.

      3. Click OK.

   9. Click Save to save the entire credential.

3. In Step 2: Enter IP Range to Credential Associations, if you have more than one FortiSIEM collector, select the collector that will do the polling from the drop-down list. Note: A drop-down list will not appear if you only have one collector.
4. Click New.
   1. In the IP/Host Name field, enter "api.umbrella.com".
   2. Click +, and add all relevant Cisco Umbrella credentials that each represent an API call to get data.
   3. Click Save.
   4. Select the Step 2 mapping that was just saved/created.
5. Click the Test drop-down list and select Test Connectivity without Ping to test the connection.
   If you encounter an error, refer to Common Errors for additional information that may help you resolve the issue.
   
6. Observe that the test connectivity and confirm that it is successful.
7. Wait for approximately 5 minutes for the first set of events to get pulled in.
8. Navigate to ANALYTICS, and confirm that events appear by searching for event type containing "CiscoUmbrella".

Configuration via Amazon S3

• Setup in Cisco Umbrella

• Setup in FortiSIEM

Setup in Cisco Umbrella (Amazon S3)

Complete these steps from the Cisco Umbrella Portal.

1. Login to dashboard.umbrella.com.

2. Navigate to Admin > Log Management.

3. Navigate to Amazon S3.

4. Select the Use Cisco-Managed S3 storage radio button.

5. Select the closest geographically region to the FortiSIEM instance that will poll the logs.

6. Select the desired retention duration.
   Note: Since this will be ingested by FortiSIEM, it is recommended to select the shortest duration.

7. Click Save.

8. Click Continue.

9. On the final screen, record these values for Setup in FortiSIEM.

   • Data Path: This is the S3 bucket URL

   • Access Key

   • Secret Key

10. Click Got It.

11. Click Continue.
    Cisco Umbrella setup is now complete. However, it may take some time to activate.
    

Note: You can select company-managed s3 bucket, but you must provide an access key and secret with

appropriate permissions. Cisco managed takes away the difficulty with IAM permissions for S3 bucket access.

Setup in FortiSIEM (Amazon S3)

FortiSIEM processes events from Cisco Umbrella via the AWS S3 bucket API. Obtain your Access Key, Secret Key, and S3 bucket URL from the Cisco Umbrella Portal before proceeding.

Complete these steps in the FortiSIEM UI:

1. For Multi-tenant users, change the scope to the appropriate FortiSIEM organization.
2. Go to the ADMIN > Setup > Credentials tab.
3. In Step 1: Enter Credentials:
   1. Follow the instructions in “Setting Credentials“ in the User's Guide to create a new credential.
   2. Enter these settings in the Access Method Definition dialog box, and click Save when done.

      Settings	Description
      Name	Enter a name for the credential.
      Device Type	Cisco Umbrella
      Access Protocol	AWS_S3
      Region	Enter the AWS region for the bucket that was created, which can be found by looking at the data path name. For example, cisco-managed-us-west-1, means "us-west-1", so you would input us-west-1 in the Region field. If you know your region, you can use the region information from the link below. For example, for the region Europe (Frankfort), input eu-central-1 in the Region field. Region information can be found here: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html
      Bucket	Enter the Bucket value that appears before the forward slash, e.g. cisco-managed-us-west-1. If there is no prefix specified in the S3 data path section, e.g. s3://umbrella-managed-1105020-07c11114f2bd1366f0cef0db1048d111, the bucket should be "umbrella-managed-1105020-07c11114f2bd1366f0cef0db1048d111". Example: Bucket: umbrella-managed-1105020-07c11114f2bd1366f0cef0db1048d111
      Prefix	Provide the prefix; This is the part with the forward slash. Example: 1234567_b123456789f1e2a3a412345410123ffcd456789e0/ The prefix may be entered in any of the following ways: /xxxx/ xxxx /xxxx xxxx/ Examples: /1234567_b123456789f1e2a3a412345410123ffcd456789e0/ 1234567_b123456789f1e2a3a412345410123ffcd456789e0 /1234567_b123456789f1e2a3a412345410123ffcd456789e0 1234567_b123456789f1e2a3a412345410123ffcd456789e0/ If there is no prefix specified in the S3 data path section, e.g. s3://umbrella-managed-something, enter only a forward slash, "/". Example: Prefix: /
      Access Key ID	Enter/paste the access key you acquired during the Cisco Umbrella setup.
      Secret Key	Enter/paste the secret key you acquired during the Cisco Umbrella setup.
      Log Keyword	Leave the default option, which is Cisco_Umbrella_Log.
      Description	Description about the device

4. In Step 2: Enter IP Range to Credential Associations, if you have more than one FortiSIEM collector, select the collector that will do the polling from the drop-down list. Note: A drop-down list will not appear if you only have one collector.
5. Click New.
   1. Select the credential name you created (during step 3a) from the Credentials drop-down list. The IP/Host Name field should auto populate the URL (api.umbrella.com).
   2. Click Save.
6. Click the Test drop-down list and select Test Connectivity without Ping to test the connection.
7. Wait for approximately 5 minutes.
8. Navigate to ANALYTICS, and confirm that events appear.

Sample Events

//CiscoUmbrella-DNS-A-Query-Success
1 146.112.59.20 reports.api.umbrella.com Cisco_Umbrella_Log 5381234_b617173610f6e6a12340410126fdba516751f0/dnslogs/2021-08-25/2021-08-25-21-20-ade8.csv.gz : "2021-08-25 21:19:36","LAB-MACHINE","LAB-MACHINE","192.168.10.218","99.99.99.25","Allowed","1 (A)","NOERROR","static-asm.secure.skypeassets.com.","Chat,Instant Messaging,Software/Technology,Infrastructure,Internet Telephony,Application","Roaming Computers","Roaming Computers",""

//CiscoUmbrella-DNS-A-Query-Blocked
1 146.112.59.20 reports.api.umbrella.com Cisco_Umbrella_Log 5381234_b617173610f6e6a12340410126fdba516751f0/dnslogs/2021-08-26/2021-08-26-19-00-44ea.csv.gz : "2021-08-26 19:03:13","LAB-MACHINE","LAB-MACHINE","192.168.10.218","99.99.99.25","Blocked","1 (A)","NOERROR","www.facebook.com.","Social Networking,Application,Application Block","Roaming Computers","Roaming Computers","Application,Application Block"