Skip to main content

Cisco Umbrella to Huntress HEC Log Shipping

· 4 min read
Luke Steward
Luke Steward
Technical Manager & Security Engineer

This project provides two versions of a PowerShell script to ship logs from Cisco Umbrella Portal to Huntress using the HEC (HTTP Event Collector) format.

⚠️ PowerShell 7+ Required: This project requires PowerShell 7 or later. It will not work with Windows PowerShell 5.1.

Features​

  • Batched Processing: 200 events per HTTP request
  • Comprehensive Field Mapping: All Cisco Umbrella fields mapped to Huntress ECS format
  • Flattened Data Structure: Complex nested objects expanded for better SIEM visibility
  • Multiple Log Types: DNS, Proxy, Firewall, Intrusion, and IP logs
  • Incremental Processing: 10-minute lookback window for efficient processing
  • State Management: Tracks last run time to prevent duplicates

Scripts​

There are two scripts located in this GitHub repo, one is for standalone usage and one is for deploying to AzureFunctions

Standalone Version (CiscoUmbrellaToHEC-Standalone.ps1)​

  • Purpose: Run locally to test it out (Requires: PowerShell 7+)
  • Features:
    • Batched HTTP requests (200 events per request)
    • Progress indicators
  • Usage: pwsh -ExecutionPolicy Bypass -File "CiscoUmbrellaToHEC-Standalone.ps1"

Required Parameters​

  • ApiKey: Cisco Umbrella API Key
  • ApiSecret: Cisco Umbrella API Secret
  • HuntressHecToken: Huntress HEC Token (Setup Guide)

Azure Functions Version​

  • Purpose: Deploy as an Azure Function for automated execution
  • Features:
    • Same batched processing as standalone
    • Timer-triggered execution
    • Environment variable configuration
    • Azure Function return format
  • Deployment: Use the deploy to Azure Button below or follow the steps for manual deployment

Environment Variables​

  • UMBRELLA_API_KEY: Cisco Umbrella API Key
  • UMBRELLA_API_SECRET: Cisco Umbrella API Secret
  • HUNTRESS_HEC_TOKEN: Huntress HEC Token (Setup Guide)

Deployment​

🚀 One-Click Azure Deployment​

Deploy to Azure

The deployment will prompt you for:

  • Cisco Umbrella API Key: Cisco Umbrella API Key (Inside of Customer)
  • Cisco Umbrella API Secret: Cisco Umbrella API Secret
  • Huntress HEC Token: Huntress HEC Token

📦 Deploy Function Code​

After the infrastructure is deployed, you need to deploy the function code.

  1. Fork this repository to your GitHub account
  2. Go to Azure Portal → Your Function App → Deployment Center
  3. Select GitHub as source
  4. Authorize and select your forked repository
  5. Choose branch: main
  6. Set application path: CiscoUmbrellaToHEC
  7. Save - Azure will automatically deploy your function code

Manual Deployment​

  1. Download the function code
  2. Zip the CiscoUmbrellaToHEC folder
  3. Go to Azure Portal → Your Function App → Deployment Center
  4. Select "Zip Deploy" as source
  5. Upload the zip file

Configuration​

Cisco Umbrella API Setup​

  1. Log into your Cisco Umbrella Dashboard
  2. Navigate to Admin → API Keys
  3. Create a new API key with the following permissions:
    • Reporting (Read)
    • Investigations (Read)

Huntress HEC Setup​

  1. Log into your Huntress Dashboard
  2. Navigate to SIEM → Source Management → Categories
  3. Create a new Generic HTTP Event Collector (HEC) called Cisco Umbrella
  4. Note the HEC endpoint URL (usually https://hec.huntress.io/services/collector/raw)

Usage​

Standalone Script​

# Run the standalone script
pwsh -ExecutionPolicy Bypass -File "CiscoUmbrellaToHEC-Standalone.ps1" `
  -ApiKey "your-api-key" `
  -ApiSecret "your-api-secret" `
  -HuntressHecToken "your-huntress-hec-token"

Azure Function​

The Azure Function will automatically run every 10 minutes and process logs from the last 10-minute window. No manual intervention required.

Log Types Supported​

  • DNS Logs: Domain resolution events
  • Proxy Logs: Web proxy traffic
  • Firewall Logs: Network firewall events
  • Intrusion Logs: Security events and alerts
  • IP Logs: IP address reputation events

Troubleshooting​

Common Issues​

  1. PowerShell Version: Ensure you're using PowerShell 7+
  2. API Permissions: Verify your Cisco Umbrella API key has the correct permissions
  3. HEC Token: Confirm your Huntress HEC token is valid and active
  4. Network Connectivity: Ensure the Azure Function can reach both Cisco Umbrella and Huntress endpoints

Logs​

Check the Azure Function logs in the Azure Portal under Monitoring → Logs for detailed execution information.

Security Considerations​

  • Store API keys and tokens securely using Azure Key Vault or environment variables
  • Use managed identities where possible
  • Regularly rotate API keys and tokens
  • Monitor for failed authentication attempts

Contributing​

Contributions are welcome! Please feel free to submit a Pull Request.

License​

This project is licensed under the MIT License - see the LICENSE file for details.

Support​

For issues and questions:

  • Create an issue in this repository