Wordfence CLI 文档

Wordfence CLI 文档，介绍命令行安全扫描用法。

Autocomplete of CLI's Subcommands and Parameters

The source code for Wordfence CLI comes with a script that can be used to automatically suggest or fill in subcommands and command line parameters. To use these autocompletions from bash, you can run source ./scripts/complete.bash from the base of the source code directory. If you are using zsh, you can run the following prior to running source on the bash completion file:

autoload -Uz +X compinit && compinit
autoload -Uz +X bashcompinit && bashcompinit

Once this is done, you can use the Tab key to suggest subcommands or parameters when running wordfence from the command line.

Examples

$ source wordfence-cli/scripts/complete.bash 
$ wordfence vuln-scan -
--accept-terms              -E                          -l                          --no-debug                  --output                    --quiet                     --smtp-user
--banner                    --email                     -L                          --no-help                   --output-columns            --read-stdin                -t
-c                          --email-from                --license                   --no-informational          --output-format             --relative-content-path     --theme-directory
-C                          --exclude-vulnerability     --log-level                 --no-output                 --output-headers            --relative-mu-plugins-path  -v
--cache                     -f                          -m                          --no-output-headers         --output-path               --relative-plugins-path     --verbose
--cache-directory           --feed                      -M                          --no-prefix-log-levels      -p                          --require-path              --version
--check-for-update          -h                          --no-accept-terms           --no-purge-cache            -P                          -s                          -w
--color                     --help                      --no-banner                 --no-quiet                  --path-separator            --sendmail-path             --wfi-url
--configuration             -i                          --noc1-url                  --no-read-stdin             --plugin-directory          --smtp-host                 --wordpress-path
-d                          -I                          --no-cache                  --no-require-path           --prefix-log-levels         --smtp-password             
--debug                     --include-vulnerability     --no-check-for-update       --no-verbose                --purge-cache               --smtp-port                 
-e                          --informational             --no-color                  --no-version                -q                          --smtp-tls-mode             

$ wordfence malware-scan -
-a                       --debug                  --images                 -n                       --no-include-all-files   --output-columns         -s                       --wfi-url
--accept-terms           -e                       --include-all-files      -N                       --no-match-all           --output-format          --scanned-content-limit  --workers
--allow-io-errors        -E                       --include-files          --no-accept-terms        --no-output              --output-headers         --sendmail-path          -x
--banner                 --email                  --include-files-pattern  --no-allow-io-errors     --no-output-headers      --output-path            --smtp-host              -X
-c                       --email-from             --include-signatures     --no-banner              --no-prefix-log-levels   --pcre-backtrack-limit   --smtp-password          -z
--cache                  --exclude-files          -l                       --noc1-url               --no-progress            --pcre-recursion-limit   --smtp-port              
--cache-directory        --exclude-files-pattern  -L                       --no-cache               --no-purge-cache         --prefix-log-levels      --smtp-tls-mode          
--check-for-update       --exclude-signatures     --license                --no-check-for-update    --no-quiet               --progress               --smtp-user              
--chunk-size             --file-list-separator    --log-level              --no-color               --no-read-stdin          --purge-cache            -v                       
--color                  -h                       -m                       --no-debug               --no-verbose             -q                       --verbose                
--configuration          --help                   -M                       --no-help                --no-version             --quiet                  --version                
-d                       -i                       --match-all              --no-images              --output                 --read-stdin             -w

Configuration

Configuration can be set through command line arguments, or configured globally through the wordfence-cli.ini file. Once Wordfence CLI is installed, we recommend running wordfence configure to interactively configure Wordfence CLI's global options.

wordfence configure Command Line Arguments

Global Command Line Arguments

These arguments apply to all subcommands.

General Options:

Output Control:

Email:

Logging:

Caching:

wordfence-cli.ini

By default, the configuration file will reside at ~/.config/wordfence/wordfence-cli.ini. This INI file is best suited for global configuration options for Wordfence CLI. The license is the only item that's typically configured here.

Global INI Options

[DEFAULT]
license = <your license key>
verbose = [on|off]
debug = [on|off]
banner = [on|off]
quiet = [on|off]
email = <recipient email address for reports>
email_from = <sender email address for reports>
smtp_host = <hostname of SMTP server for mailing reports>
smtp_port = <port for SMTP server for mailing reports>
smtp_tls_mode = [none|smtps|starttls]
smtp_user = <username>
smtp_password = [on|off]
sendmail_path = <path to sendmail executable, used when SMTP is not configured>
cache_directory = <path to a directory to use for caching>
cache = [on|off]

Subcommand INI Options

See documentation for each subcommand for its respective INI options. Most command line options can also be set in the INI file. Generally, only settings that should be applied every time CLI is invoked should be stored in the config file. For example, don't store options specific to one site being scanned in the global config file. Global options may also be overwritten for each subcommand section.

Email

Wordfence CLI can be configured to send a summary of scan results (both the malware scan and the vulnerability scan) to an email address. The email will only send when the scan actually finds something, for instance a file contains malware, or a WordPress plugin has a vulnerability. An email will also not be sent in the event a scan fails. We recommend reviewing scan findings regularly.

Configuration

The following command line arguments can be supplied to either the malware scan or the vulnerability scan to tell CLI how to send email. If using SMTP, we recommend storing the configuration in the INI rather than supplying credentials as command line parameters.

If you do not have access to an external SMTP server, sendmail can be used as a local relay. We recommend going through the process of authenticating your server as an email sender using SPF, DKIM, and DMARC to prevent emails from CLI from being flagged as spam.

Attaching Output Files

Using the --output-path option in conjunction with --email will cause the output file to be added as an attachment to the emailed report.

Further reading

Frequently Asked Questions

How do I get a license?

Licenses can be obtained at https://www.wordfence.com/products/wordfence-cli/.

The scanner has identified malware. What do I do now?

If you do not know what the file is, we recommend making a backup before you remove it, in case it was a false positive. We always recommend saving a backup copy of the file first, whether by making a full backup of the system or by saving only the file and the location where it belongs, so you can replace it if necessary.

What permissions are required to install/run CLI?

Wordfence CLI can be installed and run as any user, including root. When installing using pip as root, pip will return a warning about running as root. Using that installation method, we recommend installing using pip as a non-priveledged user.

What the difference is between Wordfence CLI and WP-CLI?

Wordfence CLI is a stand-alone, command-line, malware scanner written in Python. WP-CLI is a WordPress command-line utility for managing a WordPress installation written in PHP. They are 2 separate and distinct pieces of software and are unrelated.

If I have Wordfence CLI, do I need the Wordfence plugin too?

If you are a WordPress site owner who is looking for a security solution, the Wordfence plugin offers comprehensive protection and intrusion detection. Wordfence CLI can be used alongside the Wordfence plugin. Wordfence CLI would be used instead of the malware detection functionality of the Wordfence plugin's scan.

If I want to run Wordfence CLI alongside the Wordfence plugin, as a replacement for the malware scanner, are there any scanner settings I can turn off in the plugin to reduce redundancy?

Yes. Within the Wordfence plugin scan options, you can disable the "Scan file contents for backdoors, trojans and suspicious code" scan option and rely on Wordfence CLI to perform the malware scan.

I got the error "Failed to locate libpcre". What do I do?

Wordfence CLI uses the libpcre library to run our signatures against files. There's a few ways to install it depending on your system:

For Debian/Ubuntu flavors of Linux:

apt-get install libpcre

Or

apt-get install libpcre3

For Red Hat/Fedora based Linux distributions:

dnf install pcre

How often are signatures refreshed locally?

Once every 24 hours. You can use the --purge-cache command line argument to refresh the signature set.

How many workers can I run on my system?

That's really up to you, but we recommend for a fast scan two workers per CPU core.

What is the most performant way recommended to run a scan?

We recommend two workers per CPU core for the fastest possible scan. For busy production systems, we recommend limiting the worker count to reduce the impact on the availability of production services.

What file types are scanned by default?

The default scan will scan .php, .phtml, .html, .js, and .svg files by default. Using the --images option will expand the file list to .jpg, .jpeg, .mp3, .avi, .m4v, .mov, .mp4, .gif, .png, .tiff, .svg, .sql, .js, .tbz2, .bz2, .xz, .zip, .tgz, .gz, .tar, .log, .err. If there are specific file types you want to match, you can use the --include-files or --include-files-pattern to define a custom set of files/file types to scan. See the configuration for more details.

I got the error "Unable to locate content directory for site at /path/to/wordpress". What do I do?

This is likely from a WordPress installation using a custom wp-content directory. There are a number of things CLI will check to determine where plugin and theme files are stored:

If we are unable to find a path from either of those checks, CLI will return this error. You can use one of the following command line parameters to tell CLI where to find plugins and themes:

Why am I receiving a "Rate limit reached" error message?

Some Wordfence API endpoints used by CLI have rate limits in place to prevent abuse. CLI has a built-in caching mechanism that should avoid rate limits when using the default configuration.

If you encounter this error, ensure that caching is enabled.

Do I need to enable caching? How does it work?

Yes, caching is necessary to avoid API rate limits and ensure CLI performs as expected. It should only ever be disabled temporarily for debugging purposes.

The cache utilizes filesystem storage, saving data to a directory configurable via the --cache-directory option on the command line or the cache_directory directive in the INI file. By default, this is set to ~/.cache/wordfence.

If using CLI with the same license across multiple hosts, consider using a shared cache via a network filesystem (it must support flock) or upgrading to a paid license for higher rate limits.

Installation

Installation with pip

This is the simplest method for installing CLI.

pip install wordfence

This should build and install an executable of Wordfence CLI at the following directory when run as the username user:

/home/username/.local/bin/wordfence

If run as root, the executable path should be:

/usr/local/bin/wordfence

Verify the executable works correctly on your system:

wordfence version

You should see output similar to this:

Wordfence CLI 3.0.1

Once this is done, we recommend reviewing the configuration to go through configuring a license followed by running your first scan.

Install the Debian package

This method will work for Debian and Debian-based Linux distros (Ubuntu, Linux Mint, Kali, etc) where you have root access to the system.

sudo apt install ./wordfence.deb

For older distros, you can also use the following commands to install CLI.

sudo dpkg -i wordfence.deb
sudo apt -f install

Verify the executable works correctly on your system:

wordfence --version

You should see output similar to this:

Wordfence CLI 3.0.1

Once this is done, we recommend reviewing the configuration to go through configuring a license followed by running your first scan.

Install the RPM package

This method will work for Red Hat Enterprise Linux 9 and compatible distributions (AlmaLinux, Rocky Linux, etc) where you have root access to the system. You must have the CodeReady Linux Builder (CRB) repo enabled before installing.

On RHEL, run:

subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms

On RHEL-compatible distributions, run:

dnf config-manager --set-enabled crb

You should now be able to install the RPM package:

sudo dnf install ./wordfence-el9.rpm

Verify the executable works correctly on your system:

wordfence version

You should see output similar to this:

Wordfence CLI 3.0.1

Once this is done, we recommend reviewing the configuration to go through configuring a license followed by running your first scan.

Binaries

Binaries for Wordfence CLI can be downloaded on the Releases page of the GitHub repository (under Assets of each release) along with source code, and the .whl files:

https://github.com/wordfence/wordfence-cli/releases

The binary files are in the format wordfence_yyyy.tar.gz where yyyy is the CPU architecture. The following example uses AMD64 as the architecture.

We recommend verifying the authenticity of the download prior to extracting the archive. You can do this by following the steps outlined below prior to following the rest of these installation steps.

Extract the binary:

tar xvzf wordfence_amd64.tar.gz

Verify the binary works correctly on your system:

./wordfence version

You should see output similar to this:

Wordfence CLI 3.0.1

Once this is done, we recommend reviewing the configuration to go through configuring a license followed by running your first scan.

Docker

To install Wordfence CLI using Docker, you can clone the GitHub repo to your local environment:

git clone git@github.com:wordfence/wordfence-cli.git
cd ./wordfence-cli
docker build -t wordfence-cli:latest .

Once the Docker image is built, you can start the docker container with the volumes you wish to scan:

docker run -v /var/www:/var/www wordfence-cli:latest version

You should see output similar to this:

Wordfence CLI 3.0.1

Once this is done, we recommend reviewing the configuration to go through configuring a license followed by running your first scan.

Manual Installation

To install Wordfence CLI manually, you can clone the GitHub repo to your local environment:

git clone git@github.com:wordfence/wordfence-cli.git
cd ./wordfence-cli
pip install .
python main.py version

You can additionally build the wheel archive and generate an executable:

pip install build~=0.10
python -m build --wheel
pip install dist/wordfence-*.whl

The executable should be installed to ~/.local/bin/wordfence.

If you encounter an error about libpcre.so similar to this one:

OSError: libpcre.so: cannot open shared object file: No such file or directory

You may need to install the libpcre library.

Verifying the Authenticity of a Release Asset

The checksum file for all release assets is sgned using GPG as part of the build process. We recommend verifying the authenticity of the checksum file and then verifying the checksum of the downloaded release asset prior to extracting, installing, or executing any code.

To verify the signature of the checksums file, first download and import our public GPG key:

wget https://www.wordfence.com/wp-content/uploads/public.asc
gpg --import public.asc

You can optionally sign our public key with your own private key:

gpg --lsign-key 00B225C7030F26FF4A3D3481F82623ECE1DB0FBB

Download the checksums.txt and checksums.txt.asc files from GitHub releases. You can then verify the authenticity of the checksums.txt file (replace the filenames with paths to the copies you've downloaded):

gpg --assert-signer 00B225C7030F26FF4A3D3481F82623ECE1DB0FBB --verify checksums.txt.asc checksums.txt

If your version of GPG doesn't include --assert-signer you can just run (you may see a warning using this method):

gpg --verify checksums.txt.asc checksums.txt

You should see output similar to this:

gpg: Signature made Fri Aug 18 16:27:11 2023 EDT
gpg:                using EDDSA key 00B225C7030F26FF4A3D3481F82623ECE1DB0FBB
gpg:                issuer "opensource@wordfence.com"
gpg: Good signature from "Wordfence <opensource@wordfence.com>" [ultimate]
gpg: signer '00B225C7030F26FF4A3D3481F82623ECE1DB0FBB' matched

Now that you've verified the checksums file, you can confirm that the checksum of your download matches. For example, if you downloaded the wordfence_amd64.tar.gz (the standalone Linux executable for the x86_64 architecture) to the same directory as checksums.txt, you can verify the checksum matches with:

sha256sum --ignore-missing -c checksums.txt

Output

By default Wordfence CLI will print a banner followed by which paths it was supplied for scanning:

             ▓▓▓                                                                   
        ▓▓▓▓▓   ▓▓▓▓▓          _       __               __  ____                   
  ▓▓▓▓▓▓▓           ▓▓▓▓▓▓▓   | |     / /___  _________/ / / __/__  ____  ________ 
 ▓▓           ▓           ▓▓  | | /| / / __ \/ ___/ __  /_/ /_/ _ \/ __ \/ ___/ _ \
▓▓     ▓▓    ▓▓▓    ▓▓     ▓▓ | |/ |/ / /_/ / /  / /_/ /_  __/  __/ / / / /__/  __/
▓▓      ▓     ▓     ▓      ▓▓ |__/|__/\____/_/   \____/ /_/  \___/_/ /_/\___/\___/ 
▓▓    ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    ▓▓                                       ____ _     ___ 
▓▓  ▓▓▓ ▓    ▓▓▓    ▓ ▓▓▓  ▓▓                                      / ___| |   |_ _|
▓▓▓▓▓   ▓    ▓▓▓    ▓   ▓▓▓▓▓                                     | |   | |    | | 
 ▓▓     ▓   ▓▓ ▓▓   ▓     ▓▓                                      | |___| |___ | | 
  ▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓                                        \____|_____|___|
                                                                                   
Scanning path: /var/www/
Scanning path: /home/user/

Files found that match a signature matches are printed in the output as well. There are additionally the --verbose and --debug options that can be used to get further information about what Wordfence CLI is doing under the hood.

Report Formats

The report is a separate output stream generated by Wordfence CLI that will contain a list of the files detected by one of our signatures. Use --output-columns to configure which columns are written to the report. Available columns: filename, signature_id, signature_name, signature_description, matched_text.

Wordfence CLI Subcommands

Wordfence CLI provides a variety of subcommands to support different use cases. The following subcommands are currently available:

Updating your Installation

Updating with pip

Use the following to update to the latest release of Wordfence CLI:

pip install --upgrade wordfence

Binaries

The releases page in GitHub will have the most recently available binaries for download:

https://github.com/wordfence/wordfence-cli/releases

The binary files are in the format wordfence_yyyy.tar.gz where yyyy is the CPU architecture. The following example uses AMD64 as the architecture.

We recommend verifying the authenticity of the download prior to extracting the archive. You can do this by following the steps outlined in the installation document prior to following the rest of these updating steps.

Extract the binary:

tar xvzf wordfence_amd64.tar.gz

Verify the binary works correctly on your system:

./wordfence version

You should see output similar to this:

Wordfence CLI 2.0.1

Copy the binary to the path you've installed your existing Wordfence CLI binary.

Docker

If you've followed our installation instructions for Docker, you can cd into the source code directory and run git pull to fetch the latest version. The main branch is kept up-to-date with the most recent stable release.

Manual Installation

Updating a manual/development installation can be done by using git pull in the source code directory. The main branch is kept up-to-date with the most recent stable release.

Site Counting Configuration

Site counting can be configured using either command line arguments, the INI file, or a combination of both.

Command Line Arguments

INI Options

[COUNT_SITES]
# Read paths from stdin
read_stdin = [on|off]
# Separator string when reading paths from stdin, defaults to null byte
path_separator = <separator>
allow_nested = [on|off]
allow_io_errors = [on|off]

Examples

Count the number of WordPress sites under /var/www

wordfence count-sites /var/www

Database Scan Configuration

Database scanning can be configured using either command line arguments, the INI file, or a combination of both.

Command Line Arguments

INI Options

[DB_SCAN]
# The name of an environment variable containing the database password to use
password_env = <variable>
# Read paths from stdin
read_stdin = [on|off]
# Separator string when reading paths from stdin, defaults to null byte
path_separator = <separator>
# Controls whether or not output is written to stdout
output = [on|off]
output_path = <path to which to write results>
# Comma-delimited list of columns to include in output (`table`, `rule_id`, `rule_description`, `row`)
output_columns = <columns>
output_format = [human|csv|tsv|null-delimited|line-delimited]
# Whether to include headers in output
output_headers = [on|off]
allow_nested = [on|off]
allow_io_errors = [on|off]
use_remote_rules = [on|off]
rules_file = <path>
# Comma-delimited list of rule IDs
exclude_rules = <rules>
include_rules = <rules>

JSON Configuration

When --locate-sites is not used, each trailing argument should be a JSON file containing a list of database configurations in the following shape:

[
  {
    "name": "wordpress",
    "user": "wordpress",
    "password": "example",
    "host": "db.example.com",
    "port": 3306,
    "collation": "utf8mb4_unicode_ci",
    "prefix": "wp_"
  }
]

Entries may omit port, collation, or prefix; defaults are applied automatically.

When databases are discovered through --locate-sites or provided via JSON files, connection details from those sources override the command-line defaults for each database.

Examples

Scanning a single WordPress database

Scan a WordPress database using explicit connection settings and prompt for the password at runtime.

wordfence db-scan -H db.example.com -P 3306 -u wordpress -D wordpress --prompt-for-password

Automatically locating WordPress installations

Search the supplied directories for wp-config.php, extract the database credentials, and scan each discovered site.

wordfence db-scan -S /var/www/wordpress /srv/wordpress

Scanning databases listed in a JSON file

Provide a JSON file that lists one or more database configurations. Each entry must include name, user, password, and host, with optional port, collation, and prefix values. Multiple JSON files can be supplied.

wordfence db-scan /etc/wordfence/databases.json

Writing database scan results to a CSV

Output scan results to a CSV file with headers and explicitly selected columns.

wordfence db-scan -S /var/www/wordpress --output-format csv --output-columns table,rule_description,row --output-headers --output-path /home/username/db-scan-results.csv

Malware Scan Configuration

Malware scanning can be configured using either command line arguments, the INI file, or a combination of both.

Command Line Arguments

INI Options

[MALWARE_SCAN]
# Read file paths to scan from stdin
read_stdin = [on|off]
file_list_separator = <separator string, defaults to null byte>
# Controls whether or not output is written to stdout
output = [on|off]
output_path = <path to which to write results>
# Comma-delimited list of columns to include in output (`filename`, `signature_id`, `signature_name`, `signature_description`, `matched_text`)
output_columns = <columns>
output_format = [human|csv|tsv|null-delimited|line-delimited]
# Whether to include headers in output
output_headers = [on|off]
# Comma-delimited list of signature IDs
exclude_signatures = <signatures>
include_signatures = <signatures>
images = [on|off]
include_all_files = [on|off]
# Comma-delimited list of filenames
include_files = <filenames>
exclude_files = <filenames>
# Comma-delimited list of Python regex patterns
include_files_pattern = <patterns>
exclude_files_pattern = <patterns>
allow_io_errors = [on|off]
# Files are scanned in chunks of this size, may use b, k, or m suffix
chunk_size = <size>
# Maximum amount of data to scan for each file, may use b, k, or m suffix
scanned_content_limit = <size>
match_engine = [pcre|vectorscan]
match_all = [on|off]
# Backtrack limit option for PCRE, should be an integer
pcre_backtrack_limit = <limits>
# Number of workers to use
workers = <number>
# Alternate database path when using vectorscan
pattern_database_path = <path>
# Whether or not to compile the vectorscan database locally
compile_local = [on|off]
# Toggle direct IO (avoids filesystem caching)
direct_io = [on|off]

Examples

Scanning a single directory for malware

A basic example of recursively scanning the /var/www directory for malware.

wordfence malware-scan /var/www

Writing malware scan results to a CSV

A basic example of recursively scanning the /var/www directory for malware and writing the results to /home/username/wordfence-cli-scan.csv.

wordfence malware-scan --output-format csv --output-path /home/username/wordfence-cli-scan.csv /var/www

Running Wordfence CLI in a cron

Run Wordfence CLI in a cron job daily to scan /var/www and email the results to example@example.com. The results are also written to /home/username/wordfence-cli-scan.csv as the username user. This would be similar to how a scheduled scan works within the Wordfence plugin.

0 0 * * *  username /usr/bin/flock -w 0 /tmp/wordfence-cli-scan.lock /usr/local/bin/wordfence malware-scan --output-format csv --output-path /home/username/wordfence-cli-scan.csv --email example@example.com /var/www 2>&1 /var/log/wordfence/malware-scan.log; /usr/bin/rm /tmp/wordfence-cli-scan.lock

The cronjob uses a lock file at /tmp/wordfence-cli-scan.lock to prevent duplicate scans from running at the same time. Any output and errors are logged to /var/log/wordfence/malware-scan.log. Please update the paths from this example based on the system this is intended to run on.

Piping files from find to Wordfence CLI

Find files under the directory /var/www/ that have changed in the last hour and scan them with Wordfence CLI:

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

We recommend that you use ctime over mtime and atime as changing the ctime of a file requires root access to the file system. mtime and atime can be arbitrarily set by the file owner using the touch command.

Automatically repairing known files belonging to WordPress

Run Wordfence CLI on a WordPress installation under /var/www/wordpress and automatically repair any files infected with malware:

wordfence malware-scan --output-columns filename -m null-delimited /var/www/wordpress | wordfence remediate

Automatically repairing known files, and automatically deleting unknown files

Run Wordfence CLI on a WordPress installation under /var/www/wordpress and automatically repair any files infected with malware. For any additional files found that aren't automatically repaired, delete them:

wordfence malware-scan --output-columns filename -m null-delimited /var/www/wordpress | wordfence remediate --output-columns path -m null-delimited -u | xargs -0 rm

Remediation

Wordfence CLI, as of version 3.0.1, comes with a new subcommand, wordfence remediate, to automatically repair known files belonging to a WordPress installation. Any file part of all versions of WordPress core, as well as all versions of plugins and themes available for download on wordpress.org can be automatically downloaded to restore a file infected with malware.

To see remediate in action, visit the examples page.

Remediate Command Line Arguments

General Options:

Output Control:

Faster Scanning with Vectorscan

The malware scan currently has 2 separate scan signature engines, libpcre and Vectorscan. While both of these scan engines are highly performant, Vectorscan is software designed to address the specific use-case we have with malware scanning, where we need to run a large number of regular expressions against a stream of data.

Benchmarks for Performance Increase using Vectorscan

Benchmarking has indicated that Vectorscan can be more than 30 times as fast as the exact same scan on the exact same hardware using PCRE.

Files Matches Data Workers PCRE Time Vectorscan Time Improvement Library CPU
12,006 11,998 605.4 MiB 1 388s 16s ~25x Hyperscan 5.2.1 AMD Ryzen 7 1700
3,499 1 54.7 MiB 4 42s 3s 14x Hyperscan 5.2.1 AMD Ryzen 7 1700
25905 25001 1.7 GiB 32 38s 4s ~10x Hyperscan 5.4.0 AMD Ryzen 9 5950X
25905 25001 1.7 GiB 8 98s 3s ~32x Hyperscan 5.4.0 AMD Ryzen 9 5950X
25905 25001 1.7 GiB 4 191s 6s ~32x Hyperscan 5.4.0 AMD Ryzen 9 5950X
25905 25001 1.7 GiB 1 710s 21s ~34x Hyperscan 5.4.0 AMD Ryzen 9 5950X

(The above benchmarks were conducted using a free Wordfence CLI license)

Configuring CLI to use Vectorscan

By default, CLI will use libprce for scanning. To configure CLI to use Vectorscan, you can use the following command-line argument:

wordfence malware-scan --match-engine=vectorscan

This can also be set in the INI file:

[MALWARE_SCAN]
match_engine=vectorscan

Installing Vectorscan/Hyperscan

On Debian-based distros, Vectorscan can be installed with apt:

$ sudo apt install libvectorscan5

Vectorscan is a fork of Hyperscan and maintains a compatible API, so installing Hyperscan on Intel-based systems will work as well.

$ sudo apt install libhyperscan5

We do currently support both technologies, but this may change over time if Vectorscan's API diverges from Hyperscan's. We will officially support Vectorscan going forward.

Additional installation instructions can be found in the Vectorscan Wiki.

Downloading/Compiling Vectorscan signatures

When running a supported version of vectorscan on a supported platform, a pre-compiled Vectorscan signature database will be downloaded from the Wordfence servers automatically. This is currently rate limited to 1 request every 12 hours. Ensure that caching is enabled to avoid hitting this rate limit (the database is cached for 24 hours by default).

Alternatively, you may use the --compile-local option to pull the standard signatures from the Wordfence API and compile them to a platform-specific Vectorscan database locally. This will avoid the above rate limit but will take a significant amount of time during the scan.

Known issues

Segfaults on Ubuntu versions 22.04 and 24.04

The Vectorscan package provided by Ubuntu versions 22.04 and 24.04 will produce segfaults when performing malware scanning against certain files on some ARM systems. We've identified that this is an issue specifically with the packaged version. Compiling Vectorscan from scratch does not produce the same segfaults. We've created a ticket on LaunchPad for this issue.

Negligible Performance Improvement over NFS

CLI will oftentimes have to scan large filesystems of relatively small files. NFS is not setup particularly well to serve many small files. Vectorscan can scan these small files fast enough where there can be not much of discernible difference between using libprce and Vectorscan since the scanning processes are largely I/O bound while waiting on NFS to provide the file contents.

We've observed in our own benchmarks that there is not a significant performance increase using Vectorscan over libpcre for filesystems over NFS shares.

Remediation Configuration

Remediation can be configured using either command line arguments, the INI file, or a combination of both.

Command Line Arguments

INI Options

[COUNT_SITES]
# Read paths from stdin
read_stdin = [on|off]
# Separator string when reading paths from stdin, defaults to null byte
path_separator = <separator>
allow_nested = [on|off]
allow_io_errors = [on|off]

Examples

Restore the original contents of a plugin file

wordfence remediate /var/www/html/wp-content/plugins/hello.php

Restore all files in a theme directory and output the results to a CSV file

wordfence remediate --output-format csv --output-path /tmp/wfcli-remediation-results.csv --output-headers /var/www/html/wp-content/themes/twentytwentythree

Automatically deletect and remediate malware under /var/www/wordpress

wordfence malware-scan --output-columns filename -m null-delimited /var/www/wordpress | wordfence remediate

Vulnerability Scan Configuration

Vulnerability scanning can be configured using either command line arguments, the INI file, or a combination of both.

Command Line Arguments

INI Options

[VULN_SCAN]
# Read WordPress paths from stdin
read_stdin = [on|off]
# Separator to use when reading paths from stdin, defaults to null byte
path_separator = <separator>
# Alternate relative path for wp-content
relative_content_path = <path>
# Alternate relative path for wp-content/plugins
relative_plugins_path = <path>
# Alternate relative path for wp-content/mu-plugins
relative_mu_plugins_path = <path>
# Controls whether or not output is written to stdout
output = [on|off]
output_path = <path to which to write results>
# Comma-delimited list of columns to include in output (`software_type`, `slug`, `version`, `id`, `title`, `link`, `description`, `cve`, `cvss_vector`, `cvss_score`, `cvss_rating`, `cwe_id`, `cwe_name`, `cwe_description`, `patched`, `remediation`, `published`, `updated`, `scanned_path`)
output_columns = <columns>
output_format = [human|csv|tsv|null-delimited|line-delimited]
# Whether to include headers in output
output_headers = [on|off]
# Comma-delimited list of vulnerability UUIDs or CVE IDs
exclude_vulnerability = <ids>
include_vulnerability = <ids>
# Toggle informational vulnerabilities
informations = [on|off]
feed = [production|scanner]
allow_nested = [on|off]
allow_io_errors = [on|off]

Examples

Scanning a single WordPress installation for vulnerabilities

A basic example of scanning the /var/www/wordpress directory for vulnerabilities.

wordfence vuln-scan /var/www/wordpress

Writing vulnerability scan results to a CSV

A basic example of scanning the /var/www/wordpress directory for vulnerabilities and writing the results to /home/username/wordfence-cli-vuln-scan.csv.

wordfence vuln-scan --output-format csv --output-path /home/username/wordfence-cli-vuln-scan.csv /var/www/wordpress

Running the vulnerability scan in a cron

Run Wordfence CLI in a cron job daily to scan /var/www/wordpress and write the results to /home/username/wordfence-cli-vuln-scan.csv as the username user. This would be similar to how a scheduled scan works within the Wordfence plugin.

0 0 * * *  username /usr/bin/flock -w 0 /tmp/wordfence-cli-vuln-scan.lock /usr/local/bin/wordfence vuln-scan --output-format csv --output-path /home/username/wordfence-cli-vuln-scan.csv /var/www/wordpress 2>&1 /var/log/wordfence/vuln-scan.log; /usr/bin/rm /tmp/wordfence-cli-vuln-scan.lock

The cronjob uses a lock file at /tmp/wordfence-cli-vuln-scan.lock to prevent duplicate vulnerability scans from running at the same time. Any output and errors are logged to /var/log/wordfence/vuln-scan.log. Please update the paths from this example based on the system this is intended to run on.