Skip to content

Commit

Permalink
chore: document upcoming audit log file changes
Browse files Browse the repository at this point in the history 
Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
  • Loading branch information
@markphelps
markphelps committed Jun 9, 2024
1 parent b50d1be commit ef27692
Show file tree
Hide file tree
Showing 3 changed files with 25 additions and 14 deletions.
20 changes: 14 additions & 6 deletions configuration/auditing/overview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,18 @@ title: Overview
description: This document describes Flipt's auditing capabilities.
---

Audit Events are pieces of data that describe a particular thing that has happened in a system. At Flipt, we provide the functionality of processing and batching these audit events and an abstraction for sending these audit events to a sink.
Audit Events are pieces of data that describe a particular thing that has happened in a system. Flipt provides the functionality of processing and batching these audit events and an abstraction for sending these audit events to a sink.

## Events

Flipt supports sending audit events to configured sinks. Audit events have the following structure:

```json
{
"version": "0.1",
"version": "0.2",
"type": "flag",
"action": "created",
"status": "success",
"metadata": {
"actor": {
"authentication": "none",
Expand All @@ -31,24 +32,25 @@ Flipt supports sending audit events to configured sinks. Audit events have the f
}
```

- `version` : the version of the audit event structure. We don't expect too many changes to the structure of the audit event
- `version` : the version of the audit event structure.
- `type` : the type of the entity being acted upon (flag, variant, constraint, etc.)
- `action` : the action taken upon the entity (created, deleted, updated, etc.)
- `metadata` : extra information related to the audit event as a whole. The `actor` field will always be present containing some identity information of the source which initiated the audit event
- `payload` : the actual payload used to interact with the `Flipt` server for certain auditable events
- `timestamp`: the time the event was created
- `status`: the status of the event (success, denied, etc.)

Currently, we support the following sinks for audit events:

- Log File: the audit events are JSON encoded and new-line delimited. You can find the configuration in the [Audit Events - Log File](/configuration/overview#audit-events-log-file) section of the Configuration documentation.
- [Log](/configuration/overview#audit-events-log): the audit events are output as either `json` or `console` depending on configuration. The default output is to STDOUT, however, the log sink can also be output to a file.

Check warning on line 45 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.So] Don't start a sentence with 'so '

Raw Output:
{"message": "[Openly.So] Don't start a sentence with 'so '", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 45, "column": 199}}}, "severity": "WARNING"}

- Webhook: the audit events are sent to a URL of your choice. You can find the configuration in the [Audit Events - Webhook](/configuration/overview#audit-events-webhook) section of the Configuration documentation.
- [Webhook](/configuration/overview#audit-events-webhook): the audit events are sent to a URL of your choice.

Check warning on line 47 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 47, "column": 91}}}, "severity": "WARNING"}

You can find [examples](https://github.com/flipt-io/flipt/tree/main/examples/audit) in the main GitHub repository on how to enable audit events and how to tune configuration for it.

## Event Filtering

Starting from [v1.27.0](https://github.com/flipt-io/flipt/releases/tag/v1.27.0), you can specify configuration for which events you would like to receive on your audit sink.
You can specify configuration for which events you would like to receive on your audit sink.

An always up to date list of events supported is available in our [GitHub repository](https://github.com/flipt-io/flipt/blob/main/internal/server/audit/README.md).

Expand All @@ -64,3 +66,9 @@ rollout:deleted
rule:deleted
*:updated
```

## Authentication / Authorization

Check warning on line 70 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Authentication / Authorization' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Authentication / Authorization' should be in sentence case", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 70, "column": 4}}}, "severity": "WARNING"}

If [authentication](/authentication) is enabled, the actor field will contain the identity information of the source which initiated the audit event. This information may contain the user's email, IP address, and other relevant information.

Check warning on line 72 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 72, "column": 66}}}, "severity": "WARNING"}

If [authorization](/authorization) is enabled, the audit event will contain the result of the authorization check in the `status` field. The status field will be set to `success` if the authorization check passed, and `denied` if the check failed. This information can be used to determine if an unauthorized user attempted to perform an action.

Check warning on line 74 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 74, "column": 64}}}, "severity": "WARNING"}

Check warning on line 74 in configuration/auditing/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "configuration/auditing/overview.mdx", "range": {"start": {"line": 74, "column": 155}}}, "severity": "WARNING"}
8 changes: 5 additions & 3 deletions configuration/auditing/webhooks.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ The value in the `X-Flipt-Webhook-Signature` header is the request body HMAC SHA

## Templates

Starting from [v1.28.0](https://github.com/flipt-io/flipt/releases/tag/v1.28.0), you can specify a template for the body of an Audit Event Webhook request.
You can specify a template for the body of an Audit Event Webhook request. This allows you to customize the body of the request to your webhook server.

A sample configuration can look something like this:

Expand All @@ -72,7 +72,7 @@ audit:
- url: https://example.com
headers:
Content-Type: application/json
Authorization: Bearer this-is-a-seret-token
Authorization: Bearer <token>
body: |
{
"type": "{{ .Type }}",
Expand All @@ -87,7 +87,9 @@ audit:
into JSON if it fits the structure.
</Note>

This configuration tells Flipt to send a `POST` request when events need to be emitted to the URL `https://example.com` with the HTTP headers, `Content-Type` and `Authorization`, and the body which is a [Go template](https://pkg.go.dev/text/template) that will be executed when an event comes in. The event structure looks like this:
This configuration tells Flipt to send a `POST` request when events need to be emitted to the URL `https://example.com` with the HTTP headers, `Content-Type` and `Authorization`, and the body which is a [Go template](https://pkg.go.dev/text/template) that will be executed when an event comes in.

Check warning on line 90 in configuration/auditing/webhooks.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "configuration/auditing/webhooks.mdx", "range": {"start": {"line": 90, "column": 1}}}, "severity": "WARNING"}

Check warning on line 90 in configuration/auditing/webhooks.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "configuration/auditing/webhooks.mdx", "range": {"start": {"line": 90, "column": 95}}}, "severity": "WARNING"}

Check warning on line 90 in configuration/auditing/webhooks.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "configuration/auditing/webhooks.mdx", "range": {"start": {"line": 90, "column": 257}}}, "severity": "WARNING"}

The event structure looks like this:

```go
type Event struct {
Expand Down
11 changes: 6 additions & 5 deletions configuration/overview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -351,12 +351,13 @@ export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
| audit.buffer.flush_period | Duration to wait before sending events to sinks | 2m | v1.21.0 |
| audit.events | Type of events user would like to receive on sinks | ["*:*"] | v1.27.0 |

#### Audit Events: Log File
#### Audit Events: Log

Check warning on line 354 in configuration/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Audit Events: Log' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Audit Events: Log' should be in sentence case", "location": {"path": "configuration/overview.mdx", "range": {"start": {"line": 354, "column": 6}}}, "severity": "WARNING"}

| Property | Description | Default | Since |
| ----------------------- | ------------------------------------------------------------------------ | ------- | ------- |
| audit.sinks.log.enabled | Enable log file sink | false | v1.21.0 |
| audit.sinks.log.file | File path to write audit events to. Required if log file sink is enabled | | v1.21.0 |
| Property | Description | Default | Since |
| ------------------------ | ---------------------------------------------------- | ------- | ------- |
| audit.sinks.log.enabled | Enable log sink | false | v1.21.0 |
| audit.sinks.log.file | File path to write audit events to instead of STDOUT | | v1.21.0 |
| audit.sinks.log.encoding | Encoding to use for logging (json, console) | inherit | v1.44.0 |

#### Audit Events: Webhook

Expand Down

0 comments on commit ef27692

Please sign in to comment.