Skip to content

Instantly share code, notes, and snippets.

@chofstede
Last active September 13, 2026 16:48
Show Gist options
  • Select an option

  • Save chofstede/a422427570004719196cde948521dd04 to your computer and use it in GitHub Desktop.

Select an option

Save chofstede/a422427570004719196cde948521dd04 to your computer and use it in GitHub Desktop.
Mastodon Abuse Filter based on Username RegEx

Mastodon: Blocking Automated Signup Abuse with a Custom Username Validator

I recently had a wave of automated account registrations on a Mastodon instance where all generated usernames followed the same predictable pattern:

bp0123456789abcdef

In this case, blocking VPN providers or entire IP ranges turned out to be far too broad. A much cleaner workaround was to reject the abusive username pattern directly during Mastodon's normal account validation.

This is a local source modification, so it will need to be carried forward when upgrading Mastodon.

  1. Add a custom validator

Create:

app/validators/username_abuse_validator.rb

with:

# frozen_string_literal: true

class UsernameAbuseValidator < ActiveModel::EachValidator
  BLOCKED_PATTERNS = [
    /\Abp[0-9a-f]{16}\z/i,
  ].freeze

  def validate_each(record, attribute, value)
    return if value.blank?
    return unless BLOCKED_PATTERNS.any? { |pattern| value.match?(pattern) }

    record.errors.add(attribute, :invalid)
  end
end

The example above rejects usernames consisting of:

the prefix bp followed by exactly 16 hexadecimal characters

Examples that would be rejected:

bp0123456789abcdef
bpDEADBEEFCAFEBABE

Normal usernames remain unaffected.

Additional abusive patterns can simply be added to BLOCKED_PATTERNS:

BLOCKED_PATTERNS = [
  /\Abp[0-9a-f]{16}\z/i,
  /\Aanother_bad_pattern_[0-9]+\z/i,
].freeze
2. Attach the validator to local account creation

In:

app/models/account.rb

find the existing local username validations and add:

validates :username,
          username_abuse: true,
          if: -> { local? && will_save_change_to_username? && !actor_type_application? && !user&.bypass_registration_checks }

For context, the relevant section will then look roughly like this:

validates :username,
          format: { with: /\A[a-z0-9_]+\z/i },
          length: { maximum: USERNAME_LENGTH_LIMIT },
          if: -> { local? && will_save_change_to_username? && !actor_type_application? }

validates_with UnreservedUsernameValidator,
               if: -> { local? && will_save_change_to_username? && !actor_type_application? && !user&.bypass_registration_checks }

validates :username,
          username_abuse: true,
          if: -> { local? && will_save_change_to_username? && !actor_type_application? && !user&.bypass_registration_checks }

The important part here is the local? condition.

This means the validator applies to local accounts only. It does not reject remote or federated accounts merely because another server happens to use a matching username.

The bypass_registration_checks condition also keeps Mastodon's existing administrative bypass behaviour intact.

  1. Restart Mastodon

After modifying the source, restart the relevant Mastodon processes according to your deployment method.

For a typical deployment this means at least restarting the web application. Restarting Sidekiq as well keeps all application processes on the same code revision.

No database migration is required.

  1. Upgrades

Because this is a local source modification, keep the patch around when upgrading Mastodon.

My own workflow is simply:

git stash
git fetch
git checkout <new-mastodon-version>
git stash pop

Git usually reapplies this modification cleanly.

If Mastodon changes the relevant account validation code upstream, resolve the resulting conflict manually and review whether the validator still belongs in the same location.

Why do this instead of blocking VPNs or IP ranges?

Initially I also experimented with blocking known VPN provider networks at the firewall.

That worked, but it caused unnecessary collateral damage: legitimate Mastodon users do in fact use ProtonVPN and similar services.

Filtering on the actual abuse pattern is much more precise:

Block abusive behaviour, not the transport used to reach the server.

This is obviously not a general anti-spam solution. It is useful when an automated registration campaign exposes a stable and sufficiently specific username-generation pattern.

As soon as the attacker changes that pattern, the regular expression will need to be adjusted.

@mapto

mapto commented Sep 13, 2026

Copy link
Copy Markdown

Thanks for this, very timely. However, I've noticed that I do not get notifications for these registrations, unlike others. Any clue what might be the cause for this awkward behaviour?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment