doc/man_pages/falcodump.adoc

   1 include::../attributes.adoc[]
   2 = falcodump(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 falcodump - Dump log data to a file using a Falco source plugin.
  11
  12 == SYNOPSIS
  13
  14 .Common options
  15 [manarg]
  16 *falcodump*
  17 [ *--help* ]
  18 [ *--version* ]
  19 [ *--plugin-api-version* ]
  20 [ *--extcap-interfaces* ]
  21 [ *--extcap-dlts* ]
  22 [ *--extcap-interface*=<interface> ]
  23 [ *--extcap-config* ]
  24 [ *--extcap-capture-filter*=<capture filter> ]
  25 [ *--capture* ]
  26 [ *--fifo*=<path to file or pipe> ]
  27 [ *--plugin-source*=<source path or URL> ]
  28 [ *--log-level*=<log level> ]
  29 [ *--log-file*=<path to file> ]
  30
  31 .System call options
  32 [manarg]
  33 [ *--include-capture-processes=<TRUE or FALSE> ]
  34 [ *--include-switch-calls=<TRUE or FALSE> ]
  35
  36
  37 .CloudTrail plugin options
  38 [manarg]
  39 [ *--cloudtrail-s3downloadconcurrency*=<number of concurrent downloads> ]
  40 [ *--cloudtrail-s3interval*=<timeframe> ]
  41 [ *--cloudtrail-s3accountlist*=<comma separated account IDs> ]
  42 [ *--cloudtrail-sqsdelete*=<true or false> ]
  43 [ *--cloudtrail-useasync*=<true or false> ]
  44 [ *--cloudtrail-uses3sns*=<true or false> ]
  45 [ *--cloudtrail-aws-region*=<AWS region> ]
  46 [ *--cloudtrail-aws-profile*=<AWS profile> ]
  47 [ *--cloudtrail-aws-config*=<path> ]
  48 [ *--cloudtrail-aws-credentials*=<path to file> ]
  49
  50
  51 == DESCRIPTION
  52
  53 *falcodump* is an extcap tool that allows one to capture log messages from cloud providers.
  54
  55 Each plugin is listed as a separate interface.
  56 For example, the AWS CloudTrail plugin is listed as “cloudtrail”.
  57
  58 == OPTIONS
  59
  60 --help::
  61 Print program arguments.
  62 This will also list the configuration arguments for each plugin.
  63
  64 --version::
  65 Print the program version.
  66
  67 --plugin-api-version::
  68 Print the Falco plugin API version.
  69
  70 --extcap-interfaces::
  71 List the available interfaces.
  72
  73 --extcap-interface=<interface>::
  74 Use the specified interface.
  75
  76 --extcap-dlts::
  77 List the DLTs of the specified interface.
  78
  79 --extcap-config::
  80 List the configuration options of specified interface.
  81
  82 --extcap-capture-filter=<capture filter>::
  83 The capture filter.
  84 Must be a valid Sysdig / Falco filter.
  85
  86 --capture::
  87 Start capturing from the source specified by --plugin-source via the specified interface and write raw packet data to the location specified by --fifo.
  88
  89 --fifo=<path to file or pipe>::
  90 Save captured packet to file or send it through pipe.
  91
  92 --plugin-source=<source path or URL>::
  93 Capture from the specified location.
  94
  95 --log-level::
  96 Set the log level
  97
  98 --log-file::
  99 Set a log file to log messages in addition to the console
 100
 101 == SYSTEM CALL OPTIONS
 102
 103 --include-capture-processes::
 104 Include system calls for capture processes (falcodump, dumpcap, and Stratoshark) if TRUE.
 105 Defaults to FALSE.
 106
 107 --include-switch-calls::
 108 Include "switch" calls if TRUE.
 109 Defaults to FALSE.
 110
 111
 112 == PLUGINS
 113
 114 === cloudtrail (AWS CloudTrail)
 115
 116 --cloudtrail-s3downloadconcurrency::
 117 Controls the number of background goroutines used to download S3 files (Default: 32)
 118
 119 --cloudtrail-s3interval::
 120 Download log files over the specified interval (Default: no interval)
 121
 122 --cloudtrail-s3accountlist::
 123 If source is an organization CloudTrail S3 bucket download log files for all specified account IDs (Default: no account IDs)
 124
 125 --cloudtrail-sqsdelete::
 126 If true then the plugin will delete SQS messages from the queue immediately after receiving them (Default: true)
 127
 128 --cloudtrail-useasync::
 129 If true then async extraction optimization is enabled (Default: true)
 130
 131 --cloudtrail-uses3sns::
 132 If true then the plugin will expect SNS messages to originate from S3 instead of directly from Cloudtrail (Default: false)
 133
 134 --cloudtrail-aws-profile::
 135 If non-empty overrides the AWS shared configuration profile (e.g. 'default') and environment variables such as AWS_PROFILE (Default: empty)
 136
 137 --cloudtrail-aws-region::
 138 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)
 139
 140 --cloudtrail-aws-config::
 141 If non-empty overrides the AWS shared configuration filepath (e.g. ~/.aws/config) and env variables such as AWS_CONFIG_FILE (Default: empty)
 142
 143 --cloudtrail-aws-credentials::
 144 If non-empty overrides the AWS shared credentials filepath (e.g. ~/.aws/credentials) and env variables such as AWS_SHARED_CREDENTIALS_FILE (Default: empty)
 145
 146 CloudTrail sources can be S3 buckets or SQS queue URLs. S3 bucket URLs have the form
 147
 148 's3://__bucket_name__/__prefix__/AWSLogs/__account-id__/CloudTrail/__region__/__year__/__month__/__day__'
 149
 150 For organization CloudTrail the S3 bucket URL can be
 151
 152 's3://__bucket_name__/__prefix__/AWSLogs/__org-id__/__account-id__/CloudTrail/__region__/__year__/__month__/__day__'
 153
 154 The __region__, __year__, __month__, and __day__ components can be omitted in order to fetch more or less data.
 155 For example, the source 's3://mybucket/AWSLogs/012345678/CloudTrail/us-west-2/2023' will fetch all CloudWatch logs for the year 2023.
 156
 157 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'.
 158
 159 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.
 160
 161 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.
 162
 163 The cloudtrail plugin uses the AWS SDK for Go, which can obtain profile, region, and credential settings from a set of standard https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/[environment variables and configuration files].
 164 Falcodump will show a list of locally configured profiles and the current regions, and will let you supply a custom value as well.
 165
 166 More information is available in the https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md[README] of the CloudTrail plugin.
 167
 168 == EXAMPLES
 169
 170 To see program arguments:
 171
 172     falcodump --help
 173
 174 To see program version:
 175
 176     falcodump --version
 177
 178 To see interfaces:
 179
 180     falcodump --extcap-interfaces
 181
 182 Only one interface (falcodump) is supported.
 183
 184 .Example output
 185     interface {value=cloudtrail}{display=Falco plugin}
 186
 187 To see interface DLTs:
 188
 189     falcodump --extcap-interface=cloudtrail --extcap-dlts
 190
 191 .Example output
 192     dlt {number=147}{name=cloudtrail}{display=USER0}
 193
 194 To see interface configuration options:
 195
 196     falcodump --extcap-interface=cloudtrail --extcap-config
 197
 198 .Example output
 199     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}
 200     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}
 201     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}
 202     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}
 203
 204 To capture AWS CloudTrail events from an S3 bucket:
 205
 206     falcodump --extcap-interface=cloudtrail --fifo=/tmp/cloudtrail.pcap --plugin-source=s3://aws-cloudtrail-logs.../CloudTrail/us-east-2/... --capture
 207
 208 or:
 209
 210     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
 211
 212 NOTE: kbd:[CTRL+C] should be used to stop the capture in order to ensure clean termination.
 213
 214 == SEE ALSO
 215
 216 xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4)
 217 //, xref:stratoshark.html[stratoshark](1)
 218
 219 == NOTES
 220
 221 *falcodump* is part of the *Stratoshark* distribution.
 222 The latest version of *Stratoshark* can be found at https://www.wireshark.org.
 223
 224 HTML versions of the Wireshark project man pages are available at
 225 https://www.wireshark.org/docs/man-pages.
 226
 227 == AUTHORS
 228
 229 .Original Author
 230 [%hardbreaks]
 231 Gerald Combs <gerald[AT]wireshark.org>