Metadata-Version: 2.4
Name: wpsniffer
Version: 0.1.0
Summary: YARA-based command-line malware scanner for WordPress and PHP sites
Author: WPSniffer contributors
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://wpsniffer.com
Project-URL: Documentation, https://wpsniffer.com/docs/
Project-URL: Releases, https://github.com/CommanderWaterford/wpsniffer-releases/releases
Project-URL: Issues, https://github.com/CommanderWaterford/wpsniffer-releases/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: packaging>=21.0
Requires-Dist: requests>=2.3
Requires-Dist: pymysql>=0.9.3
Requires-Dist: yara-x>=1.4.0
Dynamic: license-file

# WPSniffer

WPSniffer is a command-line malware scanner for WordPress and PHP sites that
uses free, community-maintained YARA rules, scanned with a
[YARA-X](https://virustotal.github.io/yara-x/) engine.

It has a multi-process scanner, file filters, several report formats (CSV,
TSV, line-delimited, null-delimited and human-readable), email reports and a
progress display. It needs no license key or account.

Website: <https://wpsniffer.com>

See [NOTICE](NOTICE) for the project's origin and licensing details.

## Installation

Requires Python 3.8 or later. Install from [PyPI](https://pypi.org/project/wpsniffer/)
into a virtual environment:

    python3 -m venv ~/wpsniffer
    ~/wpsniffer/bin/pip install wpsniffer
    ~/wpsniffer/bin/wpsniffer version

Every release is also published as a wheel and source archive on the
[GitHub releases page](https://github.com/CommanderWaterford/wpsniffer-releases/releases).
Bug reports and feature requests go to the
[issue tracker](https://github.com/CommanderWaterford/wpsniffer-releases/issues) there.

From a checkout of this repository:

    python3 -m venv .venv
    .venv/bin/pip install .
    .venv/bin/wpsniffer version

## Rules

By default, WPSniffer downloads the
[YARA Forge](https://github.com/YARAHQ/yara-forge) **core** package (about
5,000 rules, including the signature-base PHP webshell rules), caches it in
`~/.cache/wpsniffer`, and checks for a new release once a day. If the download
fails, the cached copy is used.

| Option | Effect |
|---|---|
| `--yara-forge core\|extended\|full\|none` | Choose the YARA Forge package. `core` has the fewest false positives; `extended` and `full` add more rules and more noise. |
| `--yara-forge-release 20261018` | Pin a specific YARA Forge release instead of `latest`. |
| `--rules PATH` | Add your own `.yar`/`.yara` file or directory (repeatable). When `--rules` is given, YARA Forge is only used if `--yara-forge` is also set. |
| `--refresh-rules` | Download the YARA Forge package even if the cache is current. |
| `-e, --exclude-signatures` | Ignore rules by name; wildcards work, e.g. `-e 'SIGNATURE_BASE_SUSP_*'`. |
| `-i, --include-signatures` | Only report the named rules (wildcards work). |

Rules from `--rules` files are compiled in a namespace named after the file,
so they are reported as `filename:RULE_NAME`. Rules that fail to compile are
skipped with a warning (`--debug` shows the errors); the rest are still used.

Compiled rules are cached, so later scans skip compilation. Use `--pre-compile`
to download and compile rules without scanning, for example right after an
update in a cron job.

## Usage

Scan a WordPress install:

    wpsniffer malware-scan /var/www/html

Report every matching rule, with rule metadata, to a CSV file:

    wpsniffer malware-scan --match-all --output-path results.csv \
        --output-columns filename,signature_id,signature_description,rule_score,rule_author,rule_reference,matched_text \
        /var/www/html

Use your own rules together with YARA Forge:

    wpsniffer malware-scan --rules /etc/wpsniffer/rules --yara-forge core /var/www/html

Scan files changed in the last hour:

    find /var/www -cmin -60 -type f -print0 | wpsniffer malware-scan

Run `wpsniffer malware-scan --help` for all options.

### Report columns

`filename`, `signature_id` (rule name), `signature_name`,
`signature_description`, `matched_text` (first matched string, up to 256
bytes), `rule_author`, `rule_reference`, `rule_score`, `rule_tags`.

### Scheduled scans

`malware-scan` reads extra paths from standard input when
it is not a terminal. Under schedulers or CI systems that leave standard input
open, pass `--no-read-stdin` (or redirect `< /dev/null`) so the scan does not
wait for input.

## Scanning behavior

- Rules come from YARA Forge and/or local files.
- Each file is scanned as a whole (up to `--scanned-content-limit`, 50 MiB by
  default), so YARA conditions such as `filesize` work and matches are not
  missed at chunk boundaries.
- `--scan-timeout` limits the time per file (default 10 seconds).
- Available subcommands: `malware-scan`, `count-sites`, `configure`, `help`
  and `version`.
- Configuration lives in `~/.config/wpsniffer/wpsniffer.ini` (or
  `/etc/wpsniffer/wpsniffer.ini`) and the cache in `~/.cache/wpsniffer`.

## Development

    .venv/bin/pip install -e . pytest flake8
    .venv/bin/python -m pytest wpsniffer
    .venv/bin/python -m flake8 wpsniffer

## License

GPLv3. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
