ZMN Bot Logo
    Documentation

    ZMN Bot Documentation

    Setup guides and configuration reference for every ZMN module — security, moderation, roles, leveling, and access control.

    Quick Navigation

    Basics
    Modules

    Security Module

    Advanced anti-nuke protection and real-time threat detection

    Overview

    The Security Module provides comprehensive protection against malicious attacks, raids, and unauthorized actions. It uses real-time monitoring with Redis-based rate limiting to detect and respond to threats within milliseconds.

    Protection Against:

    • • Mass bans, kicks, and role deletions
    • • Unauthorized bot additions
    • • Admin role grants and dangerous permissions
    • • Server vandalism (name, icon, vanity changes)
    • • Channel and role spam/deletion
    • • Mass mention spam

    Key Features

    Real-Time Detection

    Monitors all administrative actions with sub-second response time

    Rate Limiting

    Redis-based counters track actions within 60-second windows

    Instant Punishment

    Automatically ban, kick, or clear roles when threats are detected

    Bypass System

    Trusted roles can bypass security checks

    Alert Notifications

    DM designated roles when security events occur

    Detailed Logging

    Comprehensive logs with executor info, actions taken, and timestamps

    How It Works

    1Event Detection

    The bot monitors Discord audit logs and events in real-time, detecting administrative actions like bans, kicks, role changes, and server modifications.

    2Bypass Check

    Before taking action, the bot checks if the executor has a bypass role. Trusted administrators can be whitelisted to prevent false positives.

    3Rate Limit Check

    For limit-based protections, the bot increments a Redis counter and checks if the configured limit has been exceeded within a 60-second window.

    4Punishment & Logging

    If a threat is detected, the configured punishment is applied (ban, kick, or clear roles). A detailed log is sent to the log channel and alert roles are notified via DM.

    Protection Types

    Anti-Nuke Limits (Rate-Based)

    These protections trigger when a user performs too many actions within 60 seconds. Each has a configurable limit and action.

    Mass Bans

    Detects excessive member bans

    Default: 5 per minute
    Mass Kicks

    Detects excessive member kicks

    Default: 5 per minute
    Role Creation

    Detects rapid role creation

    Default: 5 per minute
    Role Deletion

    Detects mass role deletions

    Default: 5 per minute
    Channel Creation

    Detects rapid channel creation

    Default: 5 per minute
    Channel Deletion

    Detects mass channel deletions

    Default: 5 per minute
    Mass Mentions

    Detects spam mentions (@everyone, @here, role mentions)

    Default: 5 per minute

    Anti-Nuke Instant (Immediate Response)

    These protections trigger immediately on the first occurrence. No rate limiting - instant punishment.

    Bot Addition
    Premium

    Triggers when any bot is added to the server

    Admin Role Grant

    Triggers when admin role is given to a member

    Dangerous Permissions

    Triggers when dangerous permissions are granted

    Member Prune

    Triggers on server member prune actions

    Vanity URL Change
    Premium

    Triggers when server vanity URL is changed

    Server Rename

    Triggers when server name is changed

    Server Icon Change

    Triggers when server icon is changed

    Role Rename

    Triggers when a role is renamed

    Channel Rename

    Triggers when a channel is renamed

    Emoji Deletion

    Triggers when server emojis are deleted

    Emoji Rename

    Triggers when server emojis are renamed

    Invite Deletion

    Triggers when server invites are deleted

    Punishment Actions

    When a threat is detected, you can configure one of three punishment types:

    Ban

    Permanently bans the offending user from the server. This is the most severe action.

    Fallback: If bot lacks ban permissions, it will clear roles instead.

    Kick

    Removes the user from the server. They can rejoin with a new invite.

    Fallback: If bot lacks kick permissions, it will clear roles instead.

    Clear Roles

    Removes all dangerous roles (Administrator and MANAGE_* permissions) from the user. They remain in the server but lose privileges.

    Note: Only removes roles below the bot's highest role in hierarchy.
    For "Admin Role Grant" instant protection with clear-roles action, both the executor (who gave the role) and target (who received it) have their dangerous roles removed.

    Configuration

    General Settings

    Alert Roles

    roles

    Roles that receive DM notifications when security events occur

    Bypass Roles

    roles

    Trusted roles that bypass all security checks (use carefully!)

    Per-Protection Settings

    Each protection type can be configured individually:

    Enabled

    toggle

    Turn this specific protection on or off

    Limit (Limits Only)

    number

    Number of actions allowed within 60 seconds before triggering

    Action

    select

    Punishment to apply (ban, kick, or clear-roles)

    Log Channel

    channel

    Channel where detailed logs will be sent

    Bypass System

    The bypass system allows you to whitelist trusted administrators who should never trigger security protections.

    How Bypass Works:

    • • Users with bypass roles are completely exempt from all security checks
    • • No logs are generated for their actions
    • • No rate limiting counters are incremented
    • • No punishments are applied
    Important: Only assign bypass roles to highly trusted administrators. Users with bypass can perform unlimited actions without triggering any protections, making them potential security risks if compromised.

    Logging & Notifications

    Log Embeds Include:

    • • Executor: Who performed the action (with avatar)
    • • Target: Who was affected (for role grants, bans, etc.)
    • • Action Type: What punishment was applied
    • • Event Counter: Current count vs. limit (for rate-based)
    • • Roles Added/Removed: Detailed list of role changes
    • • Punishment Time: How long the punishment took to execute
    • • Timestamp: When the event occurred

    Alert Notifications

    When alert roles are configured and enabled, members with those roles receive DMs containing the same log embed sent to the log channel.

    Alert DMs are sent silently - if a user has DMs disabled, the bot will skip them without errors.

    Rate Limiting Details

    The security module uses Redis for distributed rate limiting with the following characteristics:

    60-Second Windows

    Each action increments a counter that expires after 60 seconds. This creates rolling windows for rate limiting.

    Per-User Tracking

    Counters are tracked per guild, per user, per event type. Each user has independent limits.

    Counter Reset

    When a punishment is applied, the counter is immediately cleared to prevent double-punishment.

    Warning Mode

    If the limit is not exceeded, a warning log is sent (orange color) without applying punishment. This helps monitor suspicious activity.

    Best Practices

    ✓ Recommended Setup

    • • Start with conservative limits (5-10 per minute) and adjust based on your server's needs
    • • Use "clear-roles" action initially to test without banning legitimate users
    • • Set up separate log channels for limits and instant protections
    • • Add your admin team to bypass roles to prevent false positives
    • • Enable alert roles for high-priority protections (bot-add, admin-grant)
    • • Test protections in a test server before enabling in production

    ✗ Common Mistakes

    • • Setting limits too low (can trigger on legitimate bulk actions)
    • • Not adding trusted admins to bypass roles
    • • Using "ban" action without testing first
    • • Forgetting to configure log channels (no visibility into events)
    • • Enabling all protections at once without gradual rollout

    Example Scenarios

    Scenario 1: Mass Ban Attack

    Situation: A compromised admin account starts banning members rapidly.

    Detection: After 5 bans in 60 seconds, the limit is exceeded.

    Action: Bot immediately bans the compromised account and logs the event.

    Result: Attack stopped after 5 bans instead of potentially hundreds.

    Scenario 2: Unauthorized Bot Addition

    Situation: Someone adds a malicious bot to the server.

    Detection: Bot-add instant protection triggers immediately.

    Action: Bot clears all dangerous roles from the person who added the bot.

    Result: Malicious bot is added but the attacker loses permissions to do further damage.

    Scenario 3: Admin Role Self-Grant

    Situation: A member gives themselves an admin role through an exploit.

    Detection: Admin-grant instant protection detects the role change.

    Action: Bot removes all dangerous roles from both the executor and target.

    Result: Exploit is neutralized and both parties lose elevated permissions.

    Technical Details

    System Architecture:

    • • Event Listeners: Individual event handlers for each protection type
    • • Redis Storage: Distributed counters with automatic expiration
    • • Audit Log Parsing: Extracts executor information from Discord audit logs
    • • Permission Checking: Validates bot permissions before applying punishments
    • • Fallback System: Automatically downgrades to clear-roles if ban/kick fails
    • • Response Time: Typically under 200ms from detection to punishment
    Bot Hierarchy Requirement: The bot's role must be positioned higher than all roles it needs to manage. If the bot's role is too low, it cannot remove roles from users or ban members with higher roles.