# Ottieni lo stato della modalità attacco

`GET /v1/attack-protection/attack-mode` · autorizzazione `attack-protection:read`

Restituisce se l'ambiente è in modalità attacco e i periodi di modalità attacco iniziati negli ultimi 90 giorni o ancora aperti, dal più recente al più vecchio (al massimo 100; `more` indica che esistono periodi più vecchi in quella finestra).

Mentre l'ambiente è in modalità attacco, ogni passaggio con password e codice monouso richiede una sfida bot più severa, indipendentemente da ciò che dice `bot_protection.mode`. Passkey e accesso con social non vengono sottoposti a sfida. Un periodo si apre in uno di tre modi:

- `auto`: gli accessi falliti in una finestra di 5 minuti hanno superato la soglia di attivazione (il valore più alto tra 50 e dieci volte la mediana dell'ambiente). In modalità `log` di `credential_stuffing` il periodo viene registrato con `would_have: true` e non viene applicato nulla, a meno che la finestra non superi tre volte la soglia.
- `manual_customer`: l'hai attivata con [`activate`](activate-attack-mode.md).
- `manual_platform`: le operazioni di KeenAuth l'hanno attivata.

`active` è `true` solo mentre un periodo applicato (`would_have: false`) copre l'intero ambiente; in quel caso `active_until` è la fine più tardiva di quei periodi. Un periodo la cui fine è già passata ma che la pulizia non ha ancora chiuso risulta concluso a `ends_at`. Chi ha aperto un periodo manuale è nel log di audit di gestione, non in questa risposta.

## Risposta

`200 OK`

| Campo | Tipo | Descrizione |
|---|---|---|
| `active` | boolean | L'ambiente è in modalità attacco adesso. |
| `active_until` | string (date-time) o null | Quando termina la modalità attacco corrente, a meno che un periodo automatico non venga esteso; `null` quando `active` è `false`. |
| `periods[]` | array | Periodi, dal più recente al più vecchio. |
| `periods[].id` | string | Id del periodo, con prefisso `atm_`. |
| `periods[].scope` | string | `environment` oppure `org_domain`. |
| `periods[].org_domain` | string o null | Il dominio email dell'organizzazione di un periodo `org_domain`. |
| `periods[].trigger` | string | `auto`, `manual_customer` oppure `manual_platform`. |
| `periods[].would_have` | boolean | `true`: registrato in modalità `log`, non applicato. |
| `periods[].trigger_value` | integer o null | Tentativi falliti nella finestra di 5 minuti che hanno aperto un periodo `auto`; `null` per i periodi manuali. |
| `periods[].threshold` | integer o null | La soglia superata da quella finestra; `null` per i periodi manuali. |
| `periods[].started_at` | string (date-time) | Quando è iniziato il periodo. |
| `periods[].ends_at` | string (date-time) | Quando il periodo termina da solo. Un periodo `auto` viene esteso finché l'attacco continua. |
| `periods[].ended_at` | string (date-time) o null | Quando il periodo è terminato; `null` finché è aperto. |
| `more` | boolean | Esistono periodi più vecchi negli ultimi 90 giorni. |

```json
{
  "active": true,
  "active_until": "2026-10-20T10:00:00Z",
  "periods": [
    {
      "id": "atm_01jaz8m5c3f6t9w2y4b7d0g3k6",
      "scope": "environment",
      "org_domain": null,
      "trigger": "manual_customer",
      "would_have": false,
      "trigger_value": null,
      "threshold": null,
      "started_at": "2026-10-20T09:00:00Z",
      "ends_at": "2026-10-20T10:00:00Z",
      "ended_at": null
    }
  ],
  "more": false
}
```

## Errori

Ogni errore è un corpo `application/problem+json` con un `code` stabile.

| HTTP | `code` | Quando |
|---|---|---|
| 401 | `unauthenticated` | La chiave API manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La chiave non ha l'autorizzazione `attack-protection:read`. |
| 429 | `rate_limited` | È stato superato il limite di richieste; rispetta `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova più tardi. |

## Esempio

```bash
curl https://api.eu.keenauth.com/v1/attack-protection/attack-mode \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

CLI: `keenauth attack-protection attack-mode get`