Skip to content
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

Jump to bottom

chore: document upcoming audit log file changes #228

Merged
merged 2 commits into from
Jun 13, 2024
Merged

chore: document upcoming audit log file changes #228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef27692
chore: document upcoming audit log file changes
markphelps Jun 9, 2024
4776a17
Merge branch 'main' into doc-logs
markphelps Jun 13, 2024
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
20 changes: 14 additions & 6 deletions configuration/auditing/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,18 @@
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 @@
}
```

- `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 @@
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@

## 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 @@
- url: https://example.com
headers:
Content-Type: application/json
Authorization: Bearer this-is-a-seret-token
Authorization: Bearer <token>
body: |
{
"type": "{{ .Type }}",
Expand All @@ -86,7 +86,9 @@
input into JSON if it fits the structure.
</Tip>

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 89 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": 89, "column": 1}}}, "severity": "WARNING"}

Check warning on line 89 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": 89, "column": 95}}}, "severity": "WARNING"}

Check warning on line 89 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": 89, "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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -351,12 +351,13 @@
| 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
Loading