Description

PHP Antimalware Scanner is a free tool to scan PHP files and analyze your project to find any malicious code inside it.

It provides an interactive text terminal console interface to scan a file, or all files in a given directory (file paths can also be managed using --filter-paths or --ignore-paths), and find PHP code files that seem to contain malicious code. When a probable malware is detected, will be asked what action to take (like add to the whitelist, delete files, try clean infected code, etc).

Interactive fixes show a unified diff before confirmation. PHP-family files must pass php -l, and files changed with vim or nano are rescanned before they can be marked as cleaned. Automated editor choices are rejected because terminal editors require an interactive session.

The package can also scan the PHP files in a report mode (--report|-r), so without interacting and outputting anything to the terminal console. In that case, the results will be stored in a report file in HTML (default) or text format (--report-format <format>).

This scanner can work on your own php projects and on a lot of other platforms using the right combination of configurations (ex. using --lite|-l flag can help to find less false positivity).

:warning: Remember that you will be solely responsible for any damage to your computer system or loss of data that results from such activities. You are solely responsible for adequate protection and backup of the data before executing the scanner.

How to contribute

Have an idea? Found a bug? Please raise to ISSUES or PULL REQUEST. Contributions are welcome and are greatly appreciated! Every little bit helps.

WordPress report findings include a Report finding action that drafts a formatted public issue from legacy matches or canonical malware file signatures, with signature metadata and the file SHA-256 while excluding local paths and matched code. Do not upload executable malware to a public issue; maintainers can arrange a private sample transfer when needed.

Releases

• Update version number in composer.json
• Update composer hash with composer update --lock
• Build a phar file for dist/scanner
• Update version number in dist/version
• Commit and set Git tag
• Add release on GitHub
• Celebrate 🥳

WordPress plugin releases

The Antimalware Scanner dashboard automatically refreshes active scan status, shows live checked-file progress with elapsed and estimated remaining time, and summarizes recent activity. Its Security overview shows the current deduplicated unresolved finding count rather than a cumulative historical detection total. The main WordPress admin dashboard also shows a security status gauge, the latest scan, unresolved detections, malware detected, quarantined files, and a link to the latest report. Settings use collapsible panes, with Scan policy kept visible, plus a server-side folder explorer for local scan and private storage paths or a validated FTP/FTPS URL for read-only remote scans. FTP passwords remain in the server environment and are never saved in WordPress. The active plugin directory and private scanner data are always excluded from local scans. Browser edits receive a server-generated side-by-side diff and PHP syntax check before confirmation, then a focused malware rescan after saving. An About screen links installed version details and project credits to the plugin guide, scanner documentation, contribution guidance, and support.

WordPress plugin releases use separate wordpress-vX.Y.Z tags:

The tag workflow publishes the installable ZIP with GitHub-generated release notes. Publication requires a synchronized main or master branch; suffixed versions become prereleases. See plugins/wordpress/README.md for the complete process.

:blue_book: Requirements

• php 7.4+ (PHP 8.x recommended)
  • php-xml
  • php-zip
  • php-mbstring
  • php-json
  • php-common
  • php-curl
  • php-ftp (optional, required for FTP scans)
  • php-gd

:book: Install

WordPress Plugin

Download and copy to wp-content/plugins/amwscan, then activate Antimalware Scanner in WordPress. Scan history supports WordPress-style bulk archiving, restore, and confirmed permanent deletion. See the WordPress plugin guide for installation and dashboard workflows, or the plugin README for development and release details.

Upload protection is enabled by default. The plugin scans media and plugin or theme ZIP uploads before WordPress accepts them, blocks detected or incompletely scanned files, and saves the result as a report. ZIP inspection requires ext-zip in the WordPress PHP runtime.

Manual and scheduled WordPress ZIP inspection is disabled by default. Administrators can enable bounded archive scanning under Antimalware > Settings > Scope and limits; standalone CLI scans require --scan-archives. Large or highly compressed archives can increase scan time and resource usage, and entries beyond the safety limits are reported as incomplete coverage.

Release

You can use one of these methods to install the scanner by downloading it from GitHub or directly from the console.

Download

Go to the GitHub page and press on the Releases tab or download the raw file from:

Console

1. Run this command from the console (the scanner will be downloaded to your current directory):

   wget https://raw.githubusercontent.com/marcocesarato/PHP-Antimalware-Scanner/master/dist/scanner

2. Run the scanner:

   php scanner ./dir-to-scan -l ...

3. (Optional) Install as bin command (Unix Bash)

   Run this command:

   Now you can run the scanner simply with this command: awscan ./dir-to-scan -l...

Composer

The package is available on Packagist.

Global Installation (recommended)

For system-wide installation, use:

After installation, run the scanner using:

Or create an alias for easier usage:

Then you can run: amwscan <path-to-scan> [options]

Project-Level Installation

For installing within a specific project:

After installation, run the scanner using:

Source

Download

Click the GitHub page "Clone or download" or download from:

Git

1. Install git
2. Copy the command and link from below in your terminal: git clone https://github.com/marcocesarato/PHP-Antimalware-Scanner
3. Change directories to the new ~/PHP-Antimalware-Scanner directory: cd ~/PHP-Antimalware-Scanner/
4. To ensure that your master branch is up-to-date, use the pull command: git pull https://github.com/marcocesarato/PHP-Antimalware-Scanner
5. Enjoy

:whale: Docker

1. Download the source
2. Build command docker build --tag amwscan-docker .
3. Run command docker run -it --rm amwscan-docker bash

:test_tube: Testing

The project includes a comprehensive test suite with unit and integration tests.

Running Tests

Writing Tests

Tests are organized into:

• Unit Tests (tests/Unit/) - Fast, isolated tests for individual classes
• Integration Tests (tests/Integration/) - CLI execution tests with various configurations
• Test Fixtures (tests/Fixtures/) - Sample files for testing (clean, malware, obfuscated)

For detailed information on writing and debugging tests, see TESTING.md.

Continuous Integration

Tests run automatically on pull requests and pushes across multiple PHP versions (7.4, 8.0, 8.1, 8.2, 8.3).

:mag_right: Scanning mode

The first think you need to decide is the strength, you need to calibrate your scan to find less false positive as possible during scanning without miss for real malware. For this you can choose the aggression level.

The scanner permit to have some predefined modes:

:computer: Usage

Command line

Use --debug only while troubleshooting. It displays PHP runtime errors and warnings for the current scan.

Doesn't work?

In case above command doesn't work, you can use script responsible for malware scan manually by executing: php dist/scanner <path>

To check all options check the Documentation

Suggestions

If you are running the scanner on a Wordpress project or other popular platform use --only-signatures or --lite flag to have check with less false positive but this could miss some dangerous exploits like nano.

Platform checksum verification

Checksum verification is enabled by default for WordPress and WordPress plugins such as WooCommerce, as well as Joomla, Drupal, Magento Open Source, and public Composer packages. The scanner detects the installed version and retrieves per-file checksums from the platform's official API or release repository. Composer package manifests are derived from the exact distribution archive independently resolved through Packagist. Missing files under package test and tests directories are ignored because production packages may intentionally omit them. Files whose bytes exactly match an official release are skipped; modified, generated, and untracked files are still scanned. When a WordPress plugin differs from its trusted manifest, the report emits one warning for the plugin directory rather than a warning for every affected file, with the affected file list available in the CLI and WordPress report.

The first scan of a platform or package version requires outbound HTTPS access. Successful checksum manifests are cached locally. Unsupported packages and unavailable metadata fail open and are scanned normally. Use --disable-checksum to avoid checksum requests and scan every matching file.

Embedded definitions and security findings

Built-in code detection and the reviewed registry of 54 suspicious domains are embedded and available offline. The curated domain list excludes legitimate platforms, security resources, CDNs, placeholders, and IP addresses.

At scan startup, Maltrail malware-domain trails are downloaded to a private operating-system cache and compiled into a verified sorted eight-byte SHA-256 index. The cache is outside the scanned project and is not committed. Use --path-definitions=<private-path> to select its location or --disable-definitions-update to use only the last verified local cache.

The built-in exact-match layer contains 257 unique SHA-256 values generated from the malware fixtures already present in this repository. Regenerate and verify the list after an intentional corpus update with composer generate:malware-hashes.

Signatures also owns two generated fixed-width indexes: 58,461 known-malware MD5 prefixes and 6,352 normalized legacy-core SHA-256 values. Prefix matches are reported as unconfirmed warnings because a truncated hash is not a complete indicator. Legacy-core matches are used only by the optional WordPress module for unexpected files under restricted core directories. Extraction inputs and tooling remain private under the ignored .local directory; only the generated Signatures block is part of the source tree.

Component discovery lives under Modules/Inventory: Composer is supported for general PHP projects, while CMS inventories activate only when their platform is detected. Reports expose canonical malware, integrity, and reputation findings with stable IDs and complete scan coverage. WordPress core integrity excludes user-managed wp-content; genuine missing core files can be restored individually from the official release archive after checksum verification.

Use --report-format=json for the complete report or --report-format=sarif for code-scanning tools. Bounded recursive ZIP scanning is opt-in with --scan-archives and requires the PHP ZIP extension.

WordPress database scan

Use --scan-wordpress-db to add a read-only database phase when scanning a local WordPress installation:

The scan reports triggers attached to WordPress-prefixed tables, inventories administrator accounts, flags sites with multiple administrators for review, and reports orphaned posts as one aggregate finding with a bounded sample. It never drops triggers or deletes users or posts. Trigger SQL literals are redacted in reports and the original statement is represented by a SHA-256 hash.

This option requires ext-mysqli and literal string values for DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, and $table_prefix in wp-config.php; the configuration file is parsed but never executed. Administrator and orphan checks cover the primary tables selected by $table_prefix. Trigger visibility must be verifiable from the current database user's grants, otherwise coverage is marked incomplete. FTP sources are rejected, partial file scans record the database phase as skipped, and query/configuration failures are never reported as a clean result.

Programmatically

On programmatically silent mode and auto skip are automatically enabled.

Report Object

:art: Screenshots

WordPress dashboard

Report

HTML report format (default)

Interactive CLI