# Obtener el estado del modo de ataque

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

Devuelve si el entorno está en modo de ataque y los periodos de modo de ataque que comenzaron en los últimos 90 días o que siguen abiertos, del más reciente al más antiguo (como máximo 100; `more` indica que existen periodos más antiguos dentro de ese intervalo).

Mientras el entorno esté en modo de ataque, cada paso de contraseña y de código de un solo uso exige un desafío de bot más estricto, independientemente de lo que indique `bot_protection.mode`. El inicio de sesión con clave de acceso y con redes sociales no se somete a desafío. Un periodo se abre de una de tres formas:

- `auto`: los inicios de sesión fallidos en una ventana de 5 minutos superaron el umbral de activación (el mayor entre 50 y diez veces la mediana del entorno). En modo `log` de `credential_stuffing`, el periodo se registra con `would_have: true` y no se aplica nada, salvo que la ventana supere tres veces el umbral.
- `manual_customer`: lo activó usted con [`activate`](activate-attack-mode.md).
- `manual_platform`: lo activaron las operaciones de KeenAuth.

`active` es `true` solo mientras un periodo aplicado (`would_have: false`) cubra todo el entorno; en ese caso, `active_until` es el fin más tardío de esos periodos. Un periodo cuyo fin ya pasó, pero que la limpieza todavía no ha cerrado, aparece como finalizado en `ends_at`. Quién abrió un periodo manual consta en el registro de auditoría de gestión, no en esta respuesta.

## Respuesta

`200 OK`

| Campo | Tipo | Descripción |
|---|---|---|
| `active` | boolean | El entorno está ahora en modo de ataque. |
| `active_until` | string (date-time) o null | Cuándo termina el modo de ataque actual, salvo que se prolongue un periodo automático; `null` cuando `active` es `false`. |
| `periods[]` | array | Periodos, del más reciente al más antiguo. |
| `periods[].id` | string | Identificador del periodo, con el prefijo `atm_`. |
| `periods[].scope` | string | `environment` u `org_domain`. |
| `periods[].org_domain` | string o null | El dominio de correo electrónico de la organización de un periodo `org_domain`. |
| `periods[].trigger` | string | `auto`, `manual_customer` o `manual_platform`. |
| `periods[].would_have` | boolean | `true`: registrado en modo `log`, no aplicado. |
| `periods[].trigger_value` | integer o null | Intentos fallidos en la ventana de 5 minutos que abrieron un periodo `auto`; `null` en periodos manuales. |
| `periods[].threshold` | integer o null | El umbral que superó esa ventana; `null` en periodos manuales. |
| `periods[].started_at` | string (date-time) | Cuándo comenzó el periodo. |
| `periods[].ends_at` | string (date-time) | Cuándo termina el periodo por sí mismo. Un periodo `auto` se prolonga mientras continúe el ataque. |
| `periods[].ended_at` | string (date-time) o null | Cuándo terminó el periodo; `null` mientras siga abierto. |
| `more` | boolean | Existen periodos más antiguos en los últimos 90 días. |

```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
}
```

## Errores

Cada error es un cuerpo `application/problem+json` con un `code` estable.

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `unauthenticated` | La clave de API falta, no es válida o ha sido revocada. |
| 403 | `insufficient_permissions` | La clave no tiene el permiso `attack-protection:read`. |
| 429 | `rate_limited` | Se superó el límite de frecuencia; respete `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente más tarde. |

## Ejemplo

```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`