⚠️ 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​

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.

GitHub Deployment (Recommended)​

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