Discord Role Scraper

A Python script used to scrape Discord guild info, roles, and channel overwrites.

Requirements

1. Git - Install Git
   1. Check if you have Git installed with git --version
2. Python (>=3.11; <4) - Install Python (Windows), Install Python (Linux) (see pyenv)
   1. Check if you have Python installed with python3 --version
3. Pip - Install Pip
   1. Check if you have Pip installed with pip --version
4. Poetry - Install Poetry (preferrably with pipx)
   1. Check if you have Poetry installed with poetry --version

Build Requirements

1. PyInstaller - Install PyInstaller (preferrably with pipx)
   1. Check if you have PyInstaller installed with pyinstaller --version
   2. PyInstaller is platform dependent, if you want to build .exe files, you must build on Windows

Dev Requirements

1. Act - Install Act
   1. Check if you have Act installed with act --version
   2. Refer to this project's Makefile (sudo-act) for usage
   3. Put secrets in workflow.secrets (mv workflow.secrets.example workflow.secrets)
2. Markdownlint - Install Markdownlint

Usage (Linux)

Quick Start

git clone https://github.com/vile/discord-role-scraper.git
cd discord-role-scraper
make

Running with CLI Args

See CLI Args for more info.

poetry run python3 main.py (discord token) (server id) (single run)

Interacting with the script

After starting the script, follow the prompts given to input your token and server ID.

Usage (Windows)

Quick Start (exe)

Download the latest windows-release.zip file from the releases tab. Then, unzip with your choice of zip tool (WinRAR, 7zip, NanaZip, etc.), and double click DiscordRoleScraper.exe.

The releases includes the most up to date build and default config.toml file.

Running with Python

Download the latest version of this repo via HTTPS or clone with git:

Download via HTTPS

Or clone:

git clone https://github.com/vile/discord-role-scraper.git
cd discord-role-scraper

Install dependencies:

pip install -r requirements.txt

Then, run the script with Python in CMD/Powershell/Terminal:

python3 main.py

Build Exe from Source Script

Ensure you have PyInstaller installed (see build requirements), install script dependencies, then build:

pip install -r requirements.txt
pyinstaller main.py --onefile --name DiscordRoleScraper

The built exe will be exported to the dist/ folder, move the file into the root directory of the project (where config.toml is).

Running with CLI Args

CLI args are supported both running directly with Python, and with a built exe. See CLI Args for more info.

python3 main.py (discord token) (server id) (single run)

.\DiscordRoleScraper.exe (discord token) (server id) (single run)

Interacting with the script

After starting the script, follow the prompts given to input your token and server ID.

Editing config.toml

The config.toml file contains all of the editable settings for this script. Any value under the permissions_to_scrape section that starts with 0x should be commented out instead of having its value changed. The permission config can be expanded following Discord's bitwise permission flags.

Export Results

Name	type	Default Value	Description
export_results	bool	true	Whether or not to export txt files of scrapes

Scrape Guild Info

Name	type	Default Value	Description
scrape_guild_info	bool	true	Whether or not to scrape the guild's info

Name	Default Value
id	true
name	true
icon	false
description	true
home_header	false
splash	false
discovery_splash	false
features	false
banner	false
owner_id	true
application_id	false
region	true
afk_channel_id	false
afk_timeout	false
system_channel_id	false
system_channel_flags	false
widget_enabled	false
widget_channel_id	false
verification_level	true

Scrape Permission Info

Name	type	Default Value	Description
scrape_permission_info	bool	true	Whether or not to scrape the guild's roles and associated permissions and/or properties

All values starting with 0x can not be changed, if you wish to not see (disable) a specific permission in your scrapes, comment the line (using a #). Changing any of the 0x values will break calculations associated with checking permissions.

Name	Type	Default Value
name	bool	true
position	bool	true
id	bool	true
mentionable	bool	true
administrator	bitwise
mention all	bitwise
manage guild	bitwise
manage roles	bitwise
manage channels	bitwise
manage events	bitwise
manage nicknames	bitwise
kick members	bitwise
ban members	bitwise
webhooks	bitwise
app commands	bitwise
tags	bool	true

Scrape Channel Overwrites

Name	type	Default Value	Description
scrape_channel_overwrite_info	bool	false	Whether or not to scrape the guild's channel overwrites, including both roles and users

CLI Args

All CLI args are optional, but are sequentially required.

Meaning:

• if you want to pass server id, you must also pass discord token.
• if you want to pass single run, you must also pass server id and discord token.

Supported args:

• discord token (full, unquoted auth token string)
• server id (16 to 19 digit numeric server id)
• single run (true/false, whether or not to immediately exit after the first scrape completes)
  • Automatically defaults to false

Arg types and defaults

All CLI args are unquoted.

Arg	Type	Default Value
discord token	string	None
server id	int	0
single run	bool	false

Examples

python3 main.py DISCORD.TOKEN.HERE 

python3 main.py DISCORD.TOKEN.HERE SERVER_ID

python3 main.py DISCORD.TOKEN.HERE SERVER_ID true

FAQ

Is my token safe?

Yes, your token is safe, it is only temporarily cached in memory for convience if you want to scrape multiple servers in the same session. After closing the script, your token is removed from memory. Your token is never saved on your computer, and is only ever sent to the official Discord API.

Will this get my account terminated?

You're interacting with normally available API endpoints for user accounts in a normal way. However, Discord doesn't like when you script or automate any type of action, therefore there is always a risk of account termination. I am not responsible if you spam the API scraping servers and get your account terminated. It is recommended to use a brand new or alt account.

Can you help me with ...?

No, I will not help you with this script (follow the Linux and Windows sections above). No, I will not make you any scripts.

When I build my own exe, it immediately closes or says it can't find a module (e.g. tomli)

Make sure you've installed the script dependencies as well before building. PyInstaller does not automatically download packages/libraries for you, it only looks locally (either global installs or venv).