FALCODUMP(1)

📦
version 4.6.6 · 11 versions
, in alpine 3.24

💅 falcodump(1) — the group chat version 🎀

ok so you know how I keep rambling about capturing log data from cloud providers? this is the tool, bestie. it's falcodump, and no, I'm not gonna gatekeep it. it's an extcap tool (the manual page for it is FALCODUMP(1), in case you were wondering what that little header thing meant ✨).

✨ NAME ✨

falcodump — dump log data to a file using a Falco source plugin. that's it. that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

so there are three lil' families of options and I'm putting all of them right here, verbatim, because we do NOT abbreviate in this house 💅

Common options

falcodump [ --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> ]

System call options

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

CloudTrail plugin options

[ --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> ]

🦋 DESCRIPTION 🦋

falcodump is an extcap tool that lets you capture log messages from cloud providers. literally its whole personality. 😌

each plugin shows up as a separate interface. for example, the AWS CloudTrail plugin is listed as “cloudtrail”. cute, right?

💖 OPTIONS 💖

okay here's the whole menu, no skips, no "you don't need to know that"s:

  • --help — print program arguments. and yes, it also lists 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 the specified interface.
  • --extcap-capture-filter=<capture filter> — the capture filter. important: it must be a valid Sysdig / Falco filter. no random nonsense, bestie 💀
  • --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 a 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.

⭐ SYSTEM CALL OPTIONS ⭐

  • --include-capture-processes — include system calls for capture processes (falcodump, dumpcap, and Stratoshark) if TRUE. defaults to FALSE.
  • --include-switch-calls — include "switch" calls if TRUE. defaults to FALSE.

👑 PLUGINS 👑

☁️ cloudtrail (AWS CloudTrail)

the icon. the moment. the plugin. 🌈

  • --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 the source is an organization CloudTrail S3 bucket, download log files for all specified account IDs. default: no account IDs.
  • --cloudtrail-sqsdelete — if true, the plugin will delete SQS messages from the queue immediately after receiving them. default: true.
  • --cloudtrail-useasync — if true, async extraction optimization is enabled. default: true.
  • --cloudtrail-uses3sns — if true, 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.

🧚 where can your source point, tho?

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. obsessed with the flexibility ngl 💅

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. an s3interval of '1d' for example would get all events of the last 24 hours from all available regions. an 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'.

yes, it says s3invterval in the manual. I don't make the rules, I just report them 🙈

if the URL ends with 'AWSLogs/org-id' the 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 the 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. like, go-make-a-snack long. 😭

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 at 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 of the CloudTrail plugin at https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.

🔥 EXAMPLES 🔥

to see program arguments:

falcodump --help

to see program version:

falcodump --version

to see interfaces:

falcodump --extcap-interfaces

only one interface (falcodump) is supported. yes, really. 💀

example output:

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

to see interface DLTs:

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

example output:

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

to see interface configuration options:

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

example output:

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, if you're feeling extra ✨:

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. don't just close the terminal like a menace, okay? 🙏

🍓 SEE ALSO 🍓

stratoshark(1), strato(1), dumpcap(1), extcap(4) — go read those too, they're the supporting cast 💜

🌸 NOTES 🌸

falcodump is part of the Stratoshark distribution. the latest version of Stratoshark 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. iykyk ✨

💜 AUTHORS 💜

Original Author

Gerald Combs <gerald[AT]wireshark.org>

and that's the whole page, bestie — main character energy, dated 2026-05-24, living its best life as FALCODUMP(1). go forth and capture responsibly 💖🦋✨

📦 where this page comes from