Skip to content

README.md

Latest commit

 

History

History
86 lines (62 loc) · 2.75 KB

README.md

File metadata and controls

86 lines (62 loc) · 2.75 KB
Raw

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