Skip to main content

​
Overview

The Cisco Umbrella integration enables ThreatAware to collect DNS security and web filtering data from your Cisco Umbrella deployment, providing visibility into network security across your organisation.
Connection Method: API Setup Time: 15 minutes Access Required: Cisco Umbrella Administrator account

​
Data collected

The Cisco Umbrella integration provides:
  • DNS security events
  • Web filtering and blocking events
  • Network traffic patterns
  • Security threat data
  • Compliance metrics

​
Use cases

DNS Security Monitoring

Monitor DNS security events and threat detection

Web Filtering Tracking

Track web filtering policies and blocked threats

Network Threat Detection

Detect malware, botnets, and command & control traffic

Security Analytics

Analyze network security trends and patterns

​
Setup instructions

1

Log in to Cisco Umbrella Console

Access the Cisco Umbrella Dashboard with an administrator account.
2

Navigate to API Key Settings

In the Cisco Umbrella console:
  • Go to Admin > API Keys
  • This is where you’ll create your API credentials
3

Create an API Key

Click Create to generate a new API key for ThreatAware integration.
  • The system will generate an API Key and Secret
  • Copy both the Key and Secret and store them securely
The Secret will only be displayed once. Copy both values immediately and store them securely.
4

Enter Credentials in ThreatAware

In ThreatAware:
  • Navigate to Settings > Integrations
  • Search for and select Cisco Umbrella
  • Enter the required credentials:
    • API Key: The key you copied from Cisco Umbrella
    • API Secret: The secret you copied from Cisco Umbrella
5

Connect and Verify

Click Connect to establish the integration.Verify the connection status shows Active in ThreatAware.

​
Required credentials

Field Name: Cisco Umbrella API Key Type: String Description: The API key generated in Cisco Umbrella for integration access
Store this credential securely in your organisation’s password manager.
Field Name: Cisco Umbrella API Secret Type: Password (encrypted) Description: The secret associated with the API Key
The Secret will only be displayed once during creation. Copy it immediately and store it securely.

​
Verification and testing

After setup, verify the integration is working correctly:
  1. Check Integration Status
    • Navigate to Settings > Integrations in ThreatAware
    • Confirm the Cisco Umbrella integration shows Active status
  2. Verify Data Collection
    • Wait up to 1 hour for the initial data sync
    • Check that Cisco Umbrella DNS security data appears
    • Verify network traffic and threat detection events are visible
  3. Test Queries
    • Create a test query to filter by DNS security events
    • Verify network traffic data matches your Umbrella environment
    • Test filtering by threat type or blocking status

​
Troubleshooting

Symptoms: Connection fails with authentication errorSolutions:
  • Verify the API Key and API Secret are entered correctly
  • Ensure both values were copied completely without extra spaces
  • Check that the credentials have not expired
  • Regenerate API credentials if needed
Symptoms: Connection succeeds but no data appears or permission errors occurSolutions:
  • Verify the API key has read permissions to:
    • DNS security data
    • Web filtering events
    • Network traffic data
  • Review the Cisco Umbrella API Documentation for required permissions
  • Check API key scope and permissions in Cisco Umbrella
Symptoms: Integration fails to connect or times outSolutions:
  • Verify the Cisco Umbrella service is online and accessible
  • Check firewall rules allow outbound HTTPS access to Cisco Umbrella
  • Test connectivity to the Umbrella API endpoint
  • Contact Cisco support if service issues persist
Symptoms: Integration shows active but no Umbrella data appearsSolutions:
  • Verify there is DNS and traffic data in Cisco Umbrella to collect
  • Check the API credentials have sufficient permissions
  • Wait up to 1 hour for the initial data sync
  • Review ThreatAware integration logs for errors
  • Verify your Umbrella organisation has active monitoring

​
Additional resources

Cisco Umbrella API Documentation

Official Cisco Umbrella API documentation for detailed configuration and permissions

ThreatAware Support

Contact ThreatAware support for integration assistance

​
Best practices

Credential Management
  • Generate a dedicated API key pair specifically for ThreatAware
  • Store credentials securely in your organisation’s password manager
  • Rotate API credentials annually or per your security policy
  • Monitor for authentication failures in ThreatAware logs
Security Considerations
  • Only grant read permissions to the API key
  • Limit API key scope to necessary data endpoints
  • Review Cisco Umbrella audit logs periodically to monitor API usage
  • Follow your organisation’s least privilege principles