OPSWAT Filescan 1.0

Developer Guide

This is the API documentation for OPSWAT Filescan API. If you would like to evaluate or have any questions about this documentation, please contact us via our Contact Us form.

Authentication

apiKey apiKey

Fields

Key	In
X-Api-Key	Header

Scan

Upload file or URL resource for scan

/api/scan/{flow_id}/report

Scan URL

Scan URL resource

Auth

Request Body

Body_scan_file_api_scan_url_post	object
save_preset	boolean
url	string	Url of internet resource to be scanned
description	string	Uploaded file/url description
tags	string	Tags array to propagate
propagate_tags	boolean	If tags from description should be added to produced report(s) Default: true
password	string	Custom password, in case uploaded archive is protected
is_private	boolean	If file should not be available for download by other users
skip_whitelisted	boolean	If file is detected as whitelisted, report is not created

POST /api/scan/url

xxxxxxxxxx
 
curl --request POST \ --url 'https://opswat.developerhub.io/api/scan/url' \ --header 'X-Api-Key: {X-Api-Key}' \ --data 'save_preset={save_preset}' \ --data 'url={url}' \ --data 'description={description}' \ --data 'tags={tags}' \ --data 'propagate_tags=true' \ --data 'password={password}' \ --data 'is_private={is_private}' \ --data 'skip_whitelisted={skip_whitelisted}'
Copy

Responses

200

Successful Response

URL Upload Was Successful	object
flow_id	string
priority	object
applied	integer
max_possible	integer

422

Validation Error

Response

xxxxxxxxxx
 
{ "flow_id": "0123456789abcdefghijklmn", "priority": {  "applied": 20,  "max_possible": 100 }}
Copy

Scan File

Perform a scan of the uploaded file. After you submit a file for scanning you'll get the flow_id which is required to poll the result.

Auth

Request Body

Body_scan_file_api_scan_file_post	object
file	file
save_preset	boolean
description	string	Uploaded file/url description
tags	string	Tags array to propagate
propagate_tags	boolean	If tags from description should be added to produced report(s) Default: true
password	string	Custom password, in case uploaded archive is protected
is_private	boolean	If file should not be available for download by other users
skip_whitelisted	boolean	If file is detected as whitelisted, report is not created

POST /api/scan/file

xxxxxxxxxx
 
curl --request POST \ --url 'https://opswat.developerhub.io/api/scan/file' \ --header 'X-Api-Key: {X-Api-Key}' \ --form 'file=@{file}'
Copy

Responses

200

Successful Response

File Upload Was Successful	object
flow_id	string
priority	object
applied	integer
max_possible	integer
note	string

422

Validation Error

Response

xxxxxxxxxx
 
{ "flow_id": "0123456789abcdefghijklmn", "priority": {  "applied": 20,  "max_possible": 100,  "note": "In order to receive max possible scan priority, please ensure the last scan request is older than 60 seconds, and do not perform more than 60 scan requests per hour." }}
Copy

Get All Upload Related Reports

Obtain all reports for given scan init. By default, if no filter parameter is sent, we only return some basic report data, just to see report is there

Auth

Path Params

flow_id

string

flow_id from scan-file or scan-url

Query String

filter	array	Report fields that should be fetched. This parameter can have pretty complex setup. Its mostly covered in examples, but if you still have some questions, please contact support.
sorting	array	Sort parameters to be applied to fetched report data
other	array	Extra options to get special data

GET /api/scan/{flow_id}/report

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/scan/%7Bflow_id%7D/report' \ --header 'X-Api-Key: {X-Api-Key}' \ --data filter=general \ --data sorting=allSignalGroups(description:asc,averageSignalStrength:desc),allTags(tag.name:asc) \ --data other=emulationGraph
Copy

Responses

200

Successful Response

Get Scan Report - without filters	object
flowId	string
allFinished	boolean
allFilesDownloadFinished	boolean
reportsAmount	number
priority	string
pollPause	number
fileSize	number
fileReadProgressBytes	number
reports	object
additionalProperties	object
finalVerdict	object
verdict	string	The verdict of the scan. Enum: `unknown`,`benign`,`informational`,`suspicious`,`likely_malicious`,`malicious`
threatLevel	number	maximum: 1 minimum: -1
confidence	number	maximum: 1 minimum: 0
overallState	string	Describes general state of report: in_queue: file scan is not started yet, file is in scan queue in_progress: scan have started, no result verdict yet success: the scan is finished success_partial: means that some sub-task(s) had state `success_partial`, in case, ex., some it's lookups didn't complete in time failed: the scan is failed failed_partial: some sub-task(s) failed to execute Enum: `in_queue`,`in_progress`,`success`,`success_partial`,`failed`,`failed_partial`

Expand

400

Bad request

404

Item not found

422

Validation Error

Response

xxxxxxxxxx
 
{ "flowId": "63f6209b01b99ad33e80b936", "allFinished": true, "allFilesDownloadFinished": true, "reportsAmount": 1, "priority": "least", "pollPause": 12, "fileSize": 13370880, "fileReadProgressBytes": 13370880, "reports": {  "08bae608-ed5f-4ce6-8ae9-fad6b4609193": {   "overallState": "success_partial",   "positionInQueue": 0,   "finalVerdict": {    "verdict": "MALICIOUS",    "threatLevel": 1,    "confidence": 1   },   "vtRate": -1,   "file": {    "name": "bad_file.exe",    "hash": "834d1dbfab8330ea5f1844f6e905ed0ac19d1033ee9a9f1122ad2051c56783dc",    "type": "pe"   },   "filesDownloadFinished": true,   "created_date": "02/22/2023, 14:03:11",   "estimatedTime": "2",   "estimated_progress": 1  } }}
Copy

Reports

Retrieve a variety of report related data

GET

/api/reports/search

GET

/api/users/most-interesting

GET

/api/users/get-frequent-tags

GET

/api/reports/{report_id}/files

GET

/api/reports/{report_id}/{file_hash}

Search Report

Search for reports.

Finds reports and uploaded files by various tokens, like hash, filename, verdict, IOCs etc.

If query param is used, other params are ignored.

Auth

Query String

age	integer	Search reports with age of "age" days Default: -1
page	integer	Page number starting from 1 Default: 1
page_size		Page size Default: 10
method		Default: and
query	string
filename	string
source_type	string	Enum: `url`,`url-to-file`,`file`
filetype	string	Enum: `64bits`,`7zip`,`ace`,`apk`,`bat`,`bmp`,`csv`,`doc`,`docm`,`docx`,`dot`,`dotm`,`dotx`,`eml`,`elf`,`gif`,`hta`,`htm`,`html`,`img`,`iso`,`java`,`java-bytecode`,`javascript`,`jpg`,`lnk`,`mbox`,`mthml`,`msg`,`msi`,`mso`,`ole`,`pdf`,`pedll`,`peexe`,`png`,`ppt`,`pptm`,`pptx`,`pot`,`potm`,`potx`,`ps`,`pub`,`powershell`,`rar`,`rfc822`,`rtf`,`svg`,`txt`,`vbs`,`wmv`,`wsf`,`xls`,`xlsm`,`xlsb`,`xlsx`,`xlt`,`xltm`,`xltx`,`xsl`,`zip`,`exe`,`mail`,`ms-office`,`script`
media_type	string
verdict	string	Enum: `benign`,`informational`,`suspicious`,`likely_malicious`,`malicious`,`unknown`
tag	string
tags	string
date_from	string
date_to	string
rate_from	integer
rate_to	integer
domain	string
ip	string
url	string
uuid	string
email	string
registry_path	string
revision_save_id	string
sha1	string
sha256	string
sha512	string
md5	string
imphash	string
ssdeep	string
fuzzyfsiohash	string
authentihash	string
yara_rule	string
retry_count	integer
scan_init_id	string
report_id	string
signal_groups	string
mitre_techniques	string
verdict_groups	string
main_task_state		Default: success
exclude	string

Expand

GET /api/reports/search

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/reports/search' \ --header 'X-Api-Key: {X-Api-Key}' \ --data age=-1 \ --data page=1 \ --data page_size=10 \ --data method=and \ --data query={query} \ --data filename={filename} \ --data source_type={source_type} \ --data filetype={filetype} \ --data media_type={media_type} \ --data verdict={verdict} \ --data tag={tag} \ --data tags={tags} \ --data date_from={date_from} \ --data date_to={date_to} \ --data rate_from={rate_from} \ --data rate_to={rate_to} \ --data domain={domain} \ --data ip={ip} \ --data url={url} \ --data uuid={uuid} \ --data email={email} \ --data registry_path={registry_path} \ --data revision_save_id={revision_save_id} \ --data sha1={sha1} \ --data sha256={sha256} \ --data sha512={sha512} \ --data md5={md5} \ --data imphash={imphash} \ --data ssdeep={ssdeep} \ --data fuzzyfsiohash={fuzzyfsiohash} \ --data authentihash={authentihash} \ --data yara_rule={yara_rule} \ --data retry_count={retry_count} \ --data scan_init_id={scan_init_id} \ --data report_id={report_id} \ --data signal_groups={signal_groups} \ --data mitre_techniques={mitre_techniques} \ --data verdict_groups={verdict_groups} \ --data main_task_state=success \ --data exclude={exclude}
Copy

Responses

200

Successful Response

ReportSearchResponse	object	Search response returned to user
items	array
count	integer
count_search_params	integer
method	string
dbs_sync	boolean

400

Bad request

422

Validation Error

Response

xxxxxxxxxx
 
{ "items": [  "{array...}" ], "count": "{integer}", "count_search_params": "{integer}", "method": "{string}", "dbs_sync": "{boolean}"}
Copy

Get Most Interesting

Get most interesting report recently

Auth

GET /api/users/most-interesting

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/users/most-interesting' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Frequent Tags

Get most frequently seen tags recently

Auth

GET /api/users/get-frequent-tags

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/users/get-frequent-tags' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get All Files

Obtain all files for given report

Auth

Path Params

report_id string

Query String

type		Default: all
with_content	boolean	Compressed base64 data

GET /api/reports/{report_id}/files

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/reports/%7Breport_id%7D/files' \ --header 'X-Api-Key: {X-Api-Key}' \ --data type=all \ --data with_content={with_content}
Copy

Responses

200

Successful Response

Successful Response object

404

Item not found

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Specific Report

Obtain a report for given report_id.

Auth

Path Params

report_id	string	Report Id
file_hash	string	File hash

Query String

filter	array	Report fields that should be fetched
sorting	array	Sort parameters to be applied to fetched report data
other	array	Extra options to get special data

GET /api/reports/{report_id}/{file_hash}

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/reports/%7Breport_id%7D/%7Bfile_hash%7D' \ --header 'X-Api-Key: {X-Api-Key}' \ --data filter=%5Bobject%20Object%5D \ --data sorting=allSignalGroups(description:asc,averageSignalStrength:desc),allTags(tag.name:asc) \ --data other=emulationGraph
Copy

Responses

200

Successful Response

Successful Response object

400

Bad request

404

Item not found

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Files

Get a file by its hash or id in various format

GET

/api/files/{hash}

Get Single File

Obtain single file for given report by file id or hash

Auth

Path Params

hash

string

File hash

Query String

report_id	string	Report Id
type		Default: base64
original_name	boolean
password	string	Password to be used on compression

GET /api/files/{hash}

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/files/%7Bhash%7D' \ --header 'X-Api-Key: {X-Api-Key}' \ --data report_id={report_id} \ --data type=base64 \ --data original_name={original_name} \ --data password={password}
Copy

Responses

200

Successful Response

Successful Response object

404

Item not found

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Feed

Atom feed

Get Feed Info

Get reports feed info

Auth

GET /api/feed/info

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/feed/info' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Feed

Get reports feed.

For API documentation page we show smaller amount of reports. To get full feed, query feed endpoint directly from browser address bar or from any suitable app.

Auth

GET /api/feed/atom

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/feed/atom' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Users

Report-related and other functionality used by ordinary users.

GET

/api/users/uploads

GET

/api/users/{account_id}/avatar

Get Uploads

Get list of uploaded files

Auth

Query String

page

integer

Page number starting from 1

Default: 1

page_size

Page size

Default: 10

GET /api/users/uploads

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/users/uploads' \ --header 'X-Api-Key: {X-Api-Key}' \ --data page=1 \ --data page_size=10
Copy

Responses

200

Successful Response

Successful Response object

400

Bad request

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Avatar Image

Get use avatar image

Auth

Path Params

account_id string

GET /api/users/{account_id}/avatar

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/users/%7Baccount_id%7D/avatar' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

System

Various helper and system functionality.

GET

/api/system/translations/{lang}

/api/system/get-terms/{terms_type}

POST

/api/system/errors/log

Get Translations

Obtain translations for specific language

Auth

Path Params

lang

string

Enum: en,de,zh-CN,es,hi,ar,pt,bn,ru,ja,ko,fr,te,mr,tr,ta,vi,ur

GET /api/system/translations/{lang}

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/translations/%7Blang%7D' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Mitre Data

Obtain MITRE tactics and techniques

Auth

GET /api/system/mitre

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/mitre' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Default

Return general information about webservice, just to indicate that API is working

Auth

GET /api/system/info

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/info' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Terms

Obtain privacy policy and terms & conditions

Auth

Path Params

terms_type

string

Enum: privacy-policy,terms-condition,cookie-policy

GET /api/system/get-terms/{terms_type}

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/get-terms/%7Bterms_type%7D' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Log Client Error

Perform needed actions with error data, obtained from front-end

Auth

POST /api/system/errors/log

xxxxxxxxxx
 
curl --request POST \ --url 'https://opswat.developerhub.io/api/system/errors/log' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Config

Obtain project configuration to use on front-end

Auth

GET /api/system/config

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/config' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Logo

Obtain MITRE tactics and techniques

Auth

Query String

type	string
theme	string
name	string

GET /api/system/logo

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/system/logo' \ --header 'X-Api-Key: {X-Api-Key}' \ --data type={type} \ --data theme={theme} \ --data name={name}
Copy

Responses

200

Successful Response

Successful Response object

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Backend

Backend wrapper

GET

/api/backend/reputation

Get Reputation

Wrapper for reputation api

Auth

Query String

sha256	string	SHA256 digest as found in the response of submit or extracted resource in the report.
hashes	array	Array of one or more hashes

GET /api/backend/reputation

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/backend/reputation' \ --header 'X-Api-Key: {X-Api-Key}' \ --data sha256={sha256} \ --data hashes={hashes}
Copy

Responses

200

Successful Response

Successful Response object

422

Validation Error

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Docs

API documentation related

Get API Docs

Return API docs UI

Auth

GET /api/docs

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/docs' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get Sitemap

Get sitemap xml

Auth

GET /api/docs/sitemap

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/docs/sitemap' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get API Doc Styles

Return styles for api docs

Auth

GET /api/docs/styles

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/api/docs/styles' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy

Get OpenAPI Endpoint

Return API json data to be used by docs UI

Auth

GET /openapi.json

xxxxxxxxxx
 
curl --get \ --url 'https://opswat.developerhub.io/openapi.json' \ --header 'X-Api-Key: {X-Api-Key}'
Copy

Responses

200

Successful Response

Successful Response object

Response

xxxxxxxxxx
 
{ "key": "value"}
Copy