Version 2.4.8 · latest

Upload scan settings upload-scan-settings

Platform-wide upload scanning (files in multipart form uploads only): master switch, dangerous extensions, double extensions, disguised files, webshell signatures, antivirus, per-file limit, scan timeout, action and exceptions; admin only. Webshell signatures, antivirus and the sha256 blocklist belong to the paid feature WAF enhanced.

Pick an endpoint to see its example call on the right.

ProtectionAuthentication: Admin only2 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

PUT/api/v2/upload-scan-settingsUpdate upload scan settings

Authentication: Admin only

Request body application/json

FieldTypeDescription
actionstring On a hit - block, log only, or observe for 3 days (log only, then block); dangerous files have no observation period.
Values ["block","log","observe"]
disguiseboolean Disguised file detection (image extension but the magic bytes are a script or an executable).
double_extboolean Double extension detection (e.g. a.php.jpg, a.asp;.jpg).
enabledboolean Master switch; false = no site is scanned.
enhancedstring WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; enhanced items are off, settings kept); ignored on update.
Values ["full","readonly","basic"]
exceptionsUploadScanException[] Exceptions - skip the signature when the site and path prefix match (empty sig = the path is not scanned). Entries that tenants added by marking false positives (source=false_positive) must be sent back unchanged on replace, otherwise they are overwritten.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
extsstring[] Dangerous extensions (lowercase, without the dot); defaults to php phtml jsp jspx asp aspx ashx cer war sh cgi shtml when omitted. Families expand (php also covers php3-8 pht phtml phar, asp covers asa cdx cer, jsp covers jspx jspf, shtml covers shtm stm); dot-leading names (.php) are judged as extensions; while the list is non-empty, .htaccess, .user.ini and web.config are blocked too. A site may override with waf.upload_exts.
max_file_mbinteger Per-file scan limit in MB (default 20); larger files only get the extension check and are handled per oversize.
observe_untilstring End of the observation period (set when action is observe); ignored on update, written by the server.
on_parse_errorstring On multipart parse errors (bad delimiter, oversized header, truncated body, too many parts) - block or allow (pass and log); default block.
Values ["allow","block"]
on_timeoutstring On scan timeout (or failure to read the body) - allow (pass and log) or block (default allow).
Values ["allow","block"]
on_virus_errorstring On virus scan errors (clamd unreachable, read/write timeout, bad reply) - allow (pass and log) or block (default allow); clamd not installed or not running means no scan, not an error.
Values ["allow","block"]
oversizestring Files over the limit - allow (pass and log) or block.
Values ["allow","block"]
sha256object[] Local sha256 blocklist (WAF enhanced).
sigboolean Webshell signatures (WAF enhanced).
timeout_sinteger Scan timeout per request in seconds (default 2).
updated_atstring Version in the response (updated_at of the node.global config key; null if never changed); ignored on update.
virusstring Antivirus (ClamAV, WAF enhanced) - off, mem4g (nodes with at least 4 GB memory) or all nodes.
Values ["off","mem4g","all"]

Upload scan settings object

FieldTypeDescription
actionstring On a hit - block, log only, or observe for 3 days (log only, then block); dangerous files have no observation period.
Values ["block","log","observe"]
disguiseboolean Disguised file detection (image extension but the magic bytes are a script or an executable).
double_extboolean Double extension detection (e.g. a.php.jpg, a.asp;.jpg).
enabledboolean Master switch; false = no site is scanned.
enhancedstring WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; enhanced items are off, settings kept); ignored on update.
read-onlyValues ["full","readonly","basic"]
exceptionsUploadScanException[] Exceptions - skip the signature when the site and path prefix match (empty sig = the path is not scanned). Entries that tenants added by marking false positives (source=false_positive) must be sent back unchanged on replace, otherwise they are overwritten.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
extsstring[] Dangerous extensions (lowercase, without the dot); defaults to php phtml jsp jspx asp aspx ashx cer war sh cgi shtml when omitted. Families expand (php also covers php3-8 pht phtml phar, asp covers asa cdx cer, jsp covers jspx jspf, shtml covers shtm stm); dot-leading names (.php) are judged as extensions; while the list is non-empty, .htaccess, .user.ini and web.config are blocked too. A site may override with waf.upload_exts.
max_file_mbinteger Per-file scan limit in MB (default 20); larger files only get the extension check and are handled per oversize.
observe_untilstring End of the observation period (set when action is observe); ignored on update, written by the server.
read-only
on_parse_errorstring On multipart parse errors (bad delimiter, oversized header, truncated body, too many parts) - block or allow (pass and log); default block.
Values ["allow","block"]
on_timeoutstring On scan timeout (or failure to read the body) - allow (pass and log) or block (default allow).
Values ["allow","block"]
on_virus_errorstring On virus scan errors (clamd unreachable, read/write timeout, bad reply) - allow (pass and log) or block (default allow); clamd not installed or not running means no scan, not an error.
Values ["allow","block"]
oversizestring Files over the limit - allow (pass and log) or block.
Values ["allow","block"]
sha256object[] Local sha256 blocklist (WAF enhanced).
sigboolean Webshell signatures (WAF enhanced).
timeout_sinteger Scan timeout per request in seconds (default 2).
updated_atstring Version in the response (updated_at of the node.global config key; null if never changed); ignored on update.
read-only
virusstring Antivirus (ClamAV, WAF enhanced) - off, mem4g (nodes with at least 4 GB memory) or all nodes.
Values ["off","mem4g","all"]

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command