8.1.3.1. Process a file

Scanning a file using a specified workflow.

Scan is done asynchronously and each scan request is tracked by data id of which result can be retrieved by API 8.1.3.2. Fetch processing result.

Chunked transfer encoding (applying header Transfer-Encoding: Chunked) is not supported.

Multipart form upload is not supported, instead please consider using batch submission 8.1.4. Processing files in batch

Since MetaDefender Core 4.19.0, the request will be refused immediately with HTTP(S) error code 400 when MetaDefender Core does not have sufficient free disk space to handle. This is to avoid upload time being wasted.

Request

Value

Method

POST

URL

/file

Request HTTP header parameters:

name

type

required

value

apikey

string

false

Session id, can be acquired by 8.1.1.1. Login / Create a Session

filename

string

false

Specify name of file captured and displayed on corresponding MetaDefender Core scan result

filepath

string

false

Specify absolute file path resides on place where a local MetaDefender Core could read and scan it in place (without copying over to MetaDefender Core's temp folder)

MetaDefender Core will not extract file name from local path, instead expecting to use "filename" header as well.

When this header is specified, users must not have body content in HTTP(S) request, otherwise expecting to hit 400 HTTP(S) error:

{
"err": "Both body data and download link were given."
}

Details: 3.6.4.2. (New) Local scan enablement

user_agent

string

false

client identification string

rule

string

false

name of the selected rule (see 8.1.3.5. Fetching available processing rules)

workflow

string

false

name of the selected workflow (deprecated, use "rule" header parameter instead)

archivepwd

string

false

password for archive ( URL encoded UTF-8 string)

Multiple passwords is also supported, format: archivepwd<X>

  • X: Could be empty

  • When having value, X must be a number >= 1

For example:

archivepwd1: "fox"

archivepwd2: "cow"

archivepwd3: "bear"

metadata

string (JSON format)

false

could be utilized for:

  • Additional parameter for pre-defined post actions and external scanners (as a part of STDIN input).

  • Customized macro variable for watermarking text (Proactive DLP engine feature).

  • Additional context / verbose information for each file submission (appended into JSON response scan result).

For example: {"client_ip":"10.0.1.100","custom_para":"ABC"}

callbackurl

string ( <protocol://><ip | domain>:<port></path>)

false

Client's URL where MetaDefender Core will notify scan result back to whenever scan is finished (webhooks model). See details at 8.1.11.1. Individual file processing

Note: Support both non-secure (HTTP) and secured protocol (HTTPS). In case of secured protocol HTTPS, only TLS 1.2 or above is accepted by Core on the data transportation encryption between Core and remote server (client).

For example:

Details: 8.1.11. Webhooks

downloadfrom

string ( <protocol://><ip | domain>:<port></path>)

false

Details: 8.1.12. Scan via download link

When this header is specified, users must not have body content in HTTP(S) request, otherwise expecting to hit 400 HTTP(S) error:

{
"err": "Both body data and download link were given."
}

Specify download link where MetaDefender Core could download the entire payload for processing.

  • Supported protocol: HTTP / HTTPS

  • Support both individual file scan (both webhook & non-webhook) and file processing in batch via link

  • Configurable setting under workflow rule (under "SCAN" tab):

    • Download timeout

    • Max file size to download

  • Support to return status of download progress back to client in HTTP(S) response

  • Pre-check supported to refuse downloading if the file size does not meet configured conditions, and/or MetaDefender Core's temp folder does not have sufficient disk space to save the downloaded file

Limitation:

  • Redirect link is not supported

  • Retry to download is not supported

Request body should contain the the content to be scanned.

Successful response

HTTP status code: 200

{
"data_id": "61dffeaa728844adbf49eb090e4ece0e"
}

Error response

API key is invalid (only applicable when apikey header is sent)

HTTP status code: 400

{
"err": "Invalid apikey given"
}

Callback URL is invalid (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Callback url is invalid."
}

Body data and filepath header are provided at the same time (only applicable when filepath header is sent)

HTTP status code: 400

{
"err": "Both body data and local file path were given."
}

Internal error during processing batch (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Can not scan in given batch."
}

Batch is closed when file is not uploaded properly (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Batch closed during file upload."
}

Out of disk space for file upload request

HTTP status code: 400

{
"err": "File upload denied due to insufficient disk space."
}

Callbackurl header exists, but empty (only applicable when callbackurl header is sent)

HTTP status code: 403

{
"err": "No callback url given."
}

Cannot retrieve file and file size from an invalid download link (only applicable when downloadfrom header is sent)

HTTP status code: 400

{
"err": "Cannot get file name and file size from url."
}

Redirect link is not supported (only applicable when downloadfrom header is sent)

HTTP status code: 400

{
"err": "Redirect link not supported."
}

Invalid download link (only applicable when downloadfrom header is sent)

HTTP status code: 400

{
"err": "Invalid download url."
}

Invalid protocol in download link (only applicable when downloadfrom header is sent)

HTTP status code: 400

{
"err": "Download url must start with http:// or https://."
}

Content-Length header is missing from the request

HTTP status code: 411

{
"err": "Missing Content-Length header"
}

Body input is empty

HTTP status code: 422

{
"err": "File is empty"
}

Internal error

HTTP status code: 500

{
"err": "Failed to request scan. Try again later."
}

File size is larger than permitted maximum size

HTTP status code: 500

{
"err": "Failed to request scan. File size exceeded the maximum size permitted by your configuration."
}

Need to perform local file scan, however, the file defined in filepath header is inaccessible (only applicable when filepath header is sent)

HTTP status code: 500

{
"err": "File not found, invalid path or access."
}

License has been expired

HTTP status code: 500

{
"err": "License is expired"
}

There's no rule for scanning

HTTP status code: 500

{
"err": "No available rule is present for scanning."
}

Scan queue is full

HTTP status code: 503

{
"err": "Server is too busy. Try again later."
}

Unexpected event on server

HTTP status code: 500

{
"err": "<error message>"
}

Note: Check Metadefender Core server logs for more information.