# Audit Trail

The Exoscale Audit-Trail tracks all security relevant user activity and API
usage, allowing you to list the events that interact with the Exoscale resources.

## Terminology

* **Event**: User activities and API usage;
* **Mutations**: *Events* that will change any resource's state;
* **Short term Storage**: API/CLI request for *Mutations* with **30 days** retention;
* **Long term Storage**: Compressed JSON files, with *2 hours* window events, stored
  into one client's SOS bucket.

## Mutations and Short term Storage

All clients are served with the access, either via the
API [`/event`](https://community.exoscale.com/reference/api/audit-trail/event/#list-events) endpoint
, the [exoscale-cli]({{< ref "/tools/command-line-interface" >}})
, or the [Portal](https://portal.exoscale.com),
to all the *Mutations* that happened with their resources within the last **30 days**.

Example output with the [Portal](https://portal.exoscale.com/organization/audit-trail)

![](audit-trail.png "Audit Trail Window")


Example query with the exoscale-cli:

```bash
exo api list-events --from 2024-03-18T00:00:00 --to 2024-03-18T23:59:59
```

Output:

```json
[
    {
        "handler": "authenticate",
        "source-ip": "85.217.161.217",
        "message": "User user@exoscale.com: authenticate",
        "status": 200,
        "timestamp": "2024-03-18T14:27:17Z"
    },
    {
        "handler": "create session",
        "source-ip": "85.217.161.217",
        "message": "User user@exoscale.com: create session",
        "status": 200,
        "timestamp": "2024-03-18T14:51:54Z"
    },
    {
        "request-id": "d3a56d20-e537-11ee-a643-351cc382b6ff",
        "zone": "ch-gva-2",
        "body-params": {
            "template": { "id": "dbebea9b-db67-46b9-878c-aa9582e81177" },
            "public-ip-assignment": "inet4",
            "ssh-key": { "name": "ssh-key", "fingerprint": "7d:11:88:{...}:b7:86:d7" },
            "name": "super-instance",
            "disk-size": 50,
            "security-groups": [{ "id": "edece478-f019-4fa1-ab25-b5a547f252bf" }],
            "instance-type": { "id": "5e5fb3c6-e076-429d-9b6c-b71f7b27760b" },
            "anti-affinity-groups": []
        },
        "status": 200,
        "source-ip": "85.217.161.217",
        "iam-api-key": { "name": "my-api-key", "key": "EXObd2e2d17d088530077bfaa8a" },
        "uri": "/v2/instance",
        "elapsed-ms": 726,
        "timestamp": "2024-03-18T14:57:23Z",
        "handler": "create-instance",
        "message": "POST https://api-{...}.com/v2/instance [create-instance] status 200"
    },
    {
        "request-id": "e0c59070-e537-11ee-a643-351cc382b6ff",
        "zone": "ch-gva-2",
        "status": 200,
        "source-ip": "85.217.161.217",
        "iam-api-key": {
            "name": "my-api-key",
            "key": "EXObd2e2d17d088530077bfaa8a",
            "role-id": "0d91abf3-b4d7-4f40-a8dc-49301d778f25"
        },
        "iam-role": {
            "name": "my-role",
            "id": "0d91abf3-b4d7-4f40-a8dc-49301d778f25"
        },
        "uri": "/v2/instance/9a290148-af49-488e-9900-18cad0b8ac51:stop",
        "elapsed-ms": 72,
        "timestamp": "2024-03-18T14:57:45Z",
        "path-params": { "id": "9a290148-af49-488e-9900-18cad0b8ac51" },
        "handler": "stop-instance",
        "message": "PUT https://api-ch-gva-2.exo{...}51:stop [stop-instance] status 200"
    }
]
```

> [!NOTE]
> By default, the API returns events from the past 24 hours. To see further back in time, 
> [the API accepts `from` and `to` parameters](https://community.exoscale.com/reference/api/audit-trail/event/#list-events).

## General Events and Long term Storage

In case you are subscribed to one of the [advanced support plans](https://www.exoscale.com/support/),
every other relevant interaction with the Portal, CLI or API (e.g.: listing events)
will be packed together along with the *Mutations* and saved into (gzipped) compressed
JSON files.

These files will be daily uploaded into a bucket on your SOS account, which
is automatically created after the subscription, named in the form
`audit-trail-UUID` with the following structure:

```bash
[BUCKET]/[ORIGIN-ZONE]/[YEAR]/[MONTH]/[DAY]/exo.audit-trail.fct.full.[OPAQUE-IDENTIFIER].json.gz
```

```bash
exo storage list sos://audit-trail-0bf52c2d-61f8-361f-b7f8-6c5f813d3413
```

Output:
```bash 
2023-11-03 08:00:31 UTC 1 KiB at-vie-1/2023/11/03/exo.audit-trail.fct.full.0+5+0154505875.json.gz
2023-11-03 08:00:32 UTC 1 KiB at-vie-1/2023/11/03/exo.audit-trail.fct.full.0+5+0154556675.json.gz
2023-11-03 08:00:33 UTC 1 KiB at-vie-1/2023/11/03/exo.audit-trail.fct.full.0+5+0154573530.json.gz
2023-11-04 08:00:12 UTC 1 KiB at-vie-1/2023/11/04/exo.audit-trail.fct.full.0+5+0155319930.json.gz
2023-11-04 08:00:13 UTC 1 KiB at-vie-1/2023/11/04/exo.audit-trail.fct.full.0+5+0155370070.json.gz
```

Events hold enough information about the origin, owner and resource
they are referring to. Therefore, event shapes vary depending on the
entity they relate to.

> [!NOTE]
> Exoscale's Audit-Trail component only appends data to your SOS bucket. Although
> object sizes are unlikely to have significant billing impact, expiration of old
> data is left to you for scheduling according to your needs.