UploadShied/CONFIG_REFERENCE.md

Configuration Reference

This file maps the top-level configuration keys used by uploadshield.json (UploadShield) to their effect and defaults. Use absolute paths in production where possible.

Top-level sections

• modules (object): enable or disable features by name. Keys used in code:

  • flood (bool) — per-IP upload counting and flood alerts. Default: true.
  • filename (bool) — run FilenameDetector. Default: true.
  • mime_sniff (bool) — run MimeDetector & content sniffing. Default: true.
  • hashing (bool) — compute hashes for forensic records. Default: true.
  • base64_detection (bool) — detect JSON/base64 embedded payloads in raw bodies. Default: true.
  • raw_peek (bool) — allow guarded reads of php://input. Disabled by default (false) because it may consume request bodies.
  • archive_inspect (bool) — inspect archives moved to quarantine. Default: true.
  • quarantine (bool) — enable quarantine moves. Default: true.

• paths (object): filesystem locations used by the script. Common keys:

  • log_file (string) — path to JSON log file. Default: logs/uploads.log (relative to script). Recommended: absolute path under a per-site .security folder.
  • quarantine_dir (string) — path to quarantine directory. Default: quarantine.
  • state_dir (string) — path to store flood counters/state. Default: state.
  • allowlist_file (string) — optional allowlist of URIs/content-types. Default: allowlist.json.

• limits (object): thresholds controlling scanning and resource limits.

  • max_size (int) — bytes threshold for big_upload warning. Default: 52428800 (50 MB).
  • raw_body_min (int) — min bytes for raw body events. Default: 512000 (500 KB).
  • sniff_max_bytes (int) — bytes to read from a file head for content sniffing. Default: 8192 (8 KB).
  • sniff_max_filesize (int) — only sniff files up to this size. Default: 2097152 (2 MB).
  • hash_max_filesize (int) — max file size to compute hashes for. Default: 10485760 (10 MB).
  • archive_max_inspect_size (int) — skip inspecting archives larger than this. Default: 52428800 (50 MB).
  • archive_max_entries (int) — max entries to inspect inside an archive. Default: 200.

• ops (object): operator-facing options.

  • quarantine_owner / quarantine_group (string) — desired owner:group for quarantine. Default: root:www-data.
  • quarantine_dir_perms (string) — octal string for dir perms (recommended 0700). Default: 0700.
  • block_suspicious (bool) — when true the script returns 403 for suspicious uploads. Default: false (observe mode).
  • log_rotate (object) — hints for log rotation (size, keep, enabled) used in examples.
  • trusted_proxy_ips (array) — proxies allowed to signal buffered bodies or peek permission.

• allowlists (object): reduce false positives for known safe flows.

  • base64_uris (array of strings) — substrings or PCRE (when wrapped with #) matching URIs to ignore for base64/raw detections.
  • ctypes (array of strings) — content-types treated as trusted for encoded payloads (e.g., image/svg+xml).

Detector-specific keys

• detectors.content (object)
  • sniff_max_bytes (int) — override limits.sniff_max_bytes for content detector.
  • sniff_max_filesize (int) — override limits.sniff_max_filesize.
  • allow_xml_eval (bool) — relax eval() detection for XML/SVG content when true.
  • custom_patterns (array) — array of PCRE patterns (as strings) applied to the file head. Invalid patterns are ignored.

Example uploadshield.json

{
  "modules": { "flood": true, "filename": true, "mime_sniff": true, "hashing": true, "base64_detection": true, "raw_peek": false, "archive_inspect": true, "quarantine": true },
  "paths": { "log_file": "/var/www/site/.security/logs/uploads.log", "quarantine_dir": "/var/www/site/quarantine", "state_dir": "/var/www/site/state", "allowlist_file": "/var/www/site/.security/allowlist.json" },
  "limits": { "max_size": 52428800, "raw_body_min": 512000, "sniff_max_bytes": 8192, "sniff_max_filesize": 2097152 },
  "ops": { "quarantine_owner": "root", "quarantine_group": "www-data", "quarantine_dir_perms": "0700", "block_suspicious": false },
  "allowlists": { "base64_uris": ["/api/uploads/avatars"], "ctypes": ["image/svg+xml"] }
}

Operational tips

• Keep block_suspicious disabled while tuning; use allowlists.base64_uris and ctypes to reduce false positives.
• Avoid enabling raw_peek unless your front end buffers request bodies or you accept the risk of consuming php://input.
• Use absolute paths in paths.* when deploying under systemd/Ansible to avoid cwd surprises.
• Ensure quarantine_dir is inaccessible from the web and set to owner root and mode 0700; files inside should be 0600.

If you want, I can generate a per-site uploadshield.json filled with your preferred absolute paths and ownership values.

--