194 lines
6.4 KiB
Markdown
194 lines
6.4 KiB
Markdown
I wrote this bot in one night, while I'm recovering from two level cervical spinal surgery, CDA Cervical Discectomy and Disc Arthroplasty. Expect a lot of bugs.
|
||
|
||
# Matrix Bot
|
||
|
||
Matrix Bot is a Python-based chat bot designed to work with Matrix, an open network for secure, decentralized communication. This bot is built using the `simplematrixbotlib` library and provides various commands and functionalities for interacting with Matrix rooms.
|
||
|
||
## Features
|
||
|
||
- Modular architecture: Commands are implemented as separate plugins, making it easy to add or modify functionality.
|
||
- Command handling: The bot listens for specific commands prefixed with `!` and responds accordingly.
|
||
- Plugin system: Each command is implemented as a separate plugin module, allowing for easy customization and extension.
|
||
- Extensible: Users can add new commands by creating additional plugin modules.
|
||
|
||
## Automatic Installation
|
||
Run the installation script
|
||
1. `./install-funguy.sh`
|
||
|
||
2. Launch the bot:
|
||
`sudo systemctl start funguybot`
|
||
|
||
## Manual Installation
|
||
|
||
1. Create python venv
|
||
`python3 -m venv venv`
|
||
`source venv/bin/activate`
|
||
|
||
2. Clone the repository:
|
||
`git clone https://gitlab.com/Eggzy/funguybot.git`
|
||
|
||
3. Apply the patch
|
||
`cp api.py.patch simplematrixbotlib`
|
||
`git apply api.py.patch`
|
||
|
||
4. Install dependencies:
|
||
`cd simplematrixbotlib && pip install .`
|
||
`cd ../ && pip install -r requirements.txt`
|
||
|
||
3. Set up environment variables:
|
||
Create/Edit `.env` file in the root directory of the bot and add the following variables:
|
||
|
||
```
|
||
MATRIX_URL="https://matrix.org" (or another homeserver)
|
||
MATRIX_USER=""
|
||
MATRIX_PASS=""
|
||
OPENWEATHER_API_KEY="" # Optional: For weather plugin
|
||
|
||
SMTP_SERVER = "example.com`"
|
||
SMTP_PORT = 465
|
||
SMTP_USER = "name@domain.tld"
|
||
SMTP_PASSWORD = "somepassword"
|
||
|
||
OPENWEATHER_API_KEY=
|
||
SHODAN_KEY=
|
||
DNSDUMPSTER_KEY=
|
||
LASTFM_API_KEY=
|
||
YOUTUBE_API_KEY=
|
||
|
||
INFERMATIC_API=
|
||
INFERMATIC_MODEL=
|
||
OMDB_API_KEY=
|
||
GNEWS_API_KEY=
|
||
```
|
||
|
||
4. Create systemd.service
|
||
Create `/etc/systemd/system/funguybot.service`
|
||
Replace `$working_directory` with your bot install path
|
||
|
||
```
|
||
[Unit]
|
||
Description=Funguy Bot Service
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=$user
|
||
Group=$group
|
||
WorkingDirectory=$working_directory
|
||
ExecStart=$working_directory/start-funguy.sh
|
||
Restart=on-failure
|
||
StandardOutput=syslog
|
||
StandardError=syslog
|
||
SyslogIdentifier=funguybot
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
EOF
|
||
```
|
||
|
||
5. Launch Fungy
|
||
```
|
||
systemctl daemon-reload
|
||
systemctl enable funguybot
|
||
systemctl start funguybot
|
||
```
|
||
|
||
## Usage
|
||
|
||
To use the bot, invite it to a Matrix room and interact with it by sending commands prefixed with `!`. For example:
|
||
|
||
- `!date`: Display the current date and time.
|
||
- `!fortune`: Get a random fortune message.
|
||
- `!proxy`: Retrieve and test random SOCKS5 and HTTP proxies.
|
||
- `!isup <domain/ip>`: Check if the specified domain or IP address is reachable.
|
||
- `!karma <user>`: View or modify karma points for a user.
|
||
- `!funguy <prompt>` Talk to the Tech AI LLM
|
||
- `!music <prompt>` Talk to the music knowledge LLM
|
||
- `!yt <search terms>` Search Youtube
|
||
- `!weather New York` Get Weather information
|
||
- `!ud <term>` Get Urban Dictionary definition
|
||
- `!help` Get Help
|
||
For a complete list of available commands and their descriptions, use the `!commands` command.
|
||
|
||
# 🍄 Funguy Bot Commands 🍄
|
||
|
||
## Available Plugins
|
||
|
||
The bot includes the following plugins:
|
||
|
||
- **admin.py**: Full room moderation – multi‑word name support
|
||
- **arxiv.py**: arXiv academic paper search (with rate limiting and error reporting)
|
||
- **bitcoin.py**: Current Bitcoin price
|
||
- **config.py**: Admin-only configuration commands (preserves disabled plugins)
|
||
- **cron.py**: In‑process cron scheduler (room‑aware, no system crontab)
|
||
- **date.py**: Show current date and time
|
||
- **ddg.py**: DuckDuckGo search – collapsible results (ddgs library, no API key)
|
||
- **dns.py**: DNS reconnaissance
|
||
- **dnsdumpster.py**: DNSDumpster domain reconnaissance
|
||
- **exploitdb.py**: Exploit-DB search
|
||
- **fortune.py**: Random fortune message
|
||
- **geo.py**: IP geolocation lookup
|
||
- **hackernews.py**: Hacker News integration
|
||
- **hashid.py**: Hash type identifier
|
||
- **headers.py**: HTTP security header analysis
|
||
- **help.py**: Plugin for dynamically aggregating help from all loaded plugins.
|
||
- **imdb.py**: IMDb lookup via OMDb API
|
||
- **infermatic-text.py**: AI text generation via Infermatic API
|
||
- **isup.py**: Check if a site is up
|
||
- **karma.py**: Room karma tracking system (display names only, no Matrix IDs)
|
||
- **lastfm.py**: Last.fm integration
|
||
- **loadplugin.py**: Load/unload plugins at runtime
|
||
- **news.py**: News headlines via GNews API
|
||
- **plugins.py**: List all loaded plugins
|
||
- **proxy.py**: Working SOCKS5 proxy finder
|
||
- **roomstats.py**: Per‑user room statistics (Limnoria‑style), with multi‑word name support
|
||
- **shodan.py**: Shodan.io reconnaissance
|
||
- **sslscan.py**: SSL/TLS security scanner
|
||
- **stable-diffusion.py**: Stable Diffusion image generation
|
||
- **subdomains.py**: Subdomain enumeration via CertSpotter
|
||
- **sysinfo.py**: System information and monitoring
|
||
- **timezone.py**: World clock (no hardcoded cities)
|
||
- **urbandictionary.py**: Urban Dictionary definitions
|
||
- **weather.py**: Weather forecast (OWM primary, Open‑Meteo fallback)
|
||
- **welcome.py**: Room welcome message
|
||
- **whois.py**: WHOIS lookup
|
||
- **wikipedia.py**: Wikipedia article summary
|
||
- **xkcd.py**: Random XKCD comic
|
||
- **youtube-search.py**: YouTube video search
|
||
|
||
## Configuration
|
||
|
||
The bot uses a TOML configuration file (`funguy.conf`) for settings:
|
||
- `admin_user` - Matrix user ID with admin privileges
|
||
- `prefix` - Command prefix (default: "!")
|
||
- Plugin-specific settings in `plugins/ai.json` for AI commands
|
||
|
||
## Dependencies
|
||
|
||
- Python 3.7+
|
||
- simplematrixbotlib
|
||
- Various AI/ML services (Stable Diffusion, Ollama, etc.)
|
||
- Database support (SQLite)
|
||
- External APIs (OpenWeatherMap, Urban Dictionary, YouTube)
|
||
|
||
## Dependencies
|
||
|
||
- Ensure all environment variables are set correctly
|
||
- Check that required services are running (Stable Diffusion API, Ollama, etc.)
|
||
- Verify plugin permissions and whitelist settings
|
||
- Check logs for detailed error information
|
||
|
||
## Support
|
||
|
||
Join our Matrix room for support and community:
|
||
[Self-hosting | Security | Sysadmin | Homelab | Programming](https://matrix.to/#/#selfhosting:mozilla.org)
|
||
|
||
## Credits
|
||
|
||
**🧙♂️ Creator & Developer**: HB (@hashborgir:mozilla.org)
|
||
**🍄 Funguy Bot** - Created during recovery from cervical spinal surgery
|
||
|
||
---
|
||
|
||
*Note: This bot was created rapidly and may contain bugs. Please report issues and contribute improvements!*
|