# Security & Audit Log

## Overview

WaDesk gives the platform owner two related tools: a Security Center (Admin → Security) where you set platform-wide security policy and reach the emergency controls, and the Audit Log (Admin → Audit log) which records every sensitive action across the platform. Both live in the admin sidebar.

The Security Center is organised as a set of policy cards (the "enforcement layers"), a stats strip, a risk-review queue, and a Super-Admin-only danger zone. Every setting ships with a sensible default, so a control you've never touched still behaves correctly until you change it.

## Security KPIs

The KPI strip at the top of the Security Center summarises the platform's current security posture. The numbers are computed live from the audit log and user table.

KPI | Meaning
--- | ---
Security score | A simple 0–100 score: ten key toggle controls, ten points each. Shows you what you have turned on and what is still off.
Open risks | Unresolved failure/warning audit rows in the last 7 days, with the high-priority (failure) count beneath.
Blocked attempts | Failed login attempts in the last 24 hours.
Campaign holds | Warning audit rows in the last 24 hours — sends paused by a guardrail.
2FA coverage | Percentage of admin-role users who have confirmed two-factor authentication.
Webhook failures | Failed webhook events as a percentage of all webhook events in the last 24 hours.

A Controls enabled card breaks coverage into four buckets — Admin access, WhatsApp abuse prevention, API hardening, and Incident readiness — each shown as a percentage of its toggles that are on.

## Risk Review Queue

The Risk items to review card lists the most recent failure and warning audit rows so you can triage incidents without leaving the page. Each item carries a severity derived from how recent and how serious it is:

- High — a failure within the last 24 hours.
- Medium — an older failure.
- Watch — a warning.

Each row shows the signal (the audit action), a short detail, the workspace it belongs to (or "Platform" for platform-layer events), and the actor who triggered it. For the full searchable history, open the Audit Log described below.

## Policy Forms (Enforcement Layers)

The bulk of the Security Center is a set of policy cards. Each card is a form; saving it stores your changes and writes a single audit-log entry listing exactly which fields changed (old value to new value).

### Login, sessions & 2FA

Setting | Default | What it does
--- | --- | ---
Require 2FA for admins / owners / all | Off | Force two-factor enrolment for the chosen audience (Super Admin, Admin, Support Admin).
Allowed 2FA methods | TOTP, Email | Which second factors users may enrol (TOTP, email, Telegram).
Session timeout (minutes) | 60 | Idle time before a session expires (5–1440).
Max concurrent sessions | 5 | How many active sessions one account may hold (1–50).
Remember me enabled | On | Whether the long-lived "remember me" cookie is allowed.
Lockout after failures / window | 5 in 15 min | Failed-login threshold and the window it is measured over.

### Password policy

Minimum length (default 8), require uppercase (on), require number (on), require symbol (off), and maximum password age in days (0 = never expires).

### WhatsApp guardrails & abuse filters

Setting | Default | What it does
--- | --- | ---
Max sends per minute / per day | 60 / 5000 | Hard caps on outbound message rate across the platform.
Hold on scam pattern | On | Pause a send that matches a known scam pattern.
Hold on links count | 3 | Pause messages that contain more than this many links.
Require template review | On | Templates must be reviewed before they can be used.
Block finance terms / short links | On / On | Anti-spam filters for high-risk financial wording and URL shorteners.
Blocked keyword list | empty | A custom block list (one keyword per line, also comma-separated).

### API, webhooks, devices & IP allowlist

API rate limit per minute (default 600), webhook signature required (on), webhook replay window in seconds (default 300), device trust required (off), logout devices after N inactive days (default 30), and an optional IP allowlist (enable plus a list of CIDR ranges).

### Login alerts & audit retention

Alert on new device (on), alert on new country (on), and the alert channel (email, whatsapp, or both). The Audit log retention (days) setting (default 365) controls how long audit rows are kept — set it to `0` to keep everything forever for compliance.

> Tip: The two list fields — blocked keywords and IP allowlist CIDRs — accept entries separated by new lines or commas. WaDesk trims, de-duplicates, and stores them as a clean list, so paste freely.

## Emergency Controls (Super Admin only)

At the bottom of the Security Center is the danger zone: Irreversible platform-wide actions. These five controls are limited to Super Admin only — even a regular Admin account that reaches the page is refused, and the denied attempt is recorded in the audit log showing who tried.

Action | Effect
--- | ---
Revoke ALL sessions | Logs out every user (including you). Everyone must sign in again.
Force password reset for ALL users | Flags every account to reset its password on next login.
Rotate ALL webhook secrets | Issues a fresh webhook secret for every workspace. Existing integrations must update.
Emergency stop sends | Blocks ALL outbound messages across the platform until you resume.
Resume sends | Lifts the emergency stop and lets messages flow again.

Every one of these actions is recorded in the audit log.

> Caution: These actions cannot be undone by a single click. Each button shows a confirmation prompt first. Emergency stop sends blocks every workspace until you press Resume, and Revoke ALL sessions will log out your own admin session too. Use them only during a genuine incident, and have your login details ready before you revoke sessions.

## The Audit Log

The Audit Log page is the permanent, searchable record of sensitive actions. Each row records the layer (platform or workspace), who did it, the action (for example a support reply or a deleted help article), the subject, the workspace, the IP and device/browser, extra details, and a result of Success, Failure, or Warning (colour-coded).

The page also shows summary counts (total rows, today, failures, platform events), the top actors over the last 7 days, an event mix by module, and a small review queue of recent failures/warnings. Click any row to open its full detail (who, which workspace, IP, device/browser, and the full details).

### Filtering

Filter by free-text search, event type (a dropdown built from the distinct actions in your data), result, layer, workspace, and a from/to date range. Dates must be valid calendar dates and the search text is capped and treated literally, so the filters cannot be abused to craft slow or wildcard queries.

### Retention

The audit log cleans itself up automatically: at most once a day, old rows beyond the retention window you set in the Security Center are removed (default 365 days; set it to `0` to keep everything forever). The cleanup runs in small batches, so even a large backlog never slows the page down.

## CSV Export

Use Export on the Audit Log to download the current filter as a CSV. The export honours the same event, result, and date filters as the on-screen list, so the file matches what you are looking at.

- The file is named `audit-log-YYYY-MM-DD-HHmmss.csv` and is downloaded in a streaming fashion, so even a very large log exports without running out of memory.
- It is saved in UTF-8 with a byte-order mark, so Excel opens it with the correct character encoding.
- It has a built-in spreadsheet safety guard: any cell that starts with `=`, `+`, `-`, or `@` is prefixed with an apostrophe, so spreadsheet apps treat it as plain text rather than running it as a formula.

> Note: The export applies the same checks on your filters as the on-screen page, so they can't be bypassed by tampering with the download link.

## Related Pages

- System Settings — where the WhatsApp provider secrets and webhook tokens are stored (encrypted at rest).
- AI & API Keys — the global AI credentials, also encrypted.