Skip to main content
POST
Malware Scan returns one safety verdict for a URL, QR code, barcode, image, or file. POST /api/lookup/malware/scan Requires an Encrata API key in the Authorization header.

Request

All five scan types use the same endpoint. Set kind to select the input and scanner.
string
required
One of url, qr, bar, image, or file.
string
URL to inspect. Required when kind is url. A URL without http:// or https:// is scanned as http://.
file
The image or file to scan, uploaded as multipart/form-data (for example -F "file=@photo.jpg"). Use it for qr, bar, image, and file instead of content_base64. When you omit filename, the uploaded file’s name is used. Send the other fields, such as kind, as form fields.
string
Base64-encoded bytes for a JSON body. For qr, bar, and image, send this field or file. For file, send this field, file, or source_url. Send raw base64 only: a data:image/png;base64, prefix returns 400 with “content_base64 is not valid base64.”
string
Short-lived download URL for a file. Available only when kind is file. The file can be up to 10 MB.
string
Original file name. Send it with uploaded images and files so extension checks and file scanners have the expected context.
boolean
default:"false"
Include a STIX 2.1 bundle in result.stix.

Examples

Replace the file=@ path with your own image or file. To send JSON instead, base64-encode the bytes into content_base64 and set Content-Type: application/json.

Response

Every scan returns the {success, result, message} envelope. Start with result.verdict and result.recommended_action. Then read signals for the evidence, checks and coverage for what the verdict rests on, and the fields for the selected kind.
This response is shortened: the URL blocks redirect_hops, domain, tls, hosting, page, threat_intel, and data_flow are left out. See URL Scan for a full response.

Common fields

boolean
Whether the scan completed.
string
A sentence you can show users. It depends on the verdict:The subject follows the scan kind: URL, QR code, barcode, image, or file. Image and code scans can add a note about image quality or a payment code’s payee.
object
The scan verdict and kind-specific analysis.

Confidence

confidence says how much evidence supports the verdict. It isn’t derived from score, so a malicious result with a score of 80 returns medium. Because reputation sources update over time, the same target can return a different confidence on a later scan.

Checks and coverage

checks says what a verdict rests on. A clean result with a check that didn’t run is weaker than one where every check answered. Each item has these fields: coverage grades the checks as a whole: recommended_action turns the verdict and coverage into one decision:

Data flow

data_flow lists every party a scan contacted, so you can check where your data went. Vendor names aren’t returned.

IOCs

iocs lists the indicators the scan observed: URLs, domains, IP addresses, file hashes, and values decoded from codes. An indicator of compromise (IOC) is evidence you can search for or block in other systems, such as a SIEM, a firewall, or an email gateway. iocs describes what the scan saw, not what is dangerous. It’s filled for every verdict, including clean. Whether an entry is a threat depends on verdict. Each entry has four fields: This QR code scan decoded a link, followed it, and reports what it found:
Read it top to bottom: the hash of the image you uploaded, the domain the link lands on, the link as written in the code, the URL it resolves to, and the IP address that serves it.

IOC types

IOC sources

When a code or image contains a link, Encrata scans that link like a URL Scan and adds that scan’s IOCs, such as its domain, url, and ip, to the list.

What to expect

  • iocs is always present, never null. Scans of an upload (qr, bar, image, and file) always contain at least the upload’s hash.
  • Each type and value pair appears once. Values are compared without regard to case, and the first entry found is kept.
  • Don’t rely on the order of entries.

Use IOCs safely

role says whether an entry is evidence of a threat:
Don’t send every iocs entry to a blocklist, firewall, or SIEM. Send only entries whose role is threat. Otherwise, the hash of a clean file you scanned ends up on your blocklist.
A STIX bundle (stix: true) follows the same rule. It always contains the observables, and adds STIX indicator objects only when verdict is suspicious or malicious.

URL fields

A url result can contain the common fields plus submitted_url, final_url, final_domain, redirects, reachable, redirect_hops, domain, tls, hosting, page, and threat_intel. See URL Scan for every field and how the verdict is decided.
Page analysis is static. Encrata does not execute scripts from the scanned URL.
Private and internal addresses, such as 127.0.0.1 or 10.x.x.x, are never fetched. The verdict is unknown and signals contains an ssrf signal.

QR code and barcode fields

A qr or bar result can contain scan_id, kind, status, verdict, score, sha256, category, confidence, data_residency, codes, image, signals, iocs, and scanned_at. Each codes item can contain: The parsed payload can describe URLs, Wi-Fi configuration without the password, payment details, phone numbers, email messages, SMS messages, coordinates, contacts, one-time password metadata without the secret, device links, FIDO data, app-install links, scripts, or text. When no code can be read, the scan returns 422 with result.code set to validation_failed instead of a scan result. message says that no QR code (qr) or no barcode (bar) was detected, and that the code may be blurred, cropped, partly covered, or too small.

Image fields

File fields

A file result uses the common fields plus sha256, file_type, and the file’s SHA-256 in iocs, which is listed for every verdict. The signals array contains malware and rule matches.

Errors

Errors use {"success": false, "result": {"code": "..."}, "message": "..."}. Branch on result.code. message is a sentence you can show to users. Each scan page shows example error responses for its kind.

Credits

Each successful scan costs 1 credit. A qr or bar image costs 1 credit per code it finds. Repeating the same kind with the same content does not charge your account twice. result.credits shows what each scan charged. See Credits.