Sentinel Cog (Automod & Anti-Scam)

Vor Sentinel is Vör’s advanced automod and anti-scam system. It provides three independent but complementary layers of protection: a text-based automod rule engine, an image signature detector (with optional OCR), and a personal self-alert system for moderators. All three operate automatically on incoming messages.

Features

Text Automod

• Keyword and regex rule matching on message text
• Rules are grouped into named categories, each with its own punishment settings
• Two built-in rule types: @everyone/@here mention detection and message spam rate-limiting
• Zero-width character stripping and text normalization before matching (bypass-resistant)
• Hits are counted per user per category within a configurable time window; punishment triggers when the threshold is reached
• “Severe” mode on a category triggers instant punishment on the first hit
• Per-category controls: punishment type (none/timeout/mute/ban), punishment duration, delete message, warn user
• Specific channels can be excluded from all automod checks

Image Signature Detection

• Computes SHA-256 and perceptual hash (pHash) from uploaded images
• Compares against a per-server (and optionally synced cross-server) signature database
• Exact match via SHA-256; near-duplicate match via pHash distance threshold
• Detected images are reported to the configured sentinel alert channel
• A private “Scam Vault” thread is auto-created in the alert channel to store reference images

OCR Scanning (optional, requires Tesseract)

• Extracts text from images using Tesseract OCR
• Matches extracted text against a configurable global keyword list
• Rate-gated per user: requires a minimum number of images in unique channels within a time window before OCR runs
• Per-user cooldown prevents repeated OCR on the same user
• Default keyword list covers common phishing and scam patterns (can be customized)

Self-Alert System

• Moderators can register personal keyword or regex patterns
• When any message in the server matches, the moderator is sent a DM with the message and context
• Up to 25 active alerts per moderator per server

Configuration

Alert Channel (required)

Vor Sentinel requires a sentinel alert channel to be set in /config guild. Alerts for image detections and automod actions are posted there. Without it, image detection is silently skipped.

Automod Ignored Channels

You can exclude specific channels from text automod using /sentinel automod channels. Rules are still checked in all other channels.

Cog Config

Configure this cog through the config UI:

/config cog VorSentinel

Setting	Description
Automod Ignored Channels	Channels where text automod is skipped (also configurable directly with /sentinel automod channels)
Mod Action Result Channel	Where mute/ban confirmation messages from automod action buttons are posted. Defaults to the sentinel alert channel if not set.
Self-Alert Roles	Roles (in addition to Moderator+) that are allowed to use /sentinel selfalert commands. Useful for trusted community members who want personal keyword alerts.

Everything else is managed through the /sentinel command group directly.

Commands

All commands require at minimum Manage Messages permission (moderator or above), unless noted.

Automod: Categories

Categories group related rules together and define how violations are punished. Each category has its own threshold, window, and punishment settings.

Command	Description
/sentinel automod category list	List all categories and their settings
/sentinel automod category set <category> [options...]	Create or update a category’s settings
/sentinel automod category delete <category>	Delete a category (optionally moving or deleting its rules)

Category set options:

Option	Description
enabled	Enable or disable this category
severe	If true, punish on the very first hit (no threshold counting)
threshold	Number of hits within window_seconds before punishment triggers
window_seconds	Time window for hit counting
punishment_type	none, timeout, mute, or ban
punishment_duration	Duration string e.g. 10m, 1h, 7d, 0 for permanent
delete_message	Whether to delete the offending message
warn_user	Whether to warn the user in the channel

Automod: Rules

Rules are the actual patterns checked against message text. Each rule belongs to a category.

Command	Description
/sentinel automod rule list [category]	List rules (optionally filtered by category)
/sentinel automod rule show <rule_id>	View details of a specific rule
/sentinel automod rule add <pattern> [options...]	Add a new rule
/sentinel automod rule set <rule_id> [options...]	Enable/disable or move a rule to another category
/sentinel automod rule remove <rule_id>	Remove a rule

Rule add options:

Option	Description
pattern	Literal substring or regex pattern to match
builtin	Use a built-in rule type instead of a pattern (see below)
regex	Treat pattern as a regular expression
enabled	Whether to enable the rule immediately (default: true)
category	Category to assign the rule to (default: General)

Built-in rule types (use builtin instead of pattern):

Built-in	Behaviour
Mention Everyone/Here	Triggers when a message contains @everyone or @here
Message Spam	Triggers when a user sends messages too quickly (rate-based)

Automod: Ignored Channels

Command	Description
/sentinel automod channels list	List channels currently excluded from automod
/sentinel automod channels add <channel>	Exclude a channel from automod
/sentinel automod channels remove <channel>	Re-enable automod in a channel

Image Signatures

Command	Description
/sentinel add_image <image> [source]	Add an image to the signature database (stores SHA-256 and pHash)
/sentinel list [limit] [include_synced]	List stored signatures (paginated)
/sentinel remove <identifier>	Remove a signature by row ID, SHA-256, or pHash
/sentinel diagnose [image] [user]	Run OCR dependency and config diagnostics

Cross-Server Sync

Signature databases can be shared between trusted servers. Both sides must configure their end.

Command	Description
/sentinel sync add <guild_id>	Request to sync signatures from another server
/sentinel sync allow <guild_id>	Allow another server to sync from yours
/sentinel sync remove <guild_id>	Stop syncing from a server
/sentinel sync revoke <guild_id>	Revoke a server’s permission to sync from you
/sentinel sync list	View current sync sources and allowed servers

Self-Alerts (Moderator Personal Alerts)

Moderators can register personal keyword watches. Each match sends a DM with the message and jump link. Up to 25 alerts per server.

By default, only members with Moderator (or higher) permissions can use these commands. You can grant access to additional roles via the Self-Alert Roles cog config — useful for trusted community members who want keyword notifications without full moderator access.

Command	Description
/sentinel selfalert add <pattern> [regex]	Add a personal keyword or regex alert
/sentinel selfalert remove <alert_id>	Remove an alert by ID
/sentinel selfalert list	List all your current alerts in this server

OCR Configuration (Bot Admin only)

These commands require Bot Admin permission (not standard moderator).

Command	Description
/sentinel ocrgate show	View current OCR gate settings
/sentinel ocrgate set <window_seconds> <unique_channels> <min_images> [options...]	Update OCR gate thresholds
/sentinel ocrgate reset	Reset OCR gate to defaults
/sentinel ocrkeywords list	List all OCR keyword rules
/sentinel ocrkeywords add <keyword> [regex]	Add an OCR keyword
/sentinel ocrkeywords remove <keyword>	Remove an OCR keyword
/sentinel ocrkeywords reset	Reset OCR keywords to the built-in defaults

Help

Command	Description
/sentinel help	View all Vor Sentinel commands with descriptions

How It Works

Text Automod Flow

1. A message is received
2. Channels in the ignore list are skipped
3. Users with Manage Messages permission are skipped (moderators are exempt)
4. Message text is normalized: lowercased, zero-width characters stripped, punctuation collapsed
5. Each enabled rule is checked in turn, grouped by category
6. On a match, the hit counter for that user+category is incremented
7. If the counter exceeds the category threshold within the window (or the category is “severe”), punishment is applied
8. The offending message is deleted and/or the user is warned, depending on category settings
9. An alert is posted to the sentinel channel

Image Detection Flow

1. A message with image attachments is received
2. Each image is downloaded and its SHA-256 hash is computed
3. The hash is compared against the server’s signature database (and any synced databases)
4. If no exact SHA-256 match is found, a perceptual hash is computed and checked for near-duplicates (distance threshold)
5. On a match, an alert embed is posted to the sentinel channel with the matched image, source, and message details
6. If OCR is configured and the user passes the gate thresholds, the image is passed through Tesseract and extracted text is checked against OCR keywords
7. OCR matches also trigger an alert

OCR Gate

OCR is not run on every image. To prevent excessive processing and false positives, a user must exceed a gate threshold before OCR runs:

• The user must post at least min_images images
• Across at least unique_channels different channels
• Within window_seconds seconds
• A per-user cooldown prevents repeated OCR runs

This means OCR is targeted at users who are mass-posting images across multiple channels - a common scam pattern.

Duration Format

All punishment durations use the same format as the Moderation cog:

Format	Meaning
30s	30 seconds
10m	10 minutes
2h	2 hours
7d	7 days
2w	2 weeks
0	Permanent

Best Practices

1. Start with a “General” catch-all category with a threshold of 2-3 hits and timeout punishment; add stricter categories for known severe patterns
2. Use the severe flag sparingly - reserve it for zero-tolerance patterns like CSAM keywords or known scam URLs
3. Exclude high-volume bot output channels (e.g. logging channels) from automod to avoid false positives
4. Add images from confirmed scam incidents to the signature database immediately after handling them
5. Use self-alerts to monitor keywords relevant to your role without creating server-wide automod rules
6. Review the sentinel alert channel regularly - detections that are false positives indicate rules that need adjustment
7. Enable cross-server signature sync if you manage multiple related servers to share scam image databases