Skip to content

SERVER_MODE.md

Latest commit

 

History

History
662 lines (520 loc) · 13 KB

SERVER_MODE.md

File metadata and controls

662 lines (520 loc) · 13 KB
Raw

PluginHunter Server Mode

Overview

Server Mode enables automated, continuous vulnerability scanning of WordPress plugins with real-time notifications to Discord and Telegram. Perfect for VPS deployment and continuous security monitoring.

Features

  • ✅ Continuous Scanning - Endless scanning mode that never stops
  • ✅ Cron-Based Scheduling - Schedule scans at specific times
  • ✅ WordPress.org Integration - Automatically fetches plugin list
  • ✅ Discord Notifications - Real-time alerts via webhooks
  • ✅ Telegram Notifications - Alerts and reports via bot
  • ✅ Professional Reports - Markdown reports with POC details
  • ✅ Fully Configurable - Interactive wizard for easy setup
  • ✅ Organized Reports - Separate folders per plugin
  • ✅ Temp Cleanup - Auto-cleanup of downloaded plugins

Quick Start

1. Install

pip install PluginHunter

2. Configure

PluginHunter
# Select option 7: Server Mode Configuration

The interactive wizard will guide you through:

  • Scan mode selection (continuous or cron)
  • Discord webhook setup
  • Telegram bot setup
  • Scan targets configuration
  • Directory settings
  • Rate limiting

3. Start Server

Option A: From Interactive Menu (Recommended)

PluginHunter
# Select option 8: Start Server Mode

This will:

  • Check if server_config.json exists
  • Display current configuration
  • Show scan mode and notification settings
  • Confirm before starting
  • Start server mode with the configured settings

Option B: From Command Line

PluginHunter server --config server_config.json

Option C: Background Mode

# Using nohup
nohup PluginHunter server --config server_config.json > server.log 2>&1 &

# Using screen
screen -S vulnhunter
PluginHunter server --config server_config.json
# Press Ctrl+A, D to detach

# Using tmux
tmux new -s vulnhunter
PluginHunter server --config server_config.json
# Press Ctrl+B, D to detach

Configuration

Interactive Configuration Wizard

The easiest way to configure server mode:

PluginHunter
# Select option 7

The wizard will:

  1. Ask for scan mode (continuous or cron)
  2. Configure Discord notifications (optional)
  3. Configure Telegram notifications (optional)
  4. Set scan targets (WordPress.org or custom list)
  5. Configure directories and settings
  6. Test webhooks/bots before saving
  7. Save configuration to server_config.json

Manual Configuration

Create server_config.json:

{
  "continuous_mode": {
    "enabled": true,
    "delay_between_scans": 10,
    "max_concurrent_scans": 1,
    "restart_on_queue_empty": true
  },
  "cron_mode": {
    "enabled": false,
    "schedule_type": "daily",
    "time": "02:00",
    "day": "monday",
    "interval_hours": 24
  },
  "notifications": {
    "discord": {
      "enabled": true,
      "webhook_url": "https://discord.com/api/webhooks/YOUR_WEBHOOK",
      "notify_on_start": true,
      "notify_on_complete": true,
      "notify_on_critical": true
    },
    "telegram": {
      "enabled": false,
      "bot_token": "YOUR_BOT_TOKEN",
      "chat_id": "YOUR_CHAT_ID",
      "notify_on_start": true,
      "notify_on_complete": true,
      "notify_on_critical": true
    }
  },
  "wordpress_api": {
    "enabled": true,
    "fetch_popular": true,
    "fetch_new": false,
    "max_plugins": 100,
    "refresh_schedule": "0 2 * * *"
  },
  "scan_settings": {
    "deep_scan": true,
    "dynamic_verification": false,
    "max_plugins_per_run": 10,
    "rate_limit_delay": 5
  },
  "directories": {
    "reports": "./server_reports",
    "temp": "./temp_plugins",
    "cleanup_temp": true
  },
  "custom_targets": {
    "enabled": false,
    "plugin_slugs": []
  }
}

Scan Modes

Continuous Mode (Endless Scanning)

Perfect for VPS deployment where you want continuous monitoring:

{
  "continuous_mode": {
    "enabled": true,
    "delay_between_scans": 10,
    "max_concurrent_scans": 1,
    "restart_on_queue_empty": true
  }
}
  • enabled: Enable continuous mode
  • delay_between_scans: Seconds to wait between scans
  • max_concurrent_scans: Number of parallel scans
  • restart_on_queue_empty: Restart queue when all plugins scanned

Start continuous scanning:

# Foreground
PluginHunter server --config server_config.json

# Background with nohup
nohup PluginHunter server --config server_config.json > server.log 2>&1 &

# Using screen
screen -S vulnhunter
PluginHunter server --config server_config.json
# Press Ctrl+A, D to detach

# Using tmux
tmux new -s vulnhunter
PluginHunter server --config server_config.json
# Press Ctrl+B, D to detach

Cron Mode (Scheduled Scanning)

For scheduled scans at specific times:

{
  "cron_mode": {
    "enabled": true,
    "schedule_type": "daily",
    "time": "02:00"
  },
  "continuous_mode": {
    "enabled": false
  }
}

Schedule Types:

  • daily: Run daily at specific time

    {"schedule_type": "daily", "time": "02:00"}

  • weekly: Run weekly on specific day

    {"schedule_type": "weekly", "day": "monday", "time": "02:00"}

  • hourly: Run every hour

    {"schedule_type": "hourly"}

  • interval: Run at custom interval

    {"schedule_type": "interval", "interval_hours": 6}

Notifications

Discord Notifications

  1. Create Discord Webhook:

    • Go to your Discord server
    • Server Settings → Integrations → Webhooks
    • Create webhook and copy URL

  2. Configure:

    {
  "discord": {
    "enabled": true,
    "webhook_url": "https://discord.com/api/webhooks/YOUR_WEBHOOK",
    "notify_on_start": true,
    "notify_on_complete": true,
    "notify_on_critical": true
  }
}

  3. Test:

    PluginHunter
# Select option 7
# Configure Discord
# Test webhook before saving

Notification Types:

  • notify_on_start: When scan starts
  • notify_on_complete: When scan completes
  • notify_on_critical: When critical/high vulnerabilities found

Telegram Notifications

  1. Create Telegram Bot:

    • Message @BotFather on Telegram
    • Send /newbot and follow instructions
    • Copy bot token

  2. Get Chat ID:

    • Message your bot
    • Visit: https://api.telegram.org/bot<TOKEN>/getUpdates
    • Find your chat ID

  3. Configure:

    {
  "telegram": {
    "enabled": true,
    "bot_token": "YOUR_BOT_TOKEN",
    "chat_id": "YOUR_CHAT_ID",
    "notify_on_start": true,
    "notify_on_complete": true,
    "notify_on_critical": true
  }
}

WordPress.org Integration

Automatically fetch and scan plugins from WordPress.org:

{
  "wordpress_api": {
    "enabled": true,
    "fetch_popular": true,
    "fetch_new": false,
    "max_plugins": 100,
    "refresh_schedule": "0 2 * * *"
  }
}
  • enabled: Enable WordPress.org API integration
  • fetch_popular: Fetch popular plugins
  • fetch_new: Fetch newly added plugins
  • max_plugins: Maximum number of plugins to fetch
  • refresh_schedule: Cron expression for database refresh

Refresh Schedule Examples:

  • 0 2 * * * - Daily at 2:00 AM
  • 0 */6 * * * - Every 6 hours
  • 0 0 * * 0 - Weekly on Sunday at midnight

Scan Settings

{
  "scan_settings": {
    "deep_scan": true,
    "dynamic_verification": false,
    "max_plugins_per_run": 10,
    "rate_limit_delay": 5
  }
}
  • deep_scan: Enable comprehensive analysis
  • dynamic_verification: Enable exploit testing (requires Docker)
  • max_plugins_per_run: Limit plugins per scan cycle
  • rate_limit_delay: Seconds between API requests

Directory Structure

{
  "directories": {
    "reports": "./server_reports",
    "temp": "./temp_plugins",
    "cleanup_temp": true
  }
}

Report Organization:

server_reports/
├── contact-form-7/
│   ├── scan_20240227_143022.json
│   ├── scan_20240227_143022.html
│   └── scan_20240227_143022_cve.md
├── akismet/
│   ├── scan_20240227_144530.json
│   └── scan_20240227_144530.html
└── ...

Each plugin gets its own folder with timestamped reports.

Temp Directory:

  • Downloaded plugins stored temporarily
  • Auto-cleanup after scan (if cleanup_temp: true)
  • Saves disk space

Custom Target Lists

Scan specific plugins instead of WordPress.org list:

{
  "custom_targets": {
    "enabled": true,
    "plugin_slugs": [
      "contact-form-7",
      "akismet",
      "jetpack",
      "woocommerce"
    ]
  },
  "wordpress_api": {
    "enabled": false
  }
}

Usage Examples

Example 1: Continuous Scanning with Discord

# Configure
PluginHunter
# Select option 7
# Choose continuous mode
# Enable Discord notifications
# Configure settings

# Start
PluginHunter server --config server_config.json

Example 2: Daily Scheduled Scan

# Configure for daily 2 AM scan
PluginHunter
# Select option 7
# Choose cron mode
# Set daily at 02:00
# Configure notifications

# Start
PluginHunter server --config server_config.json

Example 3: VPS Background Deployment

# Install
pip install PluginHunter

# Configure
PluginHunter
# Select option 7, configure all settings

# Start in background
nohup PluginHunter server --config server_config.json > server.log 2>&1 &

# Check logs
tail -f server.log

# Stop
pkill -f "PluginHunter server"

Example 4: Custom Plugin List

{
  "custom_targets": {
    "enabled": true,
    "plugin_slugs": ["my-plugin-1", "my-plugin-2"]
  },
  "continuous_mode": {
    "enabled": true,
    "delay_between_scans": 30
  }
}
PluginHunter server --config server_config.json

Monitoring

Check Server Status

# View logs
tail -f server.log

# Check process
ps aux | grep PluginHunter

# View reports
ls -lh server_reports/

Stop Server

# If running in foreground
Ctrl+C

# If running in background
pkill -f "PluginHunter server"

# If using screen
screen -r vulnhunter
Ctrl+C

# If using tmux
tmux attach -t vulnhunter
Ctrl+C

Troubleshooting

Server won't start

# Check configuration
cat server_config.json

# Validate JSON
python3 -m json.tool server_config.json

# Check permissions
ls -la server_config.json

Notifications not working

# Test Discord webhook
curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test message"}'

# Test Telegram bot
curl "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>&text=Test"

High memory usage

Reduce concurrent scans:

{
  "continuous_mode": {
    "max_concurrent_scans": 1
  }
}

Disk space issues

Enable temp cleanup:

{
  "directories": {
    "cleanup_temp": true
  }
}

Best Practices

  1. Start with small plugin list - Test with 10-20 plugins first
  2. Monitor resource usage - Check CPU/memory/disk
  3. Use rate limiting - Avoid overwhelming WordPress.org API
  4. Enable temp cleanup - Save disk space
  5. Regular log rotation - Prevent log files from growing too large
  6. Test notifications - Verify webhooks/bots before production
  7. Backup reports - Archive old reports periodically
  8. Use screen/tmux - For persistent sessions on VPS

Advanced Configuration

Rate Limiting

{
  "scan_settings": {
    "rate_limit_delay": 10,
    "max_plugins_per_run": 5
  }
}

Database Refresh Schedule

{
  "wordpress_api": {
    "refresh_schedule": "0 */12 * * *"
  }
}

Multiple Notification Channels

{
  "notifications": {
    "discord": {
      "enabled": true,
      "webhook_url": "DISCORD_WEBHOOK"
    },
    "telegram": {
      "enabled": true,
      "bot_token": "TELEGRAM_TOKEN",
      "chat_id": "TELEGRAM_CHAT_ID"
    }
  }
}

Security Considerations

  • Protect config file - Contains sensitive tokens

    chmod 600 server_config.json

  • Use environment variables - For sensitive data

    export DISCORD_WEBHOOK="your_webhook"
export TELEGRAM_TOKEN="your_token"

  • Rotate tokens regularly - Update webhooks/bot tokens periodically

  • Monitor access logs - Check who's accessing reports

  • Secure VPS - Use firewall, SSH keys, fail2ban

Support

For issues or questions:

Author: LAKSHMIKANTHAN K (letchupkt)
License: MIT