1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
include::../attributes.adoc[]
= falcodump(1)
:doctype: manpage
:stylesheet: ws.css
:linkcss:
:copycss: {css_dir}/{stylesheet}
== NAME
falcodump - Dump log data to a file using a Falco source plugin.
== SYNOPSIS
.Common options
[manarg]
*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
[manarg]
[ *--include-capture-processes=<TRUE or FALSE> ]
[ *--include-switch-calls=<TRUE or FALSE> ]
.CloudTrail plugin options
[manarg]
[ *--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 https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/[environment variables and configuration files].
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 https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md[README] 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: kbd:[CTRL+C] should be used to stop the capture in order to ensure clean termination.
== SEE ALSO
xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4)
//, xref:logray.html[logray](1)
== 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
[%hardbreaks]
Gerald Combs <gerald[AT]wireshark.org>
|
