# Work through incidents

How BetterShield joins related access and file changes into incidents, and how to read a timeline, prepare a response and mark an incident handled.

An incident groups recorded changes that line up, such as a new administrator and a new PHP file on the same day. Find incidents under **BetterShield › Activity › Incidents**. An incident is a correlation, not a verdict: it does not identify malware or intent, and alerts carry on as usual.

## How changes become an incident

Only these records can open an incident (the screen calls them anchors):

- the decoy credential being used;
- a new privileged account, or a new application password on one;
- an account given a privileged role;
- a new PHP file in WordPress core, a plugin, a theme, a must-use plugin or a drop-in.

Supporting evidence joins an open incident but never opens one: for example a changed PHP file, a weakened sign-in or two-factor policy, an undone fix, a changed key setting, a dormant privileged account signing in, or one account's email, password and application password all changing within an hour.

A record joins an open incident when it falls within 24 hours of one of its anchors, or shares its recorded account, user or file. Correlation runs soon after a relevant change and hourly; **Refresh evidence** runs it now.

## Open and handled incidents

Four figures head the screen: **Open** (or **Handled**), **Evidence**, **Last correlation** and **Waiting**, which says whether saved records are still to be processed. Below them, switch between **Open** and **Handled**.

Each incident is titled by how strongly its records connect:

| Title | Meaning |
|---|---|
| **Decoy credential was used** | The decoy application password was used. |
| **Multiple access changes share a recorded actor** | One account made two or more of the anchoring changes. |
| **Signals fit a pattern** | More than one record has joined. |
| **Worth reviewing** | One record so far. |

Each also shows its number, anchor and evidence counts, and **Acknowledged** once acknowledged.

| Action | What it does |
|---|---|
| **Acknowledge** | Notes that you have seen a new incident. It stays under **Open**. |
| **Mark handled** | Moves it to **Handled**. A response never does this for you, and a handled incident cannot be reopened. |
| **Review timeline** | Opens the incident. **Hide timeline** closes it. |

## The timeline

Records run oldest first, each with its time and evidence number, what happened, the recorded account (or that the actor is unknown), how it joined, the network, and any file path. **Everything this account did** opens that account's activity. Twenty records show at first; **Show all** and **Load more evidence** bring the rest.

**Related activity** opens the activity log for the incident's days: **Everything in these days**, or the same days for one account or network.

### Explain this incident

With WordPress 7.0 or newer and an AI provider connected under **Settings › Connectors**, **Explain this** writes three short paragraphs, each sentence citing evidence numbers. Only redacted evidence is sent (the first 30 records, without account names, real account IDs, paths, credentials or request contents), and **Review exactly what will be sent** shows it first. The AI cannot act.

## Prepare a response

1. Click **Prepare response plan**. BetterShield lists actions drawn from the evidence; nothing changes yet.
2. Tick the actions you want. One that cannot run shows **Refused:** and why.
3. Click **Apply selected actions** and confirm, with your password if **Ask for my password before an action that removes a protection** is on.
4. **After the response** re-checks each target and runs the audit, marking lines **Still open**, **Not open**, **Not done**, **Yours to do** or **Not checked**. **Check again** repeats it.

| Action | Can be undone |
|---|---|
| Remove an account's site roles and individual capabilities | Yes, if the account has not changed since |
| Require a new password at the account's next password sign-in (WordPress sends its reset email) | Yes |
| End all of an account's sessions | No |
| Revoke its application passwords created in the incident window, 24 hours either side | No |
| Put back the checksum-verified published copy of a changed core or plugin file | Yes, while that file is unchanged |
| Move any other file's contents to quarantine, leaving an inert placeholder | Yes, while the placeholder is unchanged |
| Unschedule one unanswered scheduled hook | Yes, though it may then run at once |

A plan never targets your own account or the last administrator, never deletes files and never rotates sign-in keys. It covers at most 20 actions and five accounts. Applying or undoing needs a working recovery link or printed recovery codes, and safe mode off. A plan expires after 10 minutes or when the incident changes, and works only in the sign-in session that made it: **Prepare a fresh plan** to act again. **Undo this action** reverses one action; **Response plan history** keeps your earlier plans and their undo.

## How long incidents are kept

Open incidents and their evidence are never removed. A handled incident is removed 30 days after you mark it handled, or 180 days (Ultra).

## What Ultra adds

- Each timeline opens with how many incidents the site recorded in the last 180 days, and how many share a recorded account with this one.
- **Draft a summary for my client** writes a plain-language draft for you to review, with **Download draft with evidence**.
- No hourly limit on explanations. Without Ultra, one account can request 20 an hour.
- On multisite, an **Incidents** tab beside the network's **Activity** lists each site's open incidents, ten sites at a time.
- **Automatic incident response**, under **Ultra › Automatic response**: tick action types (removing roles, ending sessions, revoking application passwords, unscheduling unanswered hooks) and click **Save incident response policy**. Each hour it takes one incident with at least two anchors and applies up to three of those actions as the account that saved it. Ending sessions and revoking passwords cannot be undone. It never changes files or keys, pauses in safe mode or without a recovery method, and ignores incidents opened before you saved. A mistaken correlation can lock a colleague out.

## Related

- [Activity log](/docs/activity-log/)
- [File changes](/docs/file-changes/)
- [Automatic response](/docs/automatic-response/)
- [Locked out](/docs/locked-out/)
- [Multisite networks](/docs/multisite-network/)