Skip to content

Update Crowdstrike Readme #3057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrewkroh merged 8 commits into from
Apr 28, 2022
Merged

Update Crowdstrike Readme #3057

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fc30a08
Update Readme
GinnyGalicia Apr 11, 2022
215cfb3
Update changelog and run build
GinnyGalicia Apr 11, 2022
3b342f3
Update Readme
ellis-elastic Apr 13, 2022
94a4f8f
Update Readme - re ran build
ellis-elastic Apr 13, 2022
3b0a86c
Re ran build using v0.46.1
ellis-elastic Apr 13, 2022
edd8512
Resolved changelog conflict and ran build
ellis-elastic Apr 19, 2022
56e57ee
Merge branch 'main' into Crowdstrike-docs
ellis-elastic Apr 19, 2022
ff1a3e5
Merge branch 'main' into Crowdstrike-docs
bmorelli25 Apr 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 61 additions & 50 deletions packages/crowdstrike/_dev/build/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# CrowdStrike Integration

This integration is for CrowdStrike products. It includes the
This integration is for [CrowdStrike](https://www.crowdstrike.com/resources/?cs_query=type=5) products. It includes the
following datasets for receiving logs:

- `falcon` dataset: consists of endpoint data and Falcon platform audit data forwarded from Falcon SIEM Connector.
- `falcon` dataset: consists of endpoint data and Falcon platform audit data forwarded from [Falcon SIEM Connector](https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem/).
- `fdr` dataset: consists of logs forwarded using the [Falcon Data Replicator](https://github.com/CrowdStrike/FDR).

## Compatibility
Expand All @@ -22,15 +22,15 @@ Contains endpoint data and CrowdStrike Falcon platform audit data forwarded from

### FDR

The CrowdStrike Falcon Data Replicator (FDR) allows CrowdStrike users to replicate FDR data from CrowdStrike
managed S3 buckets. CrowdStrike writes notification events to a CrowdStrike managed SQS queue when new data is
The CrowdStrike Falcon Data Replicator (FDR) allows CrowdStrike users to replicate FDR data from CrowdStrike
managed S3 buckets. CrowdStrike writes notification events to a CrowdStrike managed SQS queue when new data is
available in S3.

This integration can be used in two ways. It can consume SQS notifications directly from the CrowdStrike managed
SQS queue or it can be used in conjunction with the FDR tool that replicates the data to a self-managed S3 bucket
This integration can be used in two ways. It can consume SQS notifications directly from the CrowdStrike managed
SQS queue or it can be used in conjunction with the FDR tool that replicates the data to a self-managed S3 bucket
and the integration can read from there.

In both cases SQS messages are deleted after they are processed. This allows you to operate more than one Elastic
In both cases SQS messages are deleted after they are processed. This allows you to operate more than one Elastic
Agent with this integration if needed and not have duplicate events, but it means you cannot ingest the data a second time.

#### Use with CrowdStrike managed S3/SQS
Expand All @@ -53,24 +53,27 @@ You need to follow the steps below:
- Configure the integration to read from your self-managed SQS topic.
- Disable the `Is FDR queue` option in the integration.

**NOTE: While the FDR tool can replicate the files from S3 to your local file system, this integration cannot read those files because they are gzip compressed, and the log file input does not support reading compressed files.**
> NOTE: While the FDR tool can replicate the files from S3 to your local file system, this integration cannot read those files because they are gzip compressed, and the log file input does not support reading compressed files.

#### Configuration for the S3 input

AWS credentials are required for running this integration if you want to use the S3 input.
AWS credentials are required for running this integration if you want to use the S3 input.

##### Configuration parameters
* *access_key_id*: first part of access key.
* *secret_access_key*: second part of access key.
* *session_token*: required when using temporary security credentials.
* *credential_profile_name*: profile name in shared credentials file.
* *shared_credential_file*: directory of the shared credentials file.
* *endpoint*: URL of the entry point for an AWS web service.
* *role_arn*: AWS IAM Role to assume.
* `access_key_id`: first part of access key.
* `secret_access_key`: second part of access key.
* `session_token`: required when using temporary security credentials.
* `credential_profile_name`: profile name in shared credentials file.
* `shared_credential_file`: directory of the shared credentials file.
* `endpoint`: URL of the entry point for an AWS web service.
* `role_arn`: AWS IAM Role to assume.

##### Credential Types
There are three types of AWS credentials can be used: access keys, temporary
security credentials and IAM role ARN.
There are three types of AWS credentials can be used:

- access keys,
- temporary security credentials, and
- IAM role ARN.

##### Access keys

Expand All @@ -83,57 +86,65 @@ for more details.

Temporary security credentials has a limited lifetime and consists of an
access key ID, a secret access key, and a security token which typically returned
from `GetSessionToken`. MFA-enabled IAM users would need to submit an MFA code
from `GetSessionToken`.

MFA-enabled IAM users would need to submit an MFA code
while calling `GetSessionToken`. `default_region` identifies the AWS Region
whose servers you want to send your first API request to by default. This is
typically the Region closest to you, but it can be any Region. Please see
whose servers you want to send your first API request to by default.

This is typically the Region closest to you, but it can be any Region. Please see
[Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
for more details.

`sts get-session-token` AWS CLI can be used to generate temporary credentials.
`sts get-session-token` AWS CLI can be used to generate temporary credentials.
For example. with MFA-enabled:
```js
aws> sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456
```

Because temporary security credentials are short term, after they expire, the
Because temporary security credentials are short term, after they expire, the
user needs to generate new ones and manually update the package configuration in
order to continue collecting `aws` metrics. This will cause data loss if the
configuration is not updated with new credentials before the old ones expire.
order to continue collecting `aws` metrics.

This will cause data loss if the configuration is not updated with new credentials before the old ones expire.

##### IAM role ARN

An IAM role is an IAM identity that you can create in your account that has
specific permissions that determine what the identity can and cannot do in AWS.

A role does not have standard long-term credentials such as a password or access
keys associated with it. Instead, when you assume a role, it provides you with
temporary security credentials for your role session. IAM role Amazon Resource
Name (ARN) can be used to specify which AWS IAM role to assume to generate
temporary credentials. Please see
[AssumeRole API documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
for more details.
keys associated with it. Instead, when you assume a role, it provides you with
temporary security credentials for your role session.
IAM role Amazon Resource Name (ARN) can be used to specify which AWS IAM role to assume to generate
temporary credentials.

Please see [AssumeRole API documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) for more details.

##### Supported Formats
1. Use access keys: Access keys include `access_key_id`, `secret_access_key`
1. Use access keys: Access keys include `access_key_id`, `secret_access_key`
and/or `session_token`.
2. Use `role_arn`: `role_arn` is used to specify which AWS IAM role to assume
for generating temporary credentials. If `role_arn` is given, the package will
check if access keys are given. If not, the package will check for credential
profile name. If neither is given, default credential profile will be used.
Please make sure credentials are given under either a credential profile or
access keys.
3. Use `credential_profile_name` and/or `shared_credential_file`:
If `access_key_id`, `secret_access_key` and `role_arn` are all not given, then
the package will check for `credential_profile_name`. If you use different
credentials for different tools or applications, you can use profiles to
configure multiple access keys in the same configuration file. If there is
no `credential_profile_name` given, the default profile will be used.
`shared_credential_file` is optional to specify the directory of your shared
credentials file. If it's empty, the default directory will be used.
In Windows, shared credentials file is at `C:\Users\<yourUserName>\.aws\credentials`.
For Linux, macOS or Unix, the file locates at `~/.aws/credentials`. Please see
[Create Shared Credentials File](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/create-shared-credentials-file.html)
for more details.
2. Use `role_arn`: `role_arn` is used to specify which AWS IAM role to assume
for generating temporary credentials.
If `role_arn` is given, the package will check if access keys are given.
If not, the package will check for credential profile name.
If neither is given, default credential profile will be used.

Please make sure credentials are given under either a credential profile or
access keys.
3. Use `credential_profile_name` and/or `shared_credential_file`:
If `access_key_id`, `secret_access_key` and `role_arn` are all not given, then
the package will check for `credential_profile_name`.
If you use different credentials for different tools or applications, you can use profiles to
configure multiple access keys in the same configuration file.
If there is no `credential_profile_name` given, the default profile will be used.
`shared_credential_file` is optional to specify the directory of your shared
credentials file.
If it's empty, the default directory will be used.
In Windows, shared credentials file is at `C:\Users\<yourUserName>\.aws\credentials`.
For Linux, macOS or Unix, the file locates at `~/.aws/credentials`.
Please see[Create Shared Credentials File](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/create-shared-credentials-file.html)
for more details.

{{fields "fdr"}}

Expand Down
5 changes: 5 additions & 0 deletions packages/crowdstrike/changelog.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
# newer versions go on top
- version: "1.3.1"
changes:
- description: Update readme file. Added link to CrowdStrike docs
type: enhancement
link: https://github.com/elastic/integrations/pull/3057
- version: "1.3.0"
changes:
- description: Update to ECS 8.2
Expand Down
111 changes: 61 additions & 50 deletions packages/crowdstrike/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# CrowdStrike Integration

This integration is for CrowdStrike products. It includes the
This integration is for [CrowdStrike](https://www.crowdstrike.com/resources/?cs_query=type=5) products. It includes the
following datasets for receiving logs:

- `falcon` dataset: consists of endpoint data and Falcon platform audit data forwarded from Falcon SIEM Connector.
- `falcon` dataset: consists of endpoint data and Falcon platform audit data forwarded from [Falcon SIEM Connector](https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem/).
- `fdr` dataset: consists of logs forwarded using the [Falcon Data Replicator](https://github.com/CrowdStrike/FDR).

## Compatibility
Expand Down Expand Up @@ -337,15 +337,15 @@ An example event for `falcon` looks as following:

### FDR

The CrowdStrike Falcon Data Replicator (FDR) allows CrowdStrike users to replicate FDR data from CrowdStrike
managed S3 buckets. CrowdStrike writes notification events to a CrowdStrike managed SQS queue when new data is
The CrowdStrike Falcon Data Replicator (FDR) allows CrowdStrike users to replicate FDR data from CrowdStrike
managed S3 buckets. CrowdStrike writes notification events to a CrowdStrike managed SQS queue when new data is
available in S3.

This integration can be used in two ways. It can consume SQS notifications directly from the CrowdStrike managed
SQS queue or it can be used in conjunction with the FDR tool that replicates the data to a self-managed S3 bucket
This integration can be used in two ways. It can consume SQS notifications directly from the CrowdStrike managed
SQS queue or it can be used in conjunction with the FDR tool that replicates the data to a self-managed S3 bucket
and the integration can read from there.

In both cases SQS messages are deleted after they are processed. This allows you to operate more than one Elastic
In both cases SQS messages are deleted after they are processed. This allows you to operate more than one Elastic
Agent with this integration if needed and not have duplicate events, but it means you cannot ingest the data a second time.

#### Use with CrowdStrike managed S3/SQS
Expand All @@ -368,24 +368,27 @@ You need to follow the steps below:
- Configure the integration to read from your self-managed SQS topic.
- Disable the `Is FDR queue` option in the integration.

**NOTE: While the FDR tool can replicate the files from S3 to your local file system, this integration cannot read those files because they are gzip compressed, and the log file input does not support reading compressed files.**
> NOTE: While the FDR tool can replicate the files from S3 to your local file system, this integration cannot read those files because they are gzip compressed, and the log file input does not support reading compressed files.

#### Configuration for the S3 input

AWS credentials are required for running this integration if you want to use the S3 input.
AWS credentials are required for running this integration if you want to use the S3 input.

##### Configuration parameters
* *access_key_id*: first part of access key.
* *secret_access_key*: second part of access key.
* *session_token*: required when using temporary security credentials.
* *credential_profile_name*: profile name in shared credentials file.
* *shared_credential_file*: directory of the shared credentials file.
* *endpoint*: URL of the entry point for an AWS web service.
* *role_arn*: AWS IAM Role to assume.
* `access_key_id`: first part of access key.
* `secret_access_key`: second part of access key.
* `session_token`: required when using temporary security credentials.
* `credential_profile_name`: profile name in shared credentials file.
* `shared_credential_file`: directory of the shared credentials file.
* `endpoint`: URL of the entry point for an AWS web service.
* `role_arn`: AWS IAM Role to assume.

##### Credential Types
There are three types of AWS credentials can be used: access keys, temporary
security credentials and IAM role ARN.
There are three types of AWS credentials can be used:

- access keys,
- temporary security credentials, and
- IAM role ARN.

##### Access keys

Expand All @@ -398,57 +401,65 @@ for more details.

Temporary security credentials has a limited lifetime and consists of an
access key ID, a secret access key, and a security token which typically returned
from `GetSessionToken`. MFA-enabled IAM users would need to submit an MFA code
from `GetSessionToken`.

MFA-enabled IAM users would need to submit an MFA code
while calling `GetSessionToken`. `default_region` identifies the AWS Region
whose servers you want to send your first API request to by default. This is
typically the Region closest to you, but it can be any Region. Please see
whose servers you want to send your first API request to by default.

This is typically the Region closest to you, but it can be any Region. Please see
[Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
for more details.

`sts get-session-token` AWS CLI can be used to generate temporary credentials.
`sts get-session-token` AWS CLI can be used to generate temporary credentials.
For example. with MFA-enabled:
```js
aws> sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456
```

Because temporary security credentials are short term, after they expire, the
Because temporary security credentials are short term, after they expire, the
user needs to generate new ones and manually update the package configuration in
order to continue collecting `aws` metrics. This will cause data loss if the
configuration is not updated with new credentials before the old ones expire.
order to continue collecting `aws` metrics.

This will cause data loss if the configuration is not updated with new credentials before the old ones expire.

##### IAM role ARN

An IAM role is an IAM identity that you can create in your account that has
specific permissions that determine what the identity can and cannot do in AWS.

A role does not have standard long-term credentials such as a password or access
keys associated with it. Instead, when you assume a role, it provides you with
temporary security credentials for your role session. IAM role Amazon Resource
Name (ARN) can be used to specify which AWS IAM role to assume to generate
temporary credentials. Please see
[AssumeRole API documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
for more details.
keys associated with it. Instead, when you assume a role, it provides you with
temporary security credentials for your role session.
IAM role Amazon Resource Name (ARN) can be used to specify which AWS IAM role to assume to generate
temporary credentials.

Please see [AssumeRole API documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) for more details.

##### Supported Formats
1. Use access keys: Access keys include `access_key_id`, `secret_access_key`
1. Use access keys: Access keys include `access_key_id`, `secret_access_key`
and/or `session_token`.
2. Use `role_arn`: `role_arn` is used to specify which AWS IAM role to assume
for generating temporary credentials. If `role_arn` is given, the package will
check if access keys are given. If not, the package will check for credential
profile name. If neither is given, default credential profile will be used.
Please make sure credentials are given under either a credential profile or
access keys.
3. Use `credential_profile_name` and/or `shared_credential_file`:
If `access_key_id`, `secret_access_key` and `role_arn` are all not given, then
the package will check for `credential_profile_name`. If you use different
credentials for different tools or applications, you can use profiles to
configure multiple access keys in the same configuration file. If there is
no `credential_profile_name` given, the default profile will be used.
`shared_credential_file` is optional to specify the directory of your shared
credentials file. If it's empty, the default directory will be used.
In Windows, shared credentials file is at `C:\Users\<yourUserName>\.aws\credentials`.
For Linux, macOS or Unix, the file locates at `~/.aws/credentials`. Please see
[Create Shared Credentials File](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/create-shared-credentials-file.html)
for more details.
2. Use `role_arn`: `role_arn` is used to specify which AWS IAM role to assume
for generating temporary credentials.
If `role_arn` is given, the package will check if access keys are given.
If not, the package will check for credential profile name.
If neither is given, default credential profile will be used.

Please make sure credentials are given under either a credential profile or
access keys.
3. Use `credential_profile_name` and/or `shared_credential_file`:
If `access_key_id`, `secret_access_key` and `role_arn` are all not given, then
the package will check for `credential_profile_name`.
If you use different credentials for different tools or applications, you can use profiles to
configure multiple access keys in the same configuration file.
If there is no `credential_profile_name` given, the default profile will be used.
`shared_credential_file` is optional to specify the directory of your shared
credentials file.
If it's empty, the default directory will be used.
In Windows, shared credentials file is at `C:\Users\<yourUserName>\.aws\credentials`.
For Linux, macOS or Unix, the file locates at `~/.aws/credentials`.
Please see[Create Shared Credentials File](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/create-shared-credentials-file.html)
for more details.

**Exported fields**

Expand Down
Loading