.png)
Cisco Umbrella Integration Guide
Connect Cisco Umbrella management, reporting, investigation, and enforcement APIs with enterprise workflows and security platforms.
Cisco Umbrella integration options at a glance
Cisco Umbrella’s primary integration model is REST API consumption across separate management, reporting, Investigate, and Enforcement API families. Management APIs use OAuth 2.0, while some Investigate and Enforcement capabilities use API keys or bearer-style credentials. Reporting integrations typically retrieve activity using filters, time windows, pagination, and checkpoints. Selected API areas support larger or multi-item retrieval patterns, but universal bulk coverage and general-purpose webhooks are not confirmed. Martini can authenticate securely, orchestrate scheduled workflows, transform Umbrella objects and security activity, apply validation and business rules, persist synchronization state, and expose controlled APIs for downstream systems.
| Integration point | Supported by Cisco Umbrella? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Cisco Umbrella provides separate REST API families for administration, reporting, investigations, and enforcement. These APIs support organization resources, security activity retrieval, intelligence lookups, and selected enforcement operations. | Martini can consume the documented REST endpoints from workflows, apply mappings and business rules, and expose reusable internal APIs around the integration. |
| Authentication | Yes | Management APIs use OAuth 2.0 access tokens; some Investigate and Enforcement APIs use API keys or bearer-style authorization. Permissions are scoped by organization and API client role. | Martini can store client secrets, tokens, API keys, organization identifiers, and endpoint configuration in protected environment configuration or secrets. |
| Reporting and incremental retrieval | Yes | Reporting APIs retrieve DNS, proxy, firewall, and security activity using endpoint-specific filters, time windows, pagination, and continuation logic. | Martini can schedule polling workflows, persist timestamps or cursors, overlap windows when needed, and deduplicate late or repeated activity. |
| Bulk or asynchronous processing | Limited | Selected reporting and enforcement areas support larger-result or multi-item retrieval patterns, but bulk coverage is not uniform across Cisco Umbrella resources. | Martini can orchestrate bounded batches, transform each page or result set, and control concurrency without assuming universal bulk support. |
| Enforcement operations | Yes | The Enforcement API can support selected operations for managing or querying destinations and other enforcement data, subject to permissions and endpoint coverage. | Martini can validate approved requests, check current state, apply idempotency controls, and invoke permitted enforcement operations. |
| Webhooks / outbound callbacks | Not confirmed | No general-purpose webhook or outbound callback facility was confirmed for Cisco Umbrella security events. | Martini should normally use scheduled polling and can expose APIs for inbound requests from other systems; product-specific notifications require separate verification. |
| SDKs | Limited | Cisco provides API documentation and examples, but a single official SDK covering all Umbrella API families was not confirmed. | Martini can consume the REST APIs directly and use custom JVM-compatible logic only where endpoint-specific processing requires it. |
| Database / analytics access | No | Cisco Umbrella does not provide direct database access to operational data; data is exposed through documented APIs and reports. | Martini can retrieve API data and write transformed results to supported databases, but it does not connect directly to Umbrella’s internal database. |
How Cisco Umbrella exposes data and business events
Cisco Umbrella REST APIs
Cisco Umbrella exposes REST API families for administration, reporting, investigations, and enforcement. The available resources and authentication requirements differ by API family, organization scope, permissions, and product entitlement.
Martini implementation pattern
Martini implementation pattern: A workflow stores API-family-specific configuration, authenticates with OAuth 2.0 or the required API-key or bearer credential, calls the selected endpoint, validates the response, maps the result, and routes it to a target system or reusable Martini API.
Implementation sequence
Cisco Umbrella Reporting APIs
Reporting APIs provide pull-based access to DNS, proxy, firewall, and security activity. Retrieval commonly depends on filters, bounded time windows, pagination, and the reporting latency of the selected endpoint.
Martini implementation pattern
Martini implementation pattern: A scheduled workflow retrieves an overlapping activity window, uses a durable timestamp or cursor checkpoint, transforms each page into a common security-event model, and delivers replay-safe records to a SIEM or database.
Implementation sequence
Cisco Umbrella Investigate API
The Investigate API supports domain, IP, and URL intelligence or reputation lookups. Its credential requirements may differ from those used for management APIs, so API-family-specific configuration is required.
Martini implementation pattern
Martini implementation pattern: A Martini API or workflow receives an enrichment request, validates the indicator type, calls the Investigate endpoint with the appropriate credential, maps the intelligence response, and returns or stores the result for an incident process.
Implementation sequence
Cisco Umbrella Enforcement API
The Enforcement API supports selected operations for querying or managing destinations and other enforcement data. Coverage and permissions must be checked for the specific resource and operation.
Martini implementation pattern
Martini implementation pattern: An approved security process invokes a controlled Martini API, which validates the requested destination and action, checks current state, applies approval and idempotency rules, and calls the permitted Enforcement endpoint.
Implementation sequence
Common Cisco Umbrella integration patterns
Pattern 1: Send security activity to a SIEM
When to use this pattern
Use this pattern when security teams need Cisco Umbrella DNS, proxy, firewall, or related activity in a central detection and investigation platform. Pull-based processing is appropriate because a general-purpose Umbrella webhook mechanism was not confirmed.
Integration direction
Example Mapping
| Cisco Umbrella Field | Canonical Field | Target Field |
|---|---|---|
| eventTimestamp | occurredAt | time |
| sourceAddress | source.ip | src_ip |
| destination | network.destination | dest_domain |
| action | security.action | action |
Martini implementation pattern
A scheduled Martini workflow reads a bounded reporting window, follows pagination, maps activity into a common event schema, enriches it with organization or network context, and submits replay-safe events. It persists a checkpoint, overlaps windows for delayed data, deduplicates records, and retries only transient failures.
Martini capabilities used
- workflows
- scheduler triggers
- API consumption
- data mapping
- business rules
- error handling
- checkpoint persistence
Pattern 2: Synchronize networks and endpoints
When to use this pattern
Use this pattern to keep an IT asset or service-management platform aligned with Cisco Umbrella Networks, Roaming computers, Users, and Teams.
Integration direction
Example Mapping
| Cisco Umbrella Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceId | u_umbrella_id |
| name | displayName | name |
| networkId | network.sourceId | cmdb_ci |
| status | lifecycle.status | install_status |
Martini implementation pattern
Martini periodically calls the relevant management endpoints, validates organization scope, maps each object to the target model, and upserts using stable Umbrella identifiers rather than display names. Invalid records are isolated for review, while transient target failures are retried without duplicating successful writes.
Martini capabilities used
- scheduled workflows
- REST API consumption
- data mapping
- validation
- upsert orchestration
- retry handling
Pattern 3: Apply approved destination enforcement
When to use this pattern
Use this pattern when a ticketing, threat-intelligence, or security process must request a controlled Umbrella destination change. It is appropriate only for operations exposed by the selected Enforcement API and authorized for the API client.
Integration direction
Example Mapping
| Cisco Umbrella Field | Canonical Field | Target Field |
|---|---|---|
| destination | indicator.value | destination |
| action | enforcement.operation | operation |
| approvalStatus | governance.approval | approval |
| requestId | idempotencyKey | request_id |
Martini implementation pattern
A Martini API receives the request, validates the indicator and approval state, checks existing destination state where supported, and invokes the Enforcement API. The workflow records the source request and response, prevents repeated application through idempotency checks, and sends rejected or ambiguous changes to exception handling.
Martini capabilities used
- API exposure
- API consumption
- validation
- business rules
- idempotency
- error handling
- audit logging
Pattern 4: Enrich incidents with Umbrella Investigate
When to use this pattern
Use this pattern when an incident platform needs domain, IP, or URL intelligence from Cisco Umbrella Investigate before analysts or automated rules make a decision.
Integration direction
Example Mapping
| Cisco Umbrella Field | Canonical Field | Target Field |
|---|---|---|
| indicator | indicator.value | query |
| indicatorType | indicator.type | lookup_type |
| classification | threat.classification | reputation |
| riskScore | threat.score | confidence |
Martini implementation pattern
Martini receives an incident enrichment request, validates the indicator type, calls the Investigate API with its separately managed credential, normalizes the response, and returns it to the incident process. Repeated lookups can be cached where appropriate, while authorization and not-found responses are not retried as transient failures.
Martini capabilities used
- API exposure
- REST API consumption
- data transformation
- conditional routing
- caching strategy
- error classification
Applications commonly integrated with Cisco Umbrella
Cisco Umbrella can be integrated with security operations, service-management, collaboration, and enterprise platforms through Martini workflows and APIs. The exact direction and API coverage should be confirmed for each target application and business process.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Splunk | Centralize Umbrella DNS, proxy, firewall, and security activity for correlation, alerting, and investigation. | Cisco Umbrella → Martini → Splunk | A scheduled workflow retrieves incremental Umbrella activity, handles pagination and checkpoints, maps events to the Splunk ingestion model, and retries transient delivery failures. |
| Microsoft Sentinel | Send Umbrella security activity and investigation data to Microsoft’s cloud SIEM for detection and incident response. | Cisco Umbrella → Martini → Microsoft Sentinel | Martini polls reporting or Investigate endpoints, normalizes activity into a security-event model, applies deduplication, and submits approved events to Sentinel. |
| ServiceNow | Synchronize security incidents, network context, and endpoint information with IT and security operations workflows. | Cisco Umbrella → Martini → ServiceNow | Martini retrieves Umbrella Networks, Roaming computers, Users, Teams, or security activity, matches stable identifiers, and creates or updates ServiceNow records with controlled retry handling. |
| Jira | Create or update security issues when Umbrella identifies policy violations, suspicious destinations, or investigation findings. | Cisco Umbrella → Martini → Jira | A workflow maps selected Umbrella findings to Jira issue fields, applies severity and routing rules, and stores the source identifier to prevent duplicate issues. |
| CrowdStrike Falcon | Enrich endpoint or threat investigations with Umbrella DNS and destination activity and correlate endpoint indicators with Umbrella data. | CrowdStrike Falcon → Martini → Cisco Umbrella | Martini receives an investigation request, calls the appropriate Umbrella Investigate or reporting endpoint, combines the response with endpoint context, and returns the enrichment to the originating security process. |
| Microsoft Teams | Post selected Umbrella alerts or workflow approval requests to security operations channels. | Cisco Umbrella → Martini → Microsoft Teams | Martini filters and formats selected activity or enforcement approval requests, then sends concise notifications through the relevant Microsoft API or endpoint. |
| PagerDuty | Create or update operational incidents for defined Umbrella service or security conditions. | Cisco Umbrella → Martini → PagerDuty | A scheduled workflow evaluates normalized Umbrella activity against alert rules, opens or resolves PagerDuty incidents, and uses deterministic keys for deduplication. |
| NetSuite | Synchronize organization or subscription-related operational data where Cisco service records are maintained in NetSuite. | Cisco Umbrella → Martini → NetSuite | Martini retrieves permitted Umbrella organization data, maps it to NetSuite’s model, and performs controlled upserts with validation and exception handling. |
How to build a Cisco Umbrella integration in Martini
Objective
Establish API-family-specific configuration and authentication without embedding Cisco Umbrella credentials in workflows.
Instructions in Martini
- Define the Umbrella endpoint, organization identifier, and API-family configuration
- Store OAuth client secrets, tokens, API keys, and bearer credentials in protected Martini secrets or environment configuration
- Grant only the organization permissions required by the workflow
- Test authentication separately for Management, Reporting, Investigate, and Enforcement APIs
Objective
Select a trigger that matches Cisco Umbrella’s pull-based integration model and the required freshness of the data.
Instructions in Martini
- Use a scheduler for reporting and inventory synchronization
- Use an exposed Martini REST API for approved enforcement or investigation requests
- Do not assume a universal Umbrella webhook exists
- Define bounded polling windows and expected reporting latency
Objective
Call the appropriate Cisco Umbrella API and retrieve complete, bounded result sets safely.
Instructions in Martini
- Select the Management, Reporting, Investigate, or Enforcement API family
- Apply endpoint-specific filters, time ranges, and pagination parameters
- Handle continuation tokens or page positions where documented
- Persist the last successful timestamp, cursor, or page checkpoint
Objective
Coordinate retrieval, validation, transformation, target delivery, and state management as a maintainable Martini workflow.
Instructions in Martini
- Separate API-family credentials and endpoint configuration
- Route management, activity, investigation, and enforcement use cases through clear workflow branches
- Limit concurrency according to the applicable Umbrella API rate limits
- Commit checkpoints only after downstream processing succeeds
Objective
Convert Cisco Umbrella objects and security activity into the target application’s canonical model.
Instructions in Martini
- Map stable Umbrella identifiers rather than display names
- Normalize timestamps, destinations, network context, actions, and classifications
- Preserve source identifiers and API-family context for auditability
- Apply schema validation before writing target records
Objective
Control enforcement, alerting, routing, and synchronization behavior according to organizational policy.
Instructions in Martini
- Require approval for destination or enforcement changes
- Filter security activity by organization, severity, destination, or network criteria
- Use deterministic keys for idempotency and duplicate prevention
- Route unmapped or ambiguous records to an exception path
Common Cisco Umbrella data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Organizations | Represent Cisco Umbrella customer or tenant organizations and provide scope for API operations. | ServiceNow, NetSuite, identity administration platforms | Martini retrieves organization data through the relevant management API, validates organization scope, and maps stable identifiers to target records. |
| Users | Represent administrative users associated with an Umbrella organization. | ServiceNow, identity governance platforms, reporting stores | Martini synchronizes user attributes where permitted, applies organization and role rules, and avoids exposing credentials in logs. |
| Teams | Group users for administrative or policy responsibilities. | ServiceNow, identity governance platforms | Martini maps Teams and memberships using stable identifiers and reconciles changes during scheduled synchronization. |
| Networks | Identify networks protected or managed by Cisco Umbrella. | ServiceNow, CMDBs, SIEM platforms | Martini retrieves Networks, normalizes identifiers and metadata, and performs replay-safe upserts into the target model. |
| Roaming computers | Represent endpoints using the Umbrella roaming security capability. | ServiceNow, CMDBs, security operations platforms | Martini synchronizes endpoint context, correlates stable identifiers, and routes unmapped or invalid records to exception handling. |
| Policies | Represent security and DNS-layer policies that control protection behavior. | ServiceNow, governance stores, security reporting platforms | Martini can retrieve supported policy data, preserve policy identifiers, and apply validation before any permitted downstream or enforcement action. |
Authentication and security considerations
API-family-specific authentication
Cisco Umbrella management APIs use OAuth 2.0, while some Investigate and Enforcement capabilities use API keys or bearer-style authorization. Credentials, organization identifiers, and endpoint configuration should be kept separate by API family.
Least privilege and secret handling
- Scope Umbrella API clients to the organization and permissions required by each workflow.
- Store OAuth client secrets, tokens, API keys, and bearer credentials in Martini secrets or protected environment configuration.
- Do not expose credentials through Martini APIs, payloads, or diagnostic logs.
- Redact sensitive domains, users, endpoints, and incident context according to organizational policy.
Operational considerations for Cisco Umbrella integrations
Polling, pagination, and rate limits
Reporting integrations should use bounded time windows, endpoint-specific pagination, durable checkpoints, and rate-aware concurrency. Confirm limits independently for the Management, Reporting, Investigate, and Enforcement APIs.
Reliability and data quality
- Use bounded exponential backoff for throttling and transient server failures.
- Do not automatically retry authentication, authorization, validation, or missing-resource failures.
- Use stable Umbrella identifiers and deterministic event keys for idempotency.
- Allow overlap for delayed reports, then deduplicate downstream.
- Test workflows when policy structures, report fields, or endpoint versions change.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a maintainable workflow layer for Cisco Umbrella API calls, scheduling, pagination, transformation, business rules, target delivery, and checkpoint management. This avoids duplicating authentication and retry logic across scripts.
Reusable integration assets
Teams can expose controlled APIs, reuse mappings and validation logic, separate environment configuration from implementation, and route failures consistently. Martini also supports writing normalized Umbrella data to enterprise platforms or supported databases without requiring direct access to Cisco’s internal data stores.
Operational control
- Centralize error handling, monitoring, and replay-safe processing.
- Keep API-family credentials and permissions explicit.
- Adapt one Umbrella integration to multiple targets through canonical mappings.
Frequently asked questions
Cisco Umbrella is primarily integrated through its REST API families for management, reporting, investigations, and enforcement. Enterprise workflows can use OAuth 2.0, API keys, or bearer-style credentials as required, retrieve activity through filtered and paginated API calls, and synchronize the results with security, service-management, and operational platforms.
Yes. Martini can integrate with Cisco Umbrella by consuming its documented management, reporting, Investigate, and Enforcement REST APIs. Martini can schedule polling workflows, transform Umbrella data, maintain synchronization checkpoints, and expose controlled APIs for approved investigation or enforcement processes.
No. A dedicated Cisco Umbrella connector is not required. Martini can use Cisco Umbrella’s confirmed native REST APIs and authentication methods through workflows and APIs; a verified native Martini connector was not confirmed in the supplied research.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Cisco Umbrella. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Cisco, cloud infrastructure, or other third-party systems depending on subscription, API usage, and deployment model.
Use the Management API for organizations, users, teams, networks, and administrative resources; Reporting APIs for security and operational activity; the Investigate API for domain, IP, and URL intelligence; and the Enforcement API for supported destination or enforcement operations. Credentials and permissions should be configured separately by API family.
A general-purpose Cisco Umbrella webhook or outbound callback mechanism was not confirmed. The safer integration design is scheduled polling of reporting or investigation endpoints. Any product-specific notification capability should be verified for the exact Umbrella service and event type before implementation.
Use the API’s supported time filters, cursors, or pagination mechanisms and persist the last successful checkpoint. For activity data, a small overlap between polling windows can account for delayed availability, while event identifiers or deterministic keys based on source attributes can prevent duplicate delivery.
Yes. Martini can expose a controlled REST API that validates requests, applies approval and business rules, invokes the appropriate Cisco Umbrella API, and returns a normalized response. This can provide downstream systems with a stable internal contract without exposing Umbrella credentials.
Related Martini documentation
APIs
Workflows
Data
Reliability
Connect Cisco Umbrella with Martini
Use Martini to orchestrate Cisco Umbrella API integrations, synchronize security data, apply controlled enforcement workflows, and deliver normalized information to enterprise systems.