PhreakBot (v0.1.40)

PhreakBot is a modular IRC bot written in Python.

Features

• Modular design with easy-to-add modules
• Permission system with owner, admin, and user levels
• Quote database with search functionality
• URL title and description fetching
• Channel management (join, part, topic)
• User registration and management
• Auto-op functionality
• CTCP version support
• Robust error handling and logging
• Frys-IX peering LAN member information with port speed, IP, and max prefix details
• MAC address vendor lookup for both full and partial MAC addresses
• Mass user registration and hostmask merging
• ROA validation and routing information
• Karma system with ++ and -- support
• And more!

Installation

Docker / Podman (Recommended)

PhreakBot supports both Docker and Podman.

1. Copy .env.example to .env and update the values:

   cp .env.example .env
   

2. Start the bot:

   Using Docker:

   docker-compose up -d
   

   Using Podman:

   podman-compose up -d
   

For detailed Podman instructions and features, see docs/PODMAN.md.

Manual Installation

1. Clone the repository
2. Install the required dependencies: pip install -r requirements.txt
3. Set up a PostgreSQL database
4. Run the SQL in dbschema.psql to create the necessary tables
5. Configure the bot by editing config/config.json
6. Run the bot: python phreakbot.py

PhreakBot uses the pydle IRC library, which offers:

• Better handling of IRC events
• Improved connection stability
• Enhanced support for custom commands like !item = value and !item?
• More detailed logging
• Asynchronous operation for better performance

Scripts

All utility scripts are located in the scripts/ directory. See scripts/README.md for detailed information about each script.

Configuration

Docker / Podman

Configure via environment variables in .env (see .env.example for defaults):

# PostgreSQL credentials — POSTGRES_PASSWORD is required, no default
POSTGRES_USER=phreakbot
POSTGRES_PASSWORD=changeme
POSTGRES_DB=phreakbot

# IRC configuration — TLS on port 6697 is the default
IRC_SERVER=irc.libera.chat
IRC_PORT=6697
IRC_NICKNAME=PhreakBot
IRC_CHANNEL=#phreakbot

Manual Installation

Edit config/config.json to configure the bot:

{
    "server": "irc.example.com",
    "port": 6697,
    "use_tls": true,
    "tls_verify": true,
    "nickname": "PhreakBot",
    "realname": "PhreakBot",
    "channels": ["#channel1", "#channel2"],
    "command_trigger": "!"
}

Setting Up Ownership

When the bot first starts, use the !owner claim command to claim ownership of the bot. This will grant you admin privileges and allow you to manage the bot.

Module Development

Modules are stored in the modules directory. Each module should have a config function that returns a dictionary with the following keys:

• events: List of IRC events to listen for
• commands: List of commands the module provides
• permissions: List of permissions required to use the module
• help: Help text for the module

For detailed information on how to create your own modules, see the Module Development Guide.

Security

• IRC connections default to TLS on port 6697 (use_tls: true). Plaintext port 6667 is intentionally not the default.
• POSTGRES_PASSWORD must be set explicitly — the bot refuses to start if it is empty.
• URL fetching (!url, auto-title, !@) is protected against SSRF: all redirect hops are re-checked against a blocked-network list (RFC 1918, loopback, link-local, cloud metadata endpoints).
• The !ip command only reports public IP addresses; private/reserved addresses are blocked from output.
• The permission system enforces an allowlist of valid permission names; unknown values are rejected at write time.
• Exception details are never sent to IRC channels; full errors are logged server-side only.

See CHANGELOG.md for the full history of security fixes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.