🛡️ 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
• Security Systems
  • Anti-Raid
  • Anti-Alts
  • Captcha Verification
  • Link Spam Protection
  • Server Backup & Auto-Restore
  • Global Ban System
  • Bot Whitelist
• Commands Reference
• Interactive Control Panel
• 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.