WordPress Watcher is a Python wrapper for WPScan that manages scans on multiple sites and reports by email.
Project description
WPWatcher
Automating WPScan to scan and report vulnerable Wordpress sites
Features
- Scan multiple sites with WPScan
- Parse WPScan output and divide the results in "Alerts", "Warnings", "Informations" and eventually "Errors"
- Keep track of fixed issues
- Handled VulnDB API limit
- Define reporting emails addresses for every configured site individually and globally
- Define false positives strings for every configured site individually and globally
- Define WPScan arguments for every configured site individually and globally
- Save raw WPScan results into files
- Speed up scans using several asynchronous workers
- Follow URL redirection if WPScan fails and propose to ignore main redirect
- Log file also lists all the findings
- Scan sites continuously at defined interval and configure script as a linux service
- Prescan sites without API token, then use token on site having issues (i.e. outdated Wordpress, plugin version) only to save API calls
Prerequisites
- WPScan (itself requires Ruby and some libraries).
- Python 3 (standard libraries)
- Tested on Linux and MacOS
Install
With PyPi (stable)
python3 -m pip install wpwatcher
Update
python3 -m pip install wpwatcher --upgrade
Manually (develop)
git clone https://github.com/tristanlatr/WPWatcher.git
cd WPWatcher
python3 setup.py install
wpwatcher should be in your PATH but you can always run the python script directly
python3 ./wpwatcher/cli.py --url exemple3.com -v
Try it out
Simple usage
Scan 2 sites with default config.
wpwatcher --url exemple.com exemple1.com
More complete exemple
Load sites from text file , add WPScan arguments , follow redirection if WPScan fails and propose to use --ignore-main-redirect, use 5 asynchronous workers , email custom recepients if any alerts with full WPScan output attached. If you reach your API limit, it will wait and continue 24h later.
wpwatcher --urls sites.txt \
--wpscan_args "--force --stealthy --api-token <TOKEN>" \
--follow_redirect \
--workers 5 \
--send --attach \
--email_to collaborator1@office.ca collaborator2@office.ca \
--api_limit_wait
Review the Wiki for more documentation, anyone can edit Wiki pages, please feel free to add any useful documentation, exemples or tips !
Notes on script behaviours
- The script will automatically try to delete all temp
wpscanfiles in/tmp/wpscanbefore starting scans. You might run into file not found error (#13), please consider adding--cache-ttl 0to WPScan arguments. - You might want to use
--ff(fail fast) when you're setting up and configuring the script. Abort scans when WPScan fails, useful to troubleshoot. - All messages are printed to
stdout. - WPWatcher store a database of reports and compare reports one scan after another to notice for fixed issues. Default location is
~/.wpwatcher/wp_reports.json. Setwp_reports=nullin the config to disable this feature.
Return non zero status code if :
- One or more WPScan command failed
- Unable to send one or more email report
- Other errors
Configuration
WPWatcher must read a configuration file to send mail reports.
See Wiki for more informations.
Select config file with --conf File path. You can specify multiple files. Will overwrites the keys with each successive file. If not specified, it will try to load config from files ~/.wpwatcher/wpwatcher.conf , ~/wpwatcher.conf and ./wpwatcher.conf, in this order.
Create and edit a new config file from template. ( --template_conf argument print a default config file )
wpwatcher --template_conf > ./wpwatcher.conf
vim ./wpwatcher.conf
See complete list of options here.
Notes about WPScan API token
You need a WPScan API token in order to show vulnerability data and be alerted of vulnerable WordPress or plugin. If you have large number of sites to scan, you'll probably can't scan all your sites because of the limited amount of daily API request. Turn on api_limit_wait to wait 24h and contuinue scans when API limit si reached.
If no API token is provided to WPScan, scans will still trigger WARNING emails with outdated plugin or WordPress version.
Please make sure you respect the WPScan license.
Configuration exemple
Sample configuration file with full featured wp_sites entry, custom WPScan path and arguments, vuln DB api limit handling and email reporting
[wpwatcher]
wp_sites= [ {
"url":"exemple.com",
"email_to":["site_owner@domain.com"],
"false_positive_strings":[
"Yoast SEO 1.2.0-11.5 - Authenticated Stored XSS",
"Yoast SEO <= 9.1 - Authenticated Race Condition"],
"wpscan_args":["--stealthy"]
},
{ "url":"exemple2.com" } ]
wpscan_path=/usr/local/rvm/gems/default/wrappers/wpscan
wpscan_args=[ "--format", "json",
"--no-banner",
"--random-user-agent",
"--disable-tls-checks",
"--api-token", "YOUR_API_TOKEN" ]
api_limit_wait=Yes
send_email_report=Yes
email_to=["me@gmail.com"]
from_email=me@gmail.com
smtp_user=me@gmail.com
smtp_server=smtp.gmail.com:587
smtp_ssl=Yes
smtp_auth=Yes
smtp_pass=P@assW0rd
You can store the API Token in the WPScan default config file at ~/.wpscan/scan.yml and not supply it via the wpscan CLI argument in the WPWatcher config file. See WPSacn readme.
Run wpwatcher --help to see options configurable with CLI.
Email reports
One report is generated per site and the reports are sent individually when finished scanning a website.
See Wiki for more informations.
Output
See Wiki.
Library usage
See Wiki.
Changelog
See Releases
Questions ?
If you have any questions, please create a new issue.
Contribute
If you like the project and think you could help with making it better, there are many ways you can do it:
- Create new issue for new feature proposal or a bug
- Implement existing issues
- Help with improving the documentation
- Spread a word about the project to your collegues, friends, blogs or any other channels
- Any other things you could imagine
- Any contribution would be of great help
Running tests
python3 -m unittest tests.quick_test
Authors
- Florian Roth (Original author of WPWatcher v0.2)
- Tristan Landes
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for wpwatcher-2.2.3-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 651b30826891dd558945933b5675ccac8f598d494d020fc61564d77e962a964f |
|
| MD5 | ecc5b80905868db9dc75399e156b9c88 |
|
| BLAKE2b-256 | 3b744bdf45f19d6e826d735b7d98a1b9ca66efcb352f31f8fa26c0ca469b3fff |
