> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wardforge.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Anti-Raid & Quarantine

> How WardForge detects coordinated bot raids and isolates suspicious new accounts automatically.

# Anti-Raid & Quarantine

Raid attacks — where dozens of bots flood a server simultaneously — are one of the most disruptive
threats a Discord community faces. WardForge's Anti-Raid engine combines **multi-window statistical
analysis**, **pattern recognition**, and a **24-hour quarantine system** to stop attacks before
they cause damage.

***

## TrustScore

Every account that joins your server receives a **TrustScore** — an algorithmic confidence score
from **0 to 100** that estimates how trustworthy the account is.

### How It's Calculated

| Factor                      | Weight    | Notes                                                      |
| --------------------------- | --------- | ---------------------------------------------------------- |
| Account age                 | High      | Accounts \< 7 days score significantly lower               |
| Username pattern similarity | Medium    | Shared prefixes with other recent joins = coordinated flag |
| Join timing                 | Medium    | Joining in a burst window reduces score                    |
| Previous ban in network     | Very High | Global blacklist hit = score drops to 0                    |
| Avatar presence             | Low       | Default avatar is a mild negative signal                   |

<Note>
  TrustScore is calculated locally — no data is sent to external services. The algorithm
  runs entirely inside WardForge's process using cached guild history.
</Note>

### Thresholds

| Score    | Status        | Action                    |
| -------- | ------------- | ------------------------- |
| 80 – 100 | ✅ Trusted     | Normal access             |
| 40 – 79  | ⚠️ Neutral    | Monitoring only           |
| 20 – 39  | 🟠 Suspicious | Logged; may trigger alert |
| 0 – 19   | 🔴 High Risk  | Flagged for staff review  |

***

## 24-Hour Account Quarantine

Any member whose account was **created less than 24 hours ago** is automatically placed in
**quarantine** upon joining — regardless of TrustScore.

### What Quarantine Does

1. The **`Guardian-Quarantine`** role is assigned to the member instantly
2. The role has **zero permissions** — the member cannot see or interact with any channel
3. The member receives a **private DM** explaining the situation and asking them to wait
4. A **staff embed** is posted in `#guardian-logs` with a one-click **"Release Quarantine"** button

```
🔒 New Member Quarantined
━━━━━━━━━━━━━━━━━━━━━━━
Member     : @username (123456789)
Account age: 4 hours, 12 minutes
Status     : Awaiting staff validation

[ ✅ Release Quarantine ]
```

### Releasing a Quarantined Member

Staff members with the **Manage Roles** permission can click the **"✅ Release Quarantine"**
button directly in the log channel. WardForge removes the quarantine role and grants normal access
immediately.

<Tip>
  New accounts aren't necessarily bots — they could be legitimate new users. The quarantine
  system is designed to be **transparent and fair**: the member knows why they're restricted and
  how to get released.
</Tip>

<Warning>
  If the **`Guardian-Quarantine`** role is **above** your regular member roles in the hierarchy,
  quarantine will not work. Use `/guardian doctor` to check hierarchy automatically.
</Warning>

***

## Multi-Window Raid Detection

WardForge monitors join events across **four simultaneous time windows**:

| Window                | Threshold | Purpose                    |
| --------------------- | --------- | -------------------------- |
| 10 seconds / 5 joins  | Burst     | Instant flood detection    |
| 30 seconds / 3 joins  | Short     | Fast sequential joins      |
| 2 minutes / 8 joins   | Medium    | Slower coordinated waves   |
| 10 minutes / 20 joins | Extended  | Sustained low-rate attacks |

When **any window** exceeds its threshold, WardForge evaluates the incoming cohort for coordination
signals.

### Coordination Detection

If more than **25%** of accounts in a burst window are \< 7 days old (or **40%** for older accounts),
WardForge flags the event as a **coordinated raid** and:

1. Sends an alert embed to `#guardian-logs`
2. Locks the server (pauses new joins or applies quarantine to all new arrivals)
3. Logs all involved account IDs for staff review

### False Positive Protection

* Windows use **independent counters** — a single spike won't permanently lock the server
* Counters reset automatically; a cleanup loop runs every 30 seconds
* Staff can manually release the lock at any time via the log embed button

***

## Configuration

WardForge's Anti-Raid module works out of the box with sensible defaults. Advanced tuning is
available via slash commands:

| Command                               | Description                                   |
| ------------------------------------- | --------------------------------------------- |
| `/antiraid mode [off\|monitor\|auto]` | Set detection mode                            |
| `/antiraid threshold [value]`         | Override the 10s burst threshold (default: 5) |
| `/trustscore [user]`                  | View a specific member's TrustScore breakdown |

<Note>
  Setting mode to `monitor` keeps all detection active but **never** automatically locks the
  server — it only alerts staff. This is useful during community events with many new members.
</Note>