From 0965144f215f292186cfae0e6648b5f9ce7c8c7f Mon Sep 17 00:00:00 2001 From: Hiroshi Hatake Date: Thu, 20 Apr 2023 10:56:39 +0200 Subject: [PATCH] out_chronicle: Add documentation Signed-off-by: Hiroshi Hatake --- .gitbook.yaml | 1 + SUMMARY.md | 1 + pipeline/outputs/chronicle.md | 56 +++++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 pipeline/outputs/chronicle.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 8c4b92479..f984c5b1e 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -50,6 +50,7 @@ redirects: output/azure_kusto: ./pipeline/outputs/azure_kusto.md output/bigquery: ./pipeline/outputs/bigquery.md output/counter: ./pipeline/outputs/counter.md + output/chronicle: ./pipeline/outputs/chronicle.md output/cloudwatch: ./pipeline/outputs/cloudwatch.md output/datadog: ./pipeline/outputs/datadog.md output/es: ./pipeline/outputs/elasticsearch.md diff --git a/SUMMARY.md b/SUMMARY.md index b0ef5c53f..d30fd5450 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -156,6 +156,7 @@ * [FlowCounter](pipeline/outputs/flowcounter.md) * [Forward](pipeline/outputs/forward.md) * [GELF](pipeline/outputs/gelf.md) + * [Google Chronicle](pipeline/outputs/chronicle.md) * [Google Cloud BigQuery](pipeline/outputs/bigquery.md) * [HTTP](pipeline/outputs/http.md) * [InfluxDB](pipeline/outputs/influxdb.md) diff --git a/pipeline/outputs/chronicle.md b/pipeline/outputs/chronicle.md new file mode 100644 index 000000000..cb15bcea4 --- /dev/null +++ b/pipeline/outputs/chronicle.md @@ -0,0 +1,56 @@ +--- + +# Chronicle + +The Chronicle output plugin allows ingesting security logs into [Google Chronicle](https://chronicle.security/) serivice. This connector is designed to send unstructured style of security logs. + +## Google Cloud Configuration + +Fluent Bit streams data into an existing Google Chronicle tenant using a service account that you specify. Therefore, before using the Chronicle output plugin, you must create a service account, create a Google Chronicle tenant, authorize the service account to write to the tenant, and provide the service account credentials to Fluent Bit. + +### Creating a Service Account + +To stream security logs into Google Chronicle, the first step is to create a Google Cloud service account for Fluent Bit: + +* [Creating a Google Cloud Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) + +### Creating a Tenant of Google Chronicle + +Fluent Bit does not create a tenant of Google Chronicle for your secutiry logs, so you must create this ahead of time. + +### Retrieving Service Account Credentials + +Fluent Bit Chronicle output plugin uses a JSON credentials file for authentication credentials. Download the credentials file by following these instructions: + +* [Creating and Managing Service Account Keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) + +## Configurations Parameters + +| Key | Description | default | +| :--- | :--- | :--- | +| google\_service\_credentials | Absolute path to a Google Cloud credentials JSON file. | Value of the environment variable _$GOOGLE\_SERVICE\_CREDENTIALS_ | +| service\_account\_email | Account email associated to the service. Only available if **no credentials file** has been provided. | Value of environment variable _$SERVICE\_ACCOUNT\_EMAIL_ | +| service\_account\_secret | Private key content associated with the service account. Only available if **no credentials file** has been provided. | Value of environment variable _$SERVICE\_ACCOUNT\_SECRET_ | +| project\_id | The project id containing the tenant of Google Chronicle to stream into. | The value of the `project_id` in the credentials file | +| customer\_id | The customer id to identify the tenant of Google Chronicle to stream into. The value of the `customer_id` should be specified in the configuration file. | | +| log\_type | The log type to handle the request entries. Users must set up the valid log types and here is [the supported log types](https://cloud.google.com/chronicle/docs/ingestion/parser-list/supported-default-parsers). Otherwise, the chronicle service denies to handle the ingested logs. | | +| region | The GCP region in which to store security logs. Currently, there are several supported regions: `US`, `EU`, `UK`, `ASIA`. Blank is handled as `US`. | | +| log\_key | By default, the whole log record will be sent to Chronocle. If you specify a key name with this option, then only the value of that key will be sent to Chronicle. | | + +See Google's [official documentation](https://cloud.google.com/chronicle/docs/reference/ingestion-api)) for further details. + +## Configuration File + +If you are using a _Google Cloud Credentials File_, the following configuration is enough to get you started: + +```text +[INPUT] + Name dummy + Tag dummy + +[OUTPUT] + Name chronicle + Match * + customer_id my_customer_id + log_type my_super_awesome_type +```