UploadShied/docs/release-checklist.md

Release & Deploy Checklist

This checklist helps you deploy upload-logger.php to production safely.

Pre-release

• Review and pin configuration in upload-logger.json (see examples/upload-logger.json).
• Ensure unit tests pass and CI workflows are green for the release branch.
• Run static analysis (vendor/bin/phpstan analyse) and fix any new issues.
• Run composer audit to confirm no advisories remain.
• Confirm branch protection and required checks are enabled for main/master.

Infrastructure & permissions

• Create directories with correct ownership and permissions:

  • logs/ — writeable by PHP-FPM user; ensure outside the webroot or blocked by web server.
  • quarantine/ — writeable by PHP-FPM user; should be secured and not executable.
  • state/ — writeable by PHP-FPM user; used for flood counters and transient state.

• Recommended permissions (adjust to your environment):

  • Owner: root (or deploy user)
  • Group: web server group (e.g., www-data)
  • logs/ directory: chmod 750 (owner rwx, group r-x)
  • Log files: chmod 640 (owner rw, group r-)
  • quarantine/ and state/: chmod 750

• SELinux/AppArmor: apply proper contexts/profiles so PHP-FPM can write to logs/, quarantine/, and state/.

Configuration

• Create upload-logger.json from examples/upload-logger.json and adjust values:
  • paths.quarantine_dir — absolute path to quarantine/.
  • paths.state_dir — absolute path to state/.
  • paths.allowlist_file — path to allowlist.json.
  • limits.* — tune max_size, sniff_max_bytes, etc., for your environment.
  • ops.block_suspicious — set to false initially to observe alerts, then true once tuned.

Deployment

• Ensure php_admin_value[auto_prepend_file] is configured in the site pool for PHP-FPM to include upload-logger.php.
• Reload or restart PHP-FPM gracefully after changing pool settings.
• Verify the web server denies direct access to logs/ and quarantine/.

Validation

• Run integration tests / smoke tests (upload small benign files, large files, multipart without files, raw-body requests).
• Confirm logs are written with expected fields and no sensitive information is recorded.
• Inspect quarantine behavior by uploading archive files and verifying entries are quarantined and inspected.
• Monitor CPU and IO while running detectors on sample traffic to ensure acceptable overhead.

Post-release

• Configure log rotation (see examples/logrotate.d/upload-logger).
• Set up monitoring/alerting on log file growth, error events, and flood alerts.
• Schedule periodic dependency checks (Dependabot and weekly composer audit).
• Periodically review allowlist.json and detector tuning to reduce false positives.