Respect media permissions and role hierarchy

Author: keepsloading

.env.example

@@ -3,6 +3,14 @@ MEMACT_GUILD_ID=
 MEMACT_DATABASE=memact_automod.db
 # MEMACT_STREAM_TITLE=Moderating this server
 # MEMACT_STREAM_URL=https://twitch.tv/discord
+# Optional server-specific Discord IDs. Defaults match the current Memact server.
+# MEMACT_BOT_JOIN_ROLE_ID=1485762440980336810
+# MEMACT_MEMBER_JOIN_ROLE_ID=1485762960851996822
+# MEMACT_ACTION_LOG_CHANNEL_ID=1485774247698890903
+# MEMACT_WELCOME_CHANNEL_ID=1485763966515941618
+# MEMACT_INTRO_CHANNEL_ID=1485764265989246996
+# MEMACT_TICKET_CHANNEL_ID=1486012638507827210
+# MEMACT_BLUESKY_RELAY_CHANNEL_ID=1490277253949558975
 # For JustRunMy.App, point this at persistent app storage if SQLite state
 # should survive Git deploys and restarts:
 # MEMACT_DATABASE=/data/memact_automod.db

README.md

@@ -47,6 +47,9 @@ This repository's source code is open source under the MIT license. See
   dictator references, protected-class slurs, untrusted external links,
   suspicious promos, unsolicited invites, URL shorteners, and repeated spam,
   including messages from installed bots/apps and webhooks
+- media-friendly moderation: normal image uploads, GIFs, stickers, embeds, and
+  attachment-only messages are allowed, while suspicious text links are still
+  evaluated
 - silent Sentinel detection for protected-class hate patterns, self-harm
   harassment, scam links, homoglyph domains, misleading markdown links,
   new-account bursts, and mention raids
@@ -59,7 +62,7 @@ This repository's source code is open source under the MIT license. See
 - rules management and rules embed posting
 - generic embed creation and reusable embed templates
 - member report, appeal, and ticket flows
-- optional Bluesky relay with automatic posting to a fixed Discord channel and
+- optional Bluesky relay with automatic posting to a configured Discord channel and
   moderator-picked reposts for older posts
 
 ## Setup
@@ -70,31 +73,35 @@ This repository's source code is open source under the MIT license. See
    including View Audit Log, Moderate Members, Manage Messages, Kick Members,
    Ban Members, Manage Roles, and Manage Channels.
 4. Copy `.env.example` to `.env` and fill in `MEMACT_TOKEN`.
-5. Install dependencies with `pip install -r requirements.txt`.
-6. Run the bot with `python main.py`.
-7. Run `/automod install` once in Discord to create or refresh native Memact
+5. If you are not running the current Memact server, set the optional
+   channel/role ID environment variables listed below so welcome, intro,
+   ticket, log, join-role, and Bluesky relay behavior points at your server.
+6. Install dependencies with `pip install -r requirements.txt`.
+7. Run the bot with `python main.py`.
+8. Run `/automod install` once in Discord to create or refresh native Memact
    Guard rules, including the hate-speech preset.
-8. Use `/security sentinel_recent` or `/security sentinel` to review silent
+9. Use `/security sentinel_recent` or `/security sentinel` to review silent
    risk intelligence after the bot has seen real traffic.
 
 ## Bluesky Relay
 
 The Bluesky relay is optional. When enabled, the bot can mirror posts from one
-public Bluesky account into the fixed Discord channel `1490277253949558975`.
+public Bluesky account into the configured relay channel. Memact's default
+relay channel is `1490277253949558975`, and other servers can override it with
+`MEMACT_BLUESKY_RELAY_CHANNEL_ID`.
 
 ### Setup
 
 1. Start the bot normally.
-2. Make sure the Discord server contains the text channel with ID
-   `1490277253949558975`.
+2. Make sure the Discord server contains the configured relay text channel.
 3. In Discord, run `/bluesky setup handle:<account>`.
 4. The bot saves the current latest Bluesky post as its sync point and starts
    auto-posting only new posts from that moment onward. The relay checks for
    new posts every five minutes.
 
 ### Moderator commands
 
-- `/bluesky view`: show the selected account, relay status, fixed relay
+- `/bluesky view`: show the selected account, relay status, configured relay
   channel, and last synced post
 - `/bluesky sync_now`: immediately catch up on posts that arrived while the
   bot was offline
@@ -118,6 +125,9 @@ In practice:
 - the bot does not warn members for ordinary profanity or casual keywords
 - GIFs, all-caps messages, memes, and normal chat are not judged by a custom
   keyword engine
+- image uploads, GIFs, stickers, embeds, and attachment-only messages are not
+  violations by themselves; if suspicious or untrusted links appear beside
+  that media, the links are still evaluated and can be deleted
 - native Discord AutoMod blocks spam, mention raids, hate-speech slur presets,
   and known scam-link patterns before they become moderation cases
 - Memact's local guard deletes public strong-profanity and offensive-reference
@@ -126,8 +136,9 @@ In practice:
 - protected-class slurs are hard-blocked locally with punctuation and leetspeak
   variants, so targeted racism does not depend only on Discord's native preset
 - public links use an allowlist-first posture: known safe hosts stay normal,
-  while unknown external links, shorteners, suspicious TLDs, invite spam, and
-  random-looking hosts are treated as spam-risk and logged
+  `memact.com` links stay allowed, while unknown external links, shorteners,
+  suspicious TLDs, invite spam, and random-looking hosts are treated as
+  spam-risk and logged
 - installed bots/apps and webhooks are moderated too, so compromised or spammy
   integrations cannot freely post abusive text, invite links, or promo scams
 - staff-only channels are treated with lighter friction for human moderators,
@@ -194,6 +205,15 @@ Recommended settings:
    - `MEMACT_BACKUP_DIR` (optional, recommended on persistent storage)
    - `MEMACT_BACKUP_INTERVAL_HOURS` (optional, default `12`)
    - `MEMACT_BACKUP_RETENTION` (optional, default `14`)
+   - `MEMACT_BOT_JOIN_ROLE_ID` (optional, defaults to Memact's bot role)
+   - `MEMACT_MEMBER_JOIN_ROLE_ID` (optional, defaults to Memact's member role)
+   - `MEMACT_ACTION_LOG_CHANNEL_ID` (optional, defaults to Memact's action log)
+   - `MEMACT_WELCOME_CHANNEL_ID` (optional, defaults to Memact's welcome
+     channel)
+   - `MEMACT_INTRO_CHANNEL_ID` (optional, defaults to Memact's intro channel)
+   - `MEMACT_TICKET_CHANNEL_ID` (optional, defaults to Memact's ticket channel)
+   - `MEMACT_BLUESKY_RELAY_CHANNEL_ID` (optional, defaults to Memact's Bluesky
+     relay channel)
 6. Start the app and watch the JustRunMy.App logs until the bot prints that it
    logged in and synced commands.
 7. Run `/automod install` after the bot is online if Discord native AutoMod
@@ -205,6 +225,15 @@ Important JustRunMy.App notes:
   the optional `/healthz` endpoint.
 - Keep secrets such as `MEMACT_TOKEN` in JustRunMy.App environment variables,
   not in `.env`.
+- Server-specific IDs are normal runtime environment variables. Defaults match
+  the current Memact server, but other servers should configure them explicitly.
+- If GitHub Actions is used for deployment, store sensitive deployment values as
+  GitHub Secrets and inject them into the deployment/runtime environment; the
+  bot code reads only normal environment variables.
+- You can enable Discord permissions for everyone to send images, GIFs,
+  stickers, and embeds. Memact Guard will leave media-only messages alone while
+  still filtering scam, invite, shortener, suspicious-domain, promo-link, and
+  spam links found in message text.
 - Use the dashboard logs, web shell, and auto-restart controls for debugging
   and recovery.
 - For durable SQLite data, set `MEMACT_DATABASE` to a path that lives on

bot.py

@@ -10,6 +10,7 @@
 
 from config import ACTION_LOG_CHANNEL_ID, EMBED_COLOR, Settings
 from db import Database
+from utils.checks import bot_can_act_on_member, log_bot_action_blocked
 from utils.time import format_timedelta, to_iso, utcnow
 from utils.ui import build_embed, safe_dm
 
@@ -267,8 +268,30 @@ async def apply_warning(
         bot_user = self.user or moderator
         escalation: str | None = None
 
-        if total_points >= config["warn_ban_threshold"] and member.bannable:
-            await member.ban(reason=f"Auto-ban after warnings: {reason}", delete_message_seconds=0)
+        if total_points >= config["warn_ban_threshold"]:
+            can_ban, block_reason = bot_can_act_on_member(member, action="automatic ban", required_permission="ban_members")
+            if not can_ban or not member.bannable:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic ban",
+                    target=member,
+                    reason=block_reason or "Discord reports this member is not bannable.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
+            try:
+                await member.ban(reason=f"Auto-ban after warnings: {reason}", delete_message_seconds=0)
+            except (nextcord.Forbidden, nextcord.HTTPException) as error:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic ban",
+                    target=member,
+                    reason=f"Discord rejected the ban: {type(error).__name__}.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
             escalation = "ban"
             case_id = await self.add_case(
                 guild.id,
@@ -291,8 +314,30 @@ async def apply_warning(
                 description=f"{member.mention} was banned automatically after warning escalation.",
                 fields=[("Case", str(case_id), True), ("Warning Points", str(total_points), True)],
             )
-        elif total_points >= config["warn_kick_threshold"] and member.kickable:
-            await member.kick(reason=f"Auto-kick after warnings: {reason}")
+        elif total_points >= config["warn_kick_threshold"]:
+            can_kick, block_reason = bot_can_act_on_member(member, action="automatic kick", required_permission="kick_members")
+            if not can_kick or not member.kickable:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic kick",
+                    target=member,
+                    reason=block_reason or "Discord reports this member is not kickable.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
+            try:
+                await member.kick(reason=f"Auto-kick after warnings: {reason}")
+            except (nextcord.Forbidden, nextcord.HTTPException) as error:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic kick",
+                    target=member,
+                    reason=f"Discord rejected the kick: {type(error).__name__}.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
             escalation = "kick"
             case_id = await self.add_case(
                 guild.id,
@@ -316,9 +361,31 @@ async def apply_warning(
                 fields=[("Case", str(case_id), True), ("Warning Points", str(total_points), True)],
             )
         elif total_points >= config["warn_timeout_threshold"]:
+            can_timeout, block_reason = bot_can_act_on_member(member, action="automatic timeout", required_permission="moderate_members")
+            if not can_timeout:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic timeout",
+                    target=member,
+                    reason=block_reason or "Discord role hierarchy blocked the timeout.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
             timeout_minutes = max(1, int(config["warn_timeout_minutes"]))
             duration = timedelta(minutes=timeout_minutes)
-            await member.edit(timeout=duration, reason=f"Auto-timeout after warnings: {reason}")
+            try:
+                await member.edit(timeout=duration, reason=f"Auto-timeout after warnings: {reason}")
+            except (nextcord.Forbidden, nextcord.HTTPException) as error:
+                await log_bot_action_blocked(
+                    self,
+                    guild,
+                    action="automatic timeout",
+                    target=member,
+                    reason=f"Discord rejected the timeout: {type(error).__name__}.",
+                    fields=[("Warning Points", str(total_points), True)],
+                )
+                return case_id, total_points, None
             escalation = "timeout"
             case_id = await self.add_case(
                 guild.id,
@@ -394,6 +461,21 @@ async def process_due_actions(self) -> None:
                     except (nextcord.Forbidden, nextcord.HTTPException):
                         continue
                 if member is not None:
+                    can_untimeout, block_reason = bot_can_act_on_member(
+                        member,
+                        action="scheduled timeout removal",
+                        required_permission="moderate_members",
+                    )
+                    if not can_untimeout:
+                        await log_bot_action_blocked(
+                            self,
+                            guild,
+                            action="scheduled timeout removal",
+                            target=member,
+                            reason=block_reason or "Discord role hierarchy blocked the timeout removal.",
+                        )
+                        self.db.delete_scheduled_action(action["id"])
+                        continue
                     try:
                         await member.edit(timeout=None, reason=reason)
                     except (nextcord.Forbidden, nextcord.HTTPException):

cogs/automod.py

@@ -10,7 +10,14 @@
 
 from bot import MemactAutoModBot
 from config import ACTION_LOG_CHANNEL_ID, BOT_JOIN_ROLE_ID, COMMAND_GUILD_IDS, INTRO_CHANNEL_ID, MEMBER_JOIN_ROLE_ID, WELCOME_CHANNEL_ID
-from utils.checks import is_moderator_member, require_admin
+from utils.checks import (
+    bot_can_act_on_member,
+    bot_can_delete_message,
+    bot_can_manage_role,
+    is_moderator_member,
+    log_bot_action_blocked,
+    require_admin,
+)
 from utils.content_guard import GuardDecision, evaluate_guard_message
 from utils.sentinel import SentinelDecision, content_hash, evaluate_message
 from utils.ui import build_embed, send_interaction
@@ -248,6 +255,18 @@ async def _assign_join_role(self, member: nextcord.Member, role_id: int) -> bool
             return False
         if role in member.roles:
             return True
+        can_assign_role, role_reason = bot_can_manage_role(member.guild, role)
+        can_edit_member, member_reason = bot_can_act_on_member(member, action="assign join role", required_permission="manage_roles")
+        if not can_assign_role or not can_edit_member:
+            await log_bot_action_blocked(
+                self.bot,
+                member.guild,
+                action="assign join role",
+                target=member,
+                reason=role_reason or member_reason or "Discord role hierarchy blocked join role assignment.",
+                fields=[("Role", role.mention, True)],
+            )
+            return False
         try:
             await member.add_roles(role, reason="Automatic join role assignment.")
         except (nextcord.Forbidden, nextcord.HTTPException) as error:
@@ -450,11 +469,15 @@ async def _run_guard(self, message: nextcord.Message, config: dict) -> bool:
         deleted = False
         deletion_error: str | None = None
         if decision.should_delete:
-            try:
-                await message.delete()
-                deleted = True
-            except (nextcord.Forbidden, nextcord.HTTPException) as error:
-                deletion_error = f"{type(error).__name__}: {error}"
+            can_delete, block_reason = bot_can_delete_message(message)
+            if not can_delete:
+                deletion_error = block_reason or "Discord role hierarchy blocked message deletion."
+            else:
+                try:
+                    await message.delete()
+                    deleted = True
+                except (nextcord.Forbidden, nextcord.HTTPException) as error:
+                    deletion_error = f"{type(error).__name__}: {error}"
 
         event_id = self.bot.db.add_sentinel_event(
             message.guild.id,
@@ -596,6 +619,17 @@ async def on_member_join(self, member: nextcord.Member) -> None:
             return
 
         reason = f"Account younger than required minimum of {required_hours} hours."
+        can_kick, block_reason = bot_can_act_on_member(member, action="join screen kick", required_permission="kick_members")
+        if not can_kick or not member.kickable:
+            await log_bot_action_blocked(
+                self.bot,
+                member.guild,
+                action="join screen kick",
+                target=member,
+                reason=block_reason or "Discord reports this member is not kickable.",
+                fields=[("Age Hours", f"{age_hours:.2f}", True), ("Required Hours", str(required_hours), True)],
+            )
+            return
         try:
             await member.kick(reason=reason)
         except (nextcord.Forbidden, nextcord.HTTPException):

cogs/bluesky.py

@@ -386,7 +386,7 @@ async def post_manual_selection(
         if channel is None:
             await send_interaction(
                 interaction,
-                content=f"The fixed Bluesky relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found.",
+                content=f"The configured Bluesky relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found.",
                 ephemeral=True,
             )
             return
@@ -464,7 +464,7 @@ async def view(self, interaction: nextcord.Interaction) -> None:
         )
         await send_interaction(interaction, embed=embed)
 
-    @bluesky.subcommand(description="Set which Bluesky account should auto-post into the fixed relay channel")
+    @bluesky.subcommand(description="Set which Bluesky account should auto-post into the configured relay channel")
     async def setup(
         self,
         interaction: nextcord.Interaction,
@@ -478,7 +478,7 @@ async def setup(
         if relay_channel is None:
             await send_interaction(
                 interaction,
-                content=f"The fixed relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found in this server.",
+                content=f"The configured relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found in this server.",
                 ephemeral=True,
             )
             return
@@ -625,7 +625,7 @@ async def history(self, interaction: nextcord.Interaction) -> None:
         if relay_channel is None:
             await send_interaction(
                 interaction,
-                content=f"The fixed relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found in this server.",
+                content=f"The configured relay channel `{BLUESKY_RELAY_CHANNEL_ID}` was not found in this server.",
                 ephemeral=True,
             )
             return