FunguyBot/README.md

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
```

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 🍄


## Plugin Documentation

### Core Commands

**🍄 !help**
Displays comprehensive help documentation for all available commands with usage examples.

**🔌 !plugins**
Lists all loaded plugins along with their descriptions.

**⏰ !date**
Displays the current date and time with proper ordinal formatting.

**🃏 !fortune**
Returns a random fortune message using the fortune command.

### Utility Commands

**💻 !proxy**
Retrieves and tests random SOCKS5 proxies from public sources, showing latency and caching working proxies.

**📶 !isup [domain/ip]**
Checks if a website or server is reachable, including DNS resolution and HTTP/HTTPS service checks.

**☯ !karma [user] [up/down]**
Manages karma points for users. View karma with `!karma user`, increase with `!karma user up`, decrease with `!karma user down`.

**🌧️ !weather [location]**
Fetches current weather information for any location using OpenWeatherMap API.
*Requires OPENWEATHER_API_KEY environment variable*

**📖 !ud [term] [index]**
Fetches definitions from Urban Dictionary. Use without arguments for random definition, or specify term and optional index.

**🔍 !dns [domain]**
Performs comprehensive DNS reconnaissance on a domain. Shows A, AAAA, MX, NS, TXT, CNAME, SOA, and other DNS records.

**💰 !btc**
Fetches the current Bitcoin price in USD from bitcointicker.co API.

### 🔍 Shodan Security Research

**📡 !shodan [command] [query]**
Shodan.io integration for security reconnaissance and threat intelligence.

**Commands:**
- `!shodan ip <ip_address>` - Detailed IP information (services, ports, banners)
- `!shodan search <query>` - Search Shodan database with filters
- `!shodan host <domain>` - Host information and subdomain enumeration
- `!shodan count <query>` - Count results with geographic/organization breakdown
- `!shodan test` - Test API connection and debug queries

**Search Examples:**
```bash
!shodan search apache
!shodan search "port:22 country:US"
!shodan search "product:nginx city:'New York'"
!shodan search "net:192.168.1.0/24"
!shodan search "vuln:cve-2021-44228"
!shodan search "http.title:'phpMyAdmin'"
!shodan search "ssl.cert.subject.cn:'example.com'"

Common Search Filters:
    country:US - Filter by country
    city:"New York" - Filter by city
    port:80,443,8080 - Filter by ports
    product:nginx - Filter by service/product
    os:Windows - Filter by operating system
    org:"Google" - Filter by organization
    net:192.168.0.0/16 - Filter by network range
    has_ssl:true - Has SSL certificate
    http.title:"admin" - HTTP page title contains
```

### 🔍 DNSDumpster Reconnaissance

**🌐 !dnsdumpster [domain]**
Comprehensive DNS reconnaissance and attack surface mapping using DNSDumpster.com API.

**Commands:**
- `!dnsdumpster <domain>` - Complete DNS reconnaissance for any domain
- `!dnsdumpster test` - Test API connection and key validity

**Features:**
- **A Records**: All IPv4 addresses with geographic and ASN information
- **NS Records**: Complete name server information with IP locations
- **MX Records**: All mail servers with geographic data
- **CNAME Records**: Full alias chain mappings
- **TXT Records**: All text records including SPF, DKIM, verification records
- **Additional Records**: AAAA, SRV, SOA, PTR records when available
- **Web Services**: HTTP/HTTPS service detection with banner information

**Examples:**
```bash
!dnsdumpster google.com
!dnsdumpster github.com
!dnsdumpster example.com
!dnsdumpster test

Data Returned:
    Total record counts for each type
    IP addresses with country and ASN information
    Web server banners and technologies
    Complete subdomain and host mappings
    Geographic distribution of services
Requires DNSDUMPSTER_KEY environment variable in .env file
```

## ExploitDB Plugin

A security plugin that searches Exploit-DB for vulnerabilities and exploits directly from Matrix.

### Features
- Searches the official Exploit-DB CSV database for security exploits
- Provides direct links to exploit details
- Fallback to web search when CSV lookup fails
- Configurable result limits (1-10)
- Formatted output with exploit metadata

### Commands
- `!exploitdb <search term> [max_results]` - Search Exploit-DB for vulnerabilities

### Examples
```
!exploitdb wordpress
!exploitdb apache 3
!exploitdb windows privilege escalation
!exploitdb android 10
```
### Usage Notes
- Maximum results limited to 10 for performance
- Results include: title, EDB-ID, type, platform, author, date, and direct URL
- Includes responsible disclosure reminder
- Automatically falls back to search links if CSV database is unavailable


### 🔒 HTTP Security Headers Analysis

**🛡️ !headers [url]**
Comprehensive HTTP security header analysis with security scoring and recommendations.

**Features:**
- **Security Scoring**: 0-100 rating based on headers configuration
- **Header Validation**: Checks presence and proper configuration of critical security headers
- **Redirect Analysis**: Follows HTTP to HTTPS redirect chain
- **SSL Certificate**: Basic SSL/TLS certificate information
- **Information Disclosure**: Identifies revealing server headers
- **Actionable Recommendations**: Specific guidance for security improvements

**Security Headers Analyzed:**
- `Strict-Transport-Security` (HSTS) - HTTP to HTTPS enforcement
- `Content-Security-Policy` (CSP) - XSS and content injection protection
- `X-Frame-Options` - Clickjacking protection
- `X-Content-Type-Options` - MIME type sniffing prevention
- `Referrer-Policy` - Referrer information control
- `Feature-Policy` / `Permissions-Policy` - Browser feature restrictions
- Information disclosure headers (`Server`, `X-Powered-By`)

**Security Ratings:**
- **🟢 Excellent (80-100)**: Strong security headers configuration
- **🟡 Good (60-79)**: Moderate security, room for improvement
- **🟠 Fair (40-59)**: Basic security, significant improvements needed
- **🔴 Poor (0-39)**: Weak security headers configuration

**Examples:**
```bash
!headers example.com
!headers https://github.com
!headers localhost:8080
!headers subdomain.target.com
```


### AI & Generation Commands

**🤖 AI Commands (!tech, !music, !eth, etc.)**
Multiple AI model commands that interface with local AI API. Each command uses specialized prompts for different domains:
- `!tech` - Technology assistance
- `!music` - Music knowledge and recommendations
- `!weather` - Weather information
- And 100+ other specialized AI commands

**📸 !sd [prompt] [options]**
Generates images using self-hosted Stable Diffusion with customizable parameters:
- `--steps` - Number of generation steps (default: 4)
- `--cfg` - CFG scale (default: 2)
- `--h` - Image height (default: 512)
- `--w` - Image width (default: 512)
- `--neg` - Negative prompt
- `--sampler` - Sampler name (default: DPM++ SDE)

**📄 !text [prompt] [options]**
Generates text using Ollama's Mistral 7B Instruct model:
- `--max_tokens` - Maximum tokens to generate (default: 512)
- `--temperature` - Sampling temperature (default: 0.7)

### Media & Search Commands

**🎬 YouTube Commands**
- Automatic preview when YouTube links are posted
- `!yt [search terms]` - Search for YouTube videos
- Shows video info, description, and attempts to fetch lyrics

**📰 !xkcd**
Fetches and displays a random XKCD comic.

### Administration Commands
*Admin only - requires admin_user configuration*

**🔧 !set [option] [value]**
Set configuration options (admin_user, prefix)

**🔍 !get [option]**
Get configuration values

**💾 !saveconf**
Save current configuration

**📥 !loadconf**
Load saved configuration

**👁️ !show**
Display current configuration

**🔄 !reset**
Reset configuration to defaults

**📤 !load [plugin]**
Load a plugin

**📥 !unload [plugin]**
Unload a plugin

**🔄 !reload**
Reload all plugins

**🚫 !disable [plugin] [room_id]**
Disable a plugin for specific room

**✅ !enable [plugin] [room_id]**
Enable a plugin for specific room

**⚙️ !rehash**
Reload configuration

### Cron System

**⏱️ !cron [add|remove] [room_id] [cron_entry] [command]**
Schedule automated commands using cron syntax:
- `add` - Add a new cron job
- `remove` - Remove an existing cron job

## Full AI Command List

The bot includes over 100 specialized AI commands covering various domains:

**Creative & Writing**: !write, !script, !author, !poem, !rap, !story, !comic, !motiv, !debate

**Technical**: !tech, !dev, !py, !php, !regex, !math, !web, !it, !security, !ai, !ml, !data, !game

**Professional**: !seo, !recruit, !coach, !devrel, !sales, !ceo, !mgmt, !startup, !invest, !fin

**Educational**: !tutor, !teach, !edu, !acad, !hist, !astro, !chem, !math, !psych

**Lifestyle**: !fit, !health, !diet, !cook, !travel, !art, !music, !film, !gaming

**Specialized**: !legal, !medical, !realest, !auto, !fashion, !design, !interior

And many more! Use `!help` in chat to see the complete list with descriptions.

## 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)

## Troubleshooting

- 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!*