# 🛡️ Security Bot — Documentation

A self-hosted Discord security bot designed to stop raids, verify new members, protect server structure, and log all suspicious activity — automatically and in real time.

---

## 📋 Table of Contents

- [Features Overview](#features-overview)
- [Security Systems](#security-systems)
  - [Anti-Raid](#-anti-raid)
  - [Anti-Alts](#-anti-alts)
  - [Captcha Verification](#-captcha-verification)
  - [Link Spam Protection](#-link-spam-protection)
  - [Server Backup & Auto-Restore](#-server-backup--auto-restore)
  - [Global Ban System](#-global-ban-system)
  - [Bot Whitelist](#-bot-whitelist)
- [Commands Reference](#commands-reference)
- [Interactive Control Panel](#interactive-control-panel)
- [Permissions Required](#permissions-required)

---

## Features Overview

| Feature | What it does |
|---|---|
| **Anti-Raid** | Detects and bans attackers who spam channel/role creation, deletions, bans, kicks, webhooks, emojis, stickers, or events |
| **Auto-Restore** | Automatically rebuilds deleted channels and roles from a saved backup after a raid |
| **Anti-Alts** | Bans accounts younger than a configurable number of days from joining |
| **Captcha** | Makes new members solve a text captcha before they can access the server |
| **Link Spam** | Detects and punishes members who post Discord invites to other servers |
| **Global Ban** | Bans a user across every server the bot is in, simultaneously |
| **Security Logs** | Sends detailed embed logs to a designated channel for every security action |
| **Raid Webhook** |  Sends raid alerts to an external webhook URL (e.g. a private log server) |
| **Bot Whitelist** | Excludes trusted bots from all anti-raid checks |
| **Control Panel** | Full graphical panel with buttons — no need to remember commands |

---

## Security Systems

### 🚨 Anti-Raid

The core protection system. It monitors a set of actions per user and automatically bans anyone who exceeds a configurable threshold within a time window.

**Monitored actions:**

| Action | Default limit | Description |
|---|---|---|
| Channel creates | 5 | Creating channels too fast |
| Channel deletes | 5 | Deleting channels too fast |
| Channel edits | 10 | Renaming/modifying channels too fast |
| Role creates | 5 | Creating roles too fast |
| Role deletes | 5 | Deleting roles too fast |
| Bans | 3 | Issuing bans too fast |
| Kicks | 3 | Kicking members too fast |
| Webhooks | 3 | Creating webhooks too fast |
| Emojis (create) | 5 | Adding emojis too fast |
| Emojis (delete) | 5 | Deleting emojis too fast |
| Stickers (create) | 5 | Adding stickers too fast |
| Stickers (delete) | 5 | Deleting stickers too fast |
| Events (create) | 5 | Creating scheduled events too fast |
| Events (delete) | 5 | Deleting scheduled events too fast |

**How it works:**
1. Every action is tracked per user in a rolling time window (default: 10 seconds, configurable per limit)
2. When a user hits the limit, the bot immediately bans them and marks the server as **under attack**
3. While under attack, limits are halved and all audit log lookups skip their initial delay — every subsequent action is processed at maximum speed
4. After a ban, the bot automatically deletes the attacker's created channels/roles and triggers a full server restore from backup

**Rapid-event detection:** If 4 or more security events fire in the same server within 2 seconds, the bot automatically declares an attack in progress — even before any single limit is reached.

Each limit can have its own independent time window, configurable from the panel.

---

### 👶 Anti-Alts

Automatically bans new members whose Discord account was created less than X days ago.

- Configurable minimum account age (1–365 days)
- Fires the moment a new member joins
- Logs the action to the security log channel

---

### 🔐 Captcha Verification

When enabled, new members must solve a 6-character alphanumeric captcha to gain access to the server.

- A verification embed is sent to a designated channel when a member joins
- The member has a limited time to answer correctly
- On success, a configurable role is assigned to the member
- Failed attempts are logged

---

### 🔗 Link Spam Protection

Detects members posting Discord invite links (discord.gg, discord.com/invite) in any channel.

- Configurable threshold: how many invites are allowed before action is taken
- Configurable action: **kick** or **ban**
- Automatically deletes the spam messages from the last 50 messages in the channel
- Logs the action to the security channel

---

### 💾 Server Backup & Auto-Restore

The bot automatically creates and maintains a full snapshot of your server structure.

**Backup includes:**
- All channels (text, voice, categories) with names, topics, positions, NSFW flags, and permission overwrites
- All roles with names, colors, permissions, and positions
- Server name and icon

**Auto-restore:**
- After banning a raider, the bot automatically restores any channels or roles that were deleted during the attack
- Server name and icon are also restored if they were changed
- Backed up channels that already exist are never touched

**Manual commands:**
- `/force-backup` — Force an immediate backup right now
- `/load` — Restore your server from the latest backup

---

### 🌍 Global Ban System

Ban a user across **every server the bot is in** at once.

- Only available to bot administrators (whitelist)
- Cross-server bans are applied immediately on all servers
- New servers the bot joins will have the global ban applied automatically on member join
- A periodic sync (every 60 minutes) ensures banned users don't slip through

---

### 🤖 Bot Whitelist

Trusted bots added to the whitelist are completely excluded from all anti-raid detection. This prevents false positives from legitimate bots that perform bulk actions (e.g. setup bots, moderation bots).

---

## Commands Reference

All commands require **Administrator** permission unless noted.

### General

| Command | Description |
|---|---|
| `/panel` | Open the interactive security control panel |
| `/status` | View the current status of all security systems at a glance |

---

### Anti-Raid

| Command | Description |
|---|---|
| `/antiraid activar` | Enable the anti-raid system |
| `/antiraid desactivar` | Disable the anti-raid system |
| `/antiraid tiempo <seconds>` | Set the global detection time window (5–300s) |
| `/antiraid limite <type> <amount>` | Set the action limit for a specific type (`channels`, `roles`, `bans`, `kicks`) |

> **Tip:** Use `/panel` → Configure → Antiraid for a visual editor with per-limit time windows.

---

### Anti-Alts

| Command | Description |
|---|---|
| `/alts activar <days>` | Enable anti-alts, banning accounts younger than `<days>` days (1–365) |
| `/alts desactivar` | Disable anti-alts |

---

### Captcha

| Command | Description |
|---|---|
| `/captcha activar` | Enable captcha verification |
| `/captcha desactivar` | Disable captcha verification |
| `/captcha canal <channel>` | Set the channel where verification embeds are sent |
| `/captcha rol <role>` | Set the role assigned after passing verification |

---

### Link Spam

| Command | Description |
|---|---|
| `/linkspam set enabled:<true/false>` | Enable or disable link spam protection |
| `/linkspam set action:<ban/kick>` | Set the action taken when the threshold is exceeded |
| `/linkspam set threshold:<number>` | Set how many invites are allowed before action (1–50) |
| `/linkspam status` | View current link spam configuration |

---

### Security Logs

| Command | Description |
|---|---|
| `/logs canal <channel>` | Set the channel where security logs are sent |
| `/logs quitar` | Remove the configured log channel |

---

### Server Backup

| Command | Description |
|---|---|
| `/force-backup` | Force an immediate server backup |
| `/load` | Restore the server from the latest backup |

---

### Bot Whitelist

| Command | Description |
|---|---|
| `/whitelistbot agregar <bot>` | Add a bot to the whitelist |
| `/whitelistbot eliminar <bot>` | Remove a bot from the whitelist |
| `/whitelistbot lista` | View all whitelisted bots in this server |

---

### Global Ban *(Bot admins only)*

| Command | Description |
|---|---|
| `/globalban <user> [reason]` | Ban a user from all servers the bot is in |
| `/unglobalban <user> [reason]` | Remove a user from the global ban list |
| `/globalbans` | View the full global ban list |

---

### Admin Tools *(Bot admins only)*

| Command | Description |
|---|---|
| `/adminload listar` | List all available backups stored in the bot |
| `/adminload cargar <origin_id> [dest_id]` | Apply a backup from one server to another |
| `/serverlist` | View all servers the bot is in with invite links |
| `/roleadd <role>` | Assign a role to every member in the server |

---

## Interactive Control Panel

Run `/panel` to open the full graphical control panel.

```
┌──────────────────────────────────────────┐
│  🛡️ Security Panel — Your Server        │
├──────────────────────────────────────────┤
│  🛡️ Anti-Raid — Enabled    [Configure]  │
│  👶 Anti-Alts — Disabled   [Configure]  │
│  🔐 Captcha  — Enabled     [Configure]  │
│  🔗 Link Spam — Enabled    [Configure]  │
│  💾 Backup                 [Configure]  │
│  🌍 Global Bans            [Configure]  │
└──────────────────────────────────────────┘
```

Each section has its own sub-panel with buttons to toggle, configure limits, and set individual time windows — all without typing a single command.

The **Antiraid sub-panel** shows every limit in a vertical list with its own **✏️ Edit** button, giving you full per-limit control:

```
📁 Channels         lím: 5 · ⏱️ 10s   [✏️ Edit]
🗑️ Channel Deletes  lím: 5 · ⏱️ 10s   [✏️ Edit]
✏️ Channel Edits    lím: 10 · ⏱️ 15s  [✏️ Edit]
🎭 Roles            lím: 5 · ⏱️ 10s   [✏️ Edit]
...
```

---

## Permissions Required

The bot needs the following permissions in your server:

| Permission | Why |
|---|---|
| **Ban Members** | To ban raiders and alt accounts |
| **Kick Members** | For link spam kick action |
| **Manage Channels** | To delete raider channels and restore from backup |
| **Manage Roles** | To restore deleted roles from backup |
| **Manage Guild** | To restore server name and icon |
| **Manage Webhooks** | To delete raider-created webhooks |
| **View Audit Log** | To identify who performed each action |
| **Send Messages** | To send log embeds and captcha messages |
| **Manage Messages** | To delete link spam messages |
| **Read Message History** | To find and delete recent spam messages |

> The bot role should be **above** all other roles in the role list to be able to ban/kick users with those roles.


Nexus Shield

# 🛡️ Nexus Shield — Protección Total para tu Servidor

> *El sistema de seguridad multi-servidor más completo para Discord*

Nexus Shield に投票

私たちをサポートしませんか？