Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to send ngrok events, including network traffic logs, to AWS Firehose. You may want to keep an audit log of configuration changes in your ngrok account, record all traffic to your endpoints for active monitoring and troubleshooting, or use AWS Firehose as a SIEM for security inspections. By integrating ngrok with AWS Firehose, you can:
  • Quickly identify application issues in real time using ngrok request events and Firehose data processing.
  • Historically audit changes occurring in an account.
  • Profile usage of your service using Firehose queries and real-time data analytics.
  • Identify security issues using ngrok events.

​
1. Obtain Firehose delivery stream ARN

For ngrok to send events to AWS Firehose, a delivery stream ARN is required. To create the stream, see the AWS Firehose documentation for creating a delivery stream. ngrok is a Direct PUT source type, and you can choose any Firehose destination you want. For testing, creating an S3 bucket as the destination may be easiest. After you create your AWS Firehose delivery stream, keep the Delivery Stream ARN for Step 3.

​
2. Create a log export

  • In a browser, go to Log Exporting in the ngrok dashboard.
  • Click + New Log Export.
  • Enter a description in the Description field.
  • In the Sources tab, click Add Source to choose which events to send to Firehose. For information about events, see the ngrok event documentation.
  • Make your selections from the list, then click Add Event Sources to confirm.
To capture traffic events only from specific endpoints or tunnels, add a CEL filter expression when configuring the source. For example, to filter by hostname: ev.conn.server_name == "your-tunnel.ngrok.app". See Log Sources filters for more examples and filter syntax.

​
3. Create event destination

To send events to Firehose, assign an Event Destination to the Log Export.
  • In the Destinations tab, click Add Destination.
  • Choose AWS Firehose as the target and fill in the required information:
    • Delivery Stream ARN
    • Description (optional)
  • Create IAM Role: An IAM role is required so ngrok can stream logs to Firehose. The dashboard provides two options: download and run the CLI Script to create the role automatically (the fastest option), or use the API tab’s displayed policy JSON to create it manually via the AWS console or tools like Terraform or Pulumi. Enter the resulting role ARN to complete the destination setup.
Security best practice: If configuring your IAM role manually, ensure that you configure the Trust Policy with a condition that includes the ExternalId. This ensures that the only data AWS can ingest is from your ngrok account. If you configure the IAM role with the CLI script, this is done automatically.
  • When all required inputs have values, click Send Test Event.
  • You should see a Success message.
  • Click Done to complete the Firehose Event Destination setup.