Discord Guard Bot · v3.0.0

Cache-first Discord security bot backed by MariaDB. Built on discord.js v14 with audit-log-aware automation for anti-abuse workloads.

Designed for guarding one guild or a small handful; cross-shard scale requires intentional sharding and per-shard pools.

Features

• Cache-first reads — guild settings live in RAM; MariaDB persists asynchronously.
• Audit-driven routing — GuildAuditLogEntryCreate catches fast webhook/integration paths.
• Modular interception — channels, roles, webhooks, vanity, bots, bans toggled independently.
• Sanctions — ban / kick / strip with explicit outcomes (protected, forbidden, …).
• Snapshots — backup and restore guild layout with rate-limit aware spacing.
• Vanity safeguards — only the Discord-transfer guild owner may change vanity; env owner list is ignored for vanity.
• Operational polish — per-guild settings mutexes, bounded discord.js caches, batched audit logs.

Getting started

npm install

Copy .env.example to .env and populate secrets (DISCORD_TOKEN, CLIENT_ID, OWNER_ID, database connection, …).

Apply schema:

npm run db:init

Register slash commands:

npm run deploy

Run:

npm start       # production
npm run dev     # node --watch

When COMMAND_ALLOWED_USER_IDS is populated, slash commands default to hidden (setDefaultMemberPermissions('0')); finalize visibility inside Server Settings → Integrations and rely on runtime checks as a second barrier.

Slash commands

Command	Purpose
/config show	Status: modules, thresholds, ledger size, websocket ping
/config toggle	Toggle a guard module
/config punishment	Default sanction mode
/config threshold	Rapid-action window tuning
/config enable	Master toggle
/snapshot create/list/restore/delete	Structural backups

Layout

src/
  index.js                # bootstrap & process lifecycle
  config.js               # env validation
  structures/             # Guard client + MariaDB facade
  handlers/               # dynamic command/event loaders
  events/                 # gateway listeners
  utils/                  # permissions, sanctioning, auditing helpers
schema.sql                # DDL

Quality

npm run lint
npm run lint:fix

Production checklist

• Rotate leaked tokens promptly and scrub git history when needed.
• Grant the bot minimal permissions (Manage Channels/Roles/Webhooks, Ban, Kick, View Audit Log rather than Administrator when possible).
• Scope database grants to explicit DML privileges for the deployment database only.
• Stream logs with LOG_FORMAT=json into your observability stack.

License

MIT