---
name: "falcodump"
section: "1"
platform: "linux"
package: "wireshark-common"
version: "4.4.18-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/falcodump"
---

# falcodump(1)

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

## NAME

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

## SYNOPSIS

**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 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”.

## OPTIONS

- \--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

## SYSTEM CALL OPTIONS

- \--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.

## PLUGINS

### cloudtrail (AWS CloudTrail)

\--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.

## 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.

**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:

```
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.

## SEE ALSO

[wireshark(1)](/wireshark/1.md), [tshark(1)](/tshark/1.md), [dumpcap(1)](/dumpcap/1.md), [extcap(4)](/extcap/4.md)

## NOTES

**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\>.

## AUTHORS

**Original Author**\
 Gerald Combs \<gerald\[AT\]wireshark.org\>