# LocalGuard Scanner

LocalGuard Scanner is a privacy-first malware scanner for WordPress. It inventories files and supported WordPress database tables, compares the WordPress core against bundled SHA-256 manifests, and combines signed signatures with contextual heuristics. Scan data stays on the WordPress server.

Version 1.2 is intentionally report-only. It never deletes, edits, repairs, or quarantines site content. Detection and response are separated internally so a reviewed quarantine workflow can be added later without turning scan rules into destructive actions.

## Highlights

- Manual scans and daily WP-Cron scans, split into short resumable batches.
- Offline signed rules; no telemetry and no HTTP requests during a scan.
- Exact bundled integrity catalogs for supported WordPress releases.
- Exact core trust plus bounded PHP data-flow analysis to reduce proximity-based false positives.
- Token-verified informational handling for inert PHP files in uploads, regardless of filename.
- A signed offline plugin advisory snapshot, initially covering User Meta through 3.1.2.
- File, administrator, option, cron, post-content, and Multisite checks.
- Explainable scores, deduplicated findings, resolution tracking, and redacted email summaries.
- Individual reconciliation of deleted-file findings, even when an unrelated file cannot be inspected completely.
- Source tabs that separate files, database records, and plugin advisories with coherent counts and pagination.
- Guided findings with human-readable database locations, read-only SQL review queries, and separate investigation, conditional correction, and verification steps.
- Explicit partial-coverage reports for unreadable, excluded, oversized, or unsupported areas.
- English source interface and a bundled Spanish translation.
- PHP 7.4+ recovery compatibility; PHP 8.3+ recommended.

## Install

1. Download `localguard-scanner-1.2.6.zip` from `dist/`.
2. In WordPress, open Plugins → Add New → Upload Plugin.
3. Upload the ZIP, activate it, and open LocalGuard.
4. Review LocalGuard → Scan → Local diagnostics before the first run.

For Multisite, network activation is recommended. Only a super administrator can access network-wide results.

## Shared VPS guidance

The default batch size is 50. On a constrained shared VPS, begin with 25–50 and increase it only after checking the locally stored timing and memory diagnostics. Each slice checks its time and memory budget between small chunks. Database values larger than 256 KiB are sampled from both ends and make coverage partial.

WP-Cron needs normal site traffic. If `DISABLE_WP_CRON` is enabled, configure the hosting provider’s system cron to request `wp-cron.php` at a suitable interval. LocalGuard reports this condition but does not contact itself or any outside service.

## Interpreting results

A high score is a reason to investigate, not proof by itself. Check the stated location and evidence, make a backup, compare against a trusted copy, and inspect access logs. “Partial coverage” must never be interpreted as a clean bill of health.

Database finding identifiers are not server paths. LocalGuard translates supported content, option, and user identifiers into their WordPress table, record, and site, and can provide a `SELECT` query for local review. It never executes that query or generates destructive SQL.

If compromise is confirmed, restore from a known-good backup or clean the site through an established incident-response process. Rotate WordPress administrator passwords, database and hosting credentials, API keys, and WordPress salts from a known-clean device.

## Development

```bash
php .tools/composer.phar install
php .tools/composer.phar test
php .tools/composer.phar lint
php .tools/composer.phar analyse
npm run test:js
npm run build:zip
php tools/verify-package.php dist/localguard-scanner-1.2.6.zip
```

The production ZIP includes Composer’s optimized autoloader and `paragonie/sodium_compat`; Composer and Node are not required on the WordPress server.

## Security and limitations

Read [SECURITY.md](SECURITY.md) before reporting a plugin vulnerability. Scanner rules and the local advisory snapshot are bundled and can become outdated until a new plugin release is installed. The advisory snapshot does not replace a continuously updated vulnerability service. Obfuscated or novel malware can evade heuristic scanning, and legitimate software can trigger a false positive.

Licensed under GPL-2.0-or-later.
