Skip to main content

Export Cisco Umbrella Config

Overview​

Export-CiscoUmbrellaConfig extracts Cisco Umbrella configuration from an HTTP Archive (HAR) file captured while browsing the Umbrella dashboard. Unlike the other Export functions in this module (which call vendor APIs directly), this function parses a local HAR file to reconstruct the full configuration — no live API access or credentials are required.

Why HAR-based? The Cisco Umbrella dashboard uses internal APIs (api.opendns.com and api.umbrella.com) that are not part of Cisco's public API surface. Capturing a HAR file while browsing the dashboard is the most reliable way to obtain the complete configuration data.

The function extracts 8 configuration object types:

#Object TypeOutput File
1DNS Policiesdns_policies.json
2Firewall Rulesfirewall_rules.json
3Web Policiesweb_policies.json
4Destination Listsdestination_lists.json
5Category Settingscategory_settings.json
6Application Settingsapplication_settings.json
7Security Settingssecurity_settings.json
8Selective Decryption Listsselective_decryption_lists.json

Prerequisites​

  • PowerShell 7.0 or higher
  • Migrate2GSA PowerShell module installed
  • Microsoft Edge (or Google Chrome — the steps are the same)
  • Cisco Umbrella dashboard access with sufficient permissions to view all policy sections
  • No network access or API credentials are required at export time — only the HAR file

Step 1: Capture the HAR File​

A HAR (HTTP Archive) file records all browser network requests and responses. You need to capture one while browsing through every configuration section of the Umbrella dashboard so that the API responses for all objects are included.

1.1 Log In and Open Developer Tools​

  1. Open Microsoft Edge (or Chrome)
  2. Navigate to the Cisco Umbrella dashboard and log in
  3. Once logged in and on the dashboard home page, press F12 to open Developer Tools (or right-click anywhere and select Inspect)
  4. Click the Network tab in the Developer Tools panel
  1. Ensure the following settings are configured:
    • Preserve log is checked (this prevents the log from clearing when pages navigate)
    • The red recording dot is active (recording is ON)
Why start after login?

Opening Developer Tools after logging in ensures that your login credentials are not captured in the HAR file. The HAR only needs the API responses from browsing configuration pages — not the authentication flow.

1.2 Browse All Configuration Sections​

After logging in, you need to visit each section of the dashboard and expand/click into individual items so that the browser fetches their full detail data. The dashboard loads summary data on list pages but fetches expanded details only when you click into each item.

Important

Simply visiting the list pages is not enough. You must click into each individual item (policy, setting, list) to trigger the detail API calls. The detail responses contain additional fields (category arrays, application lists, rule settings) that are not present in the summary views.

Follow this sequence, clicking through every item in each section:

DNS Policies​

  1. Navigate to Policies > DNS Policies
  2. The list view loads automatically — this captures the policy list with embedded settings
  3. Click on each DNS policy to open its detail view
  4. Wait for the page to fully load before moving to the next policy

Firewall Policy​

  1. Navigate to Policies > Firewall Policy
  2. The firewall ruleset loads automatically in a single view
  3. If there are more than 25 rules, scroll down or navigate to subsequent pages to load all rules

Web Policy​

  1. Navigate to Policies > Web Policy
  2. The list view loads the web policy bundles
  3. Click on each web policy to open its detail view — this triggers the proxy ruleset and ruleset settings API calls
  4. Wait for the page to fully load before moving to the next policy

Destination Lists​

  1. Navigate to Policies > Policy Components > Destination Lists
  2. The list view loads automatically
  3. Click on each destination list to view its entries — this triggers the destinations detail API calls
  4. If a list has many entries, scroll through or page through all entries to ensure they are captured

Content Categories (Category Settings)​

  1. Navigate to Policies > Policy Components > Content Categories
  2. The list view loads the category settings summaries
  3. Click on each category setting to expand it

Application Settings​

  1. Navigate to Policies > Policy Components > Application Settings
  2. The list view loads application setting summaries
  3. Click on each application setting to expand it

Security Settings​

  1. Navigate to Policies > Policy Components > Security Settings
  2. Click on each security setting to open its detail view — detail responses use datetime strings instead of epoch timestamps

Selective Decryption Lists​

  1. Navigate to Policies > Policy Components > Selective Decryption
  2. The list view loads the selective decryption list settings
  3. Click on each list to view its detail if any are present

1.3 Export the HAR File​

Once you have browsed through all sections above:

  1. Return to the Network tab in Developer Tools
  2. Right-click anywhere in the request list
  3. Select Save all as HAR with content (in Edge) or Save all as HAR (in Chrome)
  1. Save the file with a .har extension (e.g., umbrella_dashboard.har)
  2. Close Developer Tools
File Size

HAR files are typically 50–200 MB because they include all response bodies (HTML, CSS, JS, images). This is expected — the export function filters to only the relevant API responses (~2–5 MB of actual configuration data).

Step 2: Run the Export​

Syntax​

Export-CiscoUmbrellaConfig
    -HARFilePath <String>
    [-OutputDirectory <String>]
    [-ExportCleanHAR]
    [<CommonParameters>]

Parameters​

-HARFilePath​

Path to the .har file captured from the Umbrella dashboard.

  • Type: String
  • Required: Yes
  • Validation: File must exist and have a .har extension

-OutputDirectory​

Directory where the timestamped backup folder will be created.

  • Type: String
  • Required: No
  • Default value: Current directory

-ExportCleanHAR​

When specified, produces only a sanitized copy of the HAR file (sensitive headers removed, non-API entries stripped) and skips configuration extraction. This is useful for sharing the HAR with support teams.

  • Type: Switch
  • Required: No
  • Default value: $false

Examples​

Basic Export​

Import-Module Migrate2GSA

Export-CiscoUmbrellaConfig -HARFilePath "C:\captures\umbrella_dashboard.har"

Creates a backup folder in the current directory with all extracted configuration files.

Export to Custom Directory​

Export-CiscoUmbrellaConfig `
    -HARFilePath "C:\captures\umbrella_dashboard.har" `
    -OutputDirectory "C:\Backups\Umbrella"

Export a Sanitized HAR for Sharing​

Export-CiscoUmbrellaConfig `
    -HARFilePath "C:\captures\umbrella_dashboard.har" `
    -ExportCleanHAR

Produces only umbrella_clean.har — no JSON extraction is performed. The clean HAR has:

  • All non-API entries removed (HTML, CSS, JS, images, analytics)
  • Authorization, Cookie, Set-Cookie, X-CSRF-Token, and X-Auth* headers stripped
  • Cookie arrays cleared
Sharing HAR files

Always use -ExportCleanHAR before sharing a HAR file. The original HAR contains session tokens and cookies that could be used to access your Umbrella account.

Debug Mode​

Export-CiscoUmbrellaConfig `
    -HARFilePath "C:\captures\umbrella_dashboard.har" `
    -Debug

Output Structure​

Full Export (default)​

CiscoUmbrella-backup_{timestamp}/
├── dns_policies.json
├── firewall_rules.json
├── web_policies.json
├── destination_lists.json
├── category_settings.json
├── application_settings.json
├── security_settings.json
├── selective_decryption_lists.json
├── export_metadata.json
└── {timestamp}_Export-CiscoUmbrella.log

Clean HAR Export (-ExportCleanHAR)​

CiscoUmbrella-backup_{timestamp}/
├── umbrella_clean.har
└── {timestamp}_Export-CiscoUmbrella.log

Export Metadata​

The export_metadata.json file records provenance and summary counts:

{
    "timestamp": "20260220_143022",
    "sourceHARFile": "umbrella_dashboard.har",
    "organizationId": "8144773",
    "exportType": "CiscoUmbrella_HAR_Extract",
    "objectCounts": {
        "dnsPolicies": 3,
        "firewallRules": 2,
        "webPolicies": 1,
        "destinationLists": 5,
        "categorySettings": 5,
        "applicationSettings": 3,
        "securitySettings": 4,
        "selectiveDecryptionLists": 1
    },
    "warnings": []
}

Configuration Objects Exported​

Object TypeDescription
DNS PoliciesDNS filtering policy bundles with embedded category, security, and policy settings. Enriched with individual policy setting details when available.
Firewall RulesFirewall ruleset with all rules. Includes hit count interval reference data when present.
Web PoliciesWeb filtering policy bundles with proxy rulesets and ruleset settings attached.
Destination ListsCustom allow/block lists with their destination entries (domains, IPs, URLs).
Category SettingsWeb content category configurations with full categories[] and warnCategories[] arrays.
Application SettingsApplication control settings with applications[] and applicationsCategories[] arrays. Includes system-inherited settings.
Security SettingsSecurity threat protection settings with category details. MSP-inherited records are tagged with _isInherited: true.
Selective Decryption ListsSSL/TLS inspection bypass settings with linked exception domain lists.

Troubleshooting​

"No Cisco Umbrella API requests found in the HAR file"​

Cause: The HAR file doesn't contain any requests to api.opendns.com or api.umbrella.com.

Solution:

  • Verify you captured the HAR while browsing the Umbrella dashboard (not another Cisco product)
  • Ensure Preserve log was checked before navigating
  • Make sure the capture was running while you were logged in and browsing configuration pages

Missing object types (empty JSON arrays)​

Cause: You didn't browse the corresponding dashboard section during the HAR capture.

Solution:

  • Recapture the HAR, making sure to visit all sections listed in Step 1.2
  • Remember to click into each individual item — list pages alone don't trigger detail API calls

"The file is not a valid HAR/JSON file"​

Cause: The file is corrupted or not a valid HAR export.

Solution:

  • Re-export the HAR from the browser
  • Ensure you selected Save all as HAR with content (not just headers)
  • Check the file opens in a text editor and starts with { "log":

Objects exported with list-level data only (warnings about missing details)​

Cause: You visited the list page but didn't click into individual items.

Solution: Recapture the HAR and click on each item in the section to trigger the detail API calls. The log file will indicate which items fell back to list-level data.

Logging​

All output is logged to {timestamp}_Export-CiscoUmbrella.log in the backup folder. The function uses the following log levels:

LevelDescription
INFOGeneral progress and statistics
SUCCESSSuccessful extractions with item names and counts
WARNMissing data, fallback to list-level data
ERRORFailures that prevent extraction of a specific type
SUMMARYSection headers and configuration summaries
DEBUGDetailed diagnostic information (requires -Debug)

Feedback and Support​

For issues, questions, or feedback, please refer to the main repository documentation.