Harden quarantine provisioning; enforce strict permissions and update Ansible and docs

README.md

@@ -34,6 +34,20 @@ Integration notes
 - Preferred deployment: set `php_admin_value[auto_prepend_file]` in the site-specific PHP-FPM pool to the absolute path of `upload-logger.php` so it runs before application code.
 - If using sessions for user identification, the script safely reads `$_SESSION['user_id']` only when a session is active; do not rely on it being present unless your app starts sessions earlier.
 - The script uses `is_uploaded_file()`/`finfo` where available; ensure the PHP `fileinfo` extension is enabled for best MIME detection.
+- The script uses `is_uploaded_file()`/`finfo` where available; ensure the PHP `fileinfo` extension is enabled for best MIME detection.
+
+Content detector & tuning
+
+- `ContentDetector` is now included and performs a fast head-scan of uploaded files to detect PHP open-tags and common webshell indicators (e.g., `passthru()`, `system()`, `exec()`, `shell_exec()`, `proc_open()`, `popen()`, `base64_decode()`, `eval()`, `assert()`).
+- The detector only scans the first N bytes of a file to limit CPU/io work; tune these limits in `upload-logger.json`:
+	- `limits.sniff_max_bytes` — number of bytes to scan from file head (default `8192`).
+	- `limits.sniff_max_filesize` — only scan files up to this size in bytes (default `2097152` / 2MB).
+- Behavior note: `eval()` and similar tokens commonly appear inside SVG/JS contexts. The detector uses the detected MIME to be more permissive for XML/SVG-like content, but you should test and tune for your application's upload patterns to avoid false positives (see `INTEGRATION.md`).
+- If your application legitimately accepts encoded or templated payloads, add application-specific allowlist rules (URI or content-type) in `allowlist.json` or extend `upload-logger.json` with detector-specific tuning before enabling blocking mode.
+Further integration
+- Read the `INTEGRATION.md` for a commented example `upload-logger.json`, logrotate hints, and deployment caveats.
+- Provision the required directories (`quarantine`, `state`) and set ownership/SELinux via the included provisioning script: `scripts/provision_dirs.sh`.
+- Example automation: `scripts/ansible/upload-logger-provision.yml` and `scripts/systemd/upload-logger-provision.service` are included as examples to run provisioning at deploy-time or boot.
 
 Operational recommendations
 - Place the `logs/` directory outside the webroot or deny web access to it.
@@ -56,3 +70,7 @@ Support & changes
 
 ---
 Generated for upload-logger.php (v3).
+
+## Additional documentation
+
+- Auto-merge & Dependabot: [docs/auto-merge.md](docs/auto-merge.md)