falcodump - Dump log data to a file using a Falco source plugin.

OriginalAuthor
       Gerald Combs <gerald[AT]wireshark.org>

                                                   2025-06-10                                       FALCODUMP(1)

falcodump is an extcap tool that allows one to capture log messages from cloud providers.

       Each plugin is listed as a separate interface. For example, the AWS CloudTrail plugin is listed as
       “cloudtrail”.

       To see program arguments:

           falcodump --help

       To see program version:

           falcodump --version

       To see interfaces:

           falcodump --extcap-interfaces

       Only one interface (falcodump) is supported.

       Exampleoutput

           interface {value=cloudtrail}{display=Falco plugin}

       To see interface DLTs:

           falcodump --extcap-interface=cloudtrail --extcap-dlts

       Exampleoutput

           dlt {number=147}{name=cloudtrail}{display=USER0}

       To see interface configuration options:

           falcodump --extcap-interface=cloudtrail --extcap-config

       Exampleoutput

           arg {number=0}{call=--plugin-source}{display=Plugin source}{type=string}{tooltip=The plugin data source. This us usually a URL.}{placeholder=Enter a source URL…}{required=true}{group=Capture}
           arg {number=1}{call=cloudtrail-s3downloadconcurrency}{display=s3DownloadConcurrency}{type=integer}{default=1}{tooltip=Controls the number of background goroutines used to download S3 files (Default: 1)}{group=Capture}
           arg {number=2}{call=cloudtrail-sqsdelete}{display=sqsDelete}{type=boolean}{default=true}{tooltip=If true then the plugin will delete sqs messages from the queue immediately after receiving them (Default: true)}{group=Capture}
           arg {number=3}{call=cloudtrail-useasync}{display=useAsync}{type=boolean}{default=true}{tooltip=If true then async extraction optimization is enabled (Default: true)}{group=Capture}

       To capture AWS CloudTrail events from an S3 bucket:

           falcodump --extcap-interface=cloudtrail --fifo=/tmp/cloudtrail.pcap --plugin-source=s3://aws-cloudtrail-logs.../CloudTrail/us-east-2/... --capture

       or:

           falcodump --capture --extcap-interface cloudtrail --fifo ~/cloudtrail.pcap --plugin-source s3://my-cloudtrail-bucket/AWSLogs/o-abc12345/123456789012/ --cloudtrail-s3downloadconcurrency 32 --cloudtrail-s3interval 5d-2d --cloudtrail-aws-region eu-west-1

           Note

           CTRL + C should be used to stop the capture in order to ensure clean termination.

       falcodump - Dump log data to a file using a Falco source plugin.

falcodump is part of the Logray distribution. The latest version of Logray can be found at
       https://www.wireshark.org.

       HTML versions of the Wireshark project man pages are available at
       https://www.wireshark.org/docs/man-pages.

       --help
           Print program arguments. This will also list the configuration arguments for each plugin.

       --version
           Print the program version.

       --plugin-api-version
           Print the Falco plugin API version.

       --extcap-interfaces
           List the available interfaces.

       --extcap-interface=<interface>
           Use the specified interface.

       --extcap-dlts
           List the DLTs of the specified interface.

       --extcap-config
           List the configuration options of specified interface.

       --extcap-capture-filter=<capture filter>
           The capture filter. Must be a valid Sysdig / Falco filter.

       --capture
           Start capturing from the source specified by --plugin-source via the specified interface and write
           raw packet data to the location specified by --fifo.

       --fifo=<path to file or pipe>
           Save captured packet to file or send it through pipe.

       --plugin-source=<source path or URL>
           Capture from the specified location.

       --log-level
           Set the log level

       --log-file
           Set a log file to log messages in addition to the console

cloudtrail(AWSCloudTrail)
       --cloudtrail-s3downloadconcurrency
           Controls the number of background goroutines used to download S3 files (Default: 32)

       --cloudtrail-s3interval
           Download log files over the specified interval (Default: no interval)

       --cloudtrail-s3accountlist
           If source is an organization CloudTrail S3 bucket download log files for all specified account IDs
           (Default: no account IDs)

       --cloudtrail-sqsdelete
           If true then the plugin will delete SQS messages from the queue immediately after receiving them
           (Default: true)

       --cloudtrail-useasync
           If true then async extraction optimization is enabled (Default: true)

       --cloudtrail-uses3sns
           If true then the plugin will expect SNS messages to originate from S3 instead of directly from
           Cloudtrail (Default: false)

       --cloudtrail-aws-profile
           If non-empty overrides the AWS shared configuration profile (e.g. 'default') and environment
           variables such as AWS_PROFILE (Default: empty)

       --cloudtrail-aws-region
           If non-empty overrides the AWS region specified in the profile (e.g. 'us-east-1') and environment
           variables such as AWS_REGION (Default: empty)

       --cloudtrail-aws-config
           If non-empty overrides the AWS shared configuration filepath (e.g. ~/.aws/config) and env variables
           such as AWS_CONFIG_FILE (Default: empty)

       --cloudtrail-aws-credentials
           If non-empty overrides the AWS shared credentials filepath (e.g. ~/.aws/credentials) and env
           variables such as AWS_SHARED_CREDENTIALS_FILE (Default: empty)

       CloudTrail sources can be S3 buckets or SQS queue URLs. S3 bucket URLs have the form

       's3://bucket_name/prefix/AWSLogs/account-id/CloudTrail/region/year/month/day'

       For organization CloudTrail the S3 bucket URL can be

       's3://bucket_name/prefix/AWSLogs/org-id/account-id/CloudTrail/region/year/month/day'

       The region, year, month, and day components can be omitted in order to fetch more or less data. For
       example, the source 's3://mybucket/AWSLogs/012345678/CloudTrail/us-west-2/2023' will fetch all CloudWatch
       logs for the year 2023.

       If the URL ends with 'account-id/' or 'account-id/CloudTrail/' (for example
       's3://mybucket/AWSLOGS/012345678912/') the option '--cloudtrail-s3interval' can be used to define the
       time frame. A s3interval of '1d' for example would get all events of the last 24 hours from all available
       regions. A s3interval of '2w-1w' would get all events from all regions from two weeks ago up to one week
       ago. The s3invterval can also be defined as a RFC 3339-style timestamp like '2024-02-29T18:07:17Z' or
       '2024-02-29T00:00:00Z-2024-03-01T23:59:59Z'.

       If the URL ends with 'AWSLogs/org-id' option '--cloudtrail-s3accountlist' can be used to specify account
       IDs. This can be combined with '--cloudtrail-s3interval'. A source like
       's3://my-org-bucket/AWSLogs/o-123abc/' with '--cloudstrail-s3accountlist' set to
       '123456789012,987654321098' and '--cloudtrail-s3interval' set to '30m' would get all events of the last
       30min from all regions for accounts 123456789012 and 987654321098.

       If source URL is the organization CloudTrail bucket (like 's3://my-org-bucket/AWSLogs/o-123abc') and
       '--s3accountlist' is not set the plugin iterates over all accounts (limited by '--s3interval' if set).
       Attention: Depending on the size of the organization and the time interval, this can take a long time.

       The cloudtrail plugin uses the AWS SDK for Go, which can obtain profile, region, and credential settings
       from a set of standard environment variables and configuration files
       <https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/>. Falcodump will show a list of locally
       configured profiles and the current regions, and will let you supply a custom value as well.

       More information is available in the README
       <https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md> of the CloudTrail
       plugin.

wireshark(1), tshark(1), dumpcap(1), extcap(4)

Commonoptionsfalcodump [ --help ] [ --version ] [ --plugin-api-version ] [ --extcap-interfaces ] [ --extcap-dlts ]
       [ --extcap-interface=<interface> ] [ --extcap-config ] [ --extcap-capture-filter=<capture filter> ]
       [ --capture ] [ --fifo=<path to file or pipe> ] [ --plugin-source=<source path or URL> ]
       [ --log-level=<log level> ] [ --log-file=<path to file> ]

       Systemcalloptions
       [ --include-capture-processes=<TRUEorFALSE>][ --include-switch-calls=<TRUE or FALSE> ]

       CloudTrailpluginoptions
       [ --cloudtrail-s3downloadconcurrency=<number of concurrent downloads> ]
       [ --cloudtrail-s3interval=<timeframe> ] [ --cloudtrail-s3accountlist=<comma separated account IDs> ]
       [ --cloudtrail-sqsdelete=<true or false> ] [ --cloudtrail-useasync=<true or false> ]
       [ --cloudtrail-uses3sns=<true or false> ] [ --cloudtrail-aws-region=<AWS region> ]
       [ --cloudtrail-aws-profile=<AWS profile> ] [ --cloudtrail-aws-config=<path> ]
       [ --cloudtrail-aws-credentials=<path to file> ]

       --include-capture-processes
           Include system calls for capture processes (falcodump, dumpcap, and Logray) if TRUE. Defaults to
           FALSE.

       --include-switch-calls
           Include "switch" calls if TRUE. Defaults to FALSE.