diff options
Diffstat (limited to 'doc/man_pages/falcodump.adoc')
| -rw-r--r-- | doc/man_pages/falcodump.adoc | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/doc/man_pages/falcodump.adoc b/doc/man_pages/falcodump.adoc new file mode 100644 index 00000000..9e5b94f0 --- /dev/null +++ b/doc/man_pages/falcodump.adoc @@ -0,0 +1,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> |