Advanced search (TCA-0320)
The Advanced Search enables users to filter samples by search criteria submitted in a POST request. A wide range of search keywords is available, and they can be combined using search operators to build advanced queries.
This API is rate limited to 1 request per second.
General Information
- Default response format is xml
- POST requests must contain Content-Type: application/json in the HTTP header field
- The maximum amount of API results that can be returned for a search query is 100,000. Although there may be more samples matching the query in the Spectra Intelligence system, the API will only allow browsing through 100,000 of them.
- Limitation for one request (records_per_page) is 10,000 samples.
- If there are more results than the requested amount of results per page, you can retrieve them by fetching the next page of results using the next_page value from the response as the page value in the next request with the same query. The maximum amount of pages that can be fetched is the overall limit of results (100000) divided by the requested amount of results per page. For example, if the requested number of results per page is 1000, the maximum number of pages is 100. When there are no more results, the more_pages value in the response will be false. If the requested page doesn't exist, or the overall amount of results is over 100,000, the response "Max limit reached" with status code 400 is returned.
- To ensure quicker response times for long and complex queries, the response may contain fewer results than are available in the database i.e. the service will only return newest matches found within a reasonable timeframe.
- Longer and complex queries can result in a "Search query too long, please shorten and/or simplify your query." message being displayed. Although the maximum search query length is 7000 characters, even shorter queries can get expanded during input sanitization and exceed that character limit.
Search Results Algorithm
If the number of search query results is smaller than 1000, the Search Results Algorithm returns the exact total number of results.
For search queries where the number of results is greater than 10,000, the Search Results Algorithm returns an estimated total number of results, rounded down to a lower value.
Depending on the number of results, the algorithm will return the results in the following way.
If the number of search results is:
- between 1000 and 10k - the total results number is rounded to hundreds
- between 10k and 100k - the total results number is rounded to thousands
- between 100k and 1M - the total results number is rounded to ten-thousands
- between 1M and 10M - the total results number is rounded to hundred-thousands
- etc.
Non-keyword search
Advanced search queries can be quickly built without using keywords. Non-keyword search is available only for a particular subset of indicators of compromise:
- SHA1, SHA256 and MD5 hashes
- URLs
- IP addresses
- domains
- emails
- exploits (
CVE-XXXX-YYYYY
)
Non-keyword Search Queries
Non-keyword searches can be performed as standalone queries containing one or more non-keyword values, or be combined with traditional keyword searches. Email and IP (IPv4, IPv6) non-keyword queries support wildcard matching.
Single non-keyword search
This can be any one of the IOCs listed above.
Multiple non-keyword search
When combining multiple non-keyword search values delimited by spaces, the whole query will be enclosed in brackets and the spaces will be interpreted as the operator OR. Users can explicitly provide different operators (AND/NOT) to build more complex queries.
Non-keyword with keyword
When combining non-keyword search values with keywords, consecutive non-keyword values will be enclosed in brackets and the spaces between them will be interpreted as the operator OR. Spaces between non-keyword search values and keywords will be interpreted using the operator AND, meaning that the order of keywords and non-keyword values in the query is important.
Combining queries with the NOT operator
The NOT operator excludes search results that match the defined criteria.
Additional Notes
If a list of non-keyword search values contains invalid entries, the API will respond with the status code 400 Bad Request
and return the first invalid non-keyword. In cases where the query contains only hashes, invalid entries will be returned in the invalid_hashes
response field.
Using commas between non-keyword search values will result in an invalid query. Searching for strings containing commas and other special characters is supported by using quotation marks.
For example, IPV6 addresses or URLs containing colons, commas, or brackets must be enclosed in quotation marks:
"2001:0db8:85a3:0000:0000:8a2e:0370:7334"
"http://www.evildomain.com/gate.php?13,35869"
Non-keyword Search Examples
Query Type | Example | Syntax | Outcome |
---|---|---|---|
Single non-keyword | 0000038704cb5f0e1bd87d6a75e904529af0d6ac | NK | NK |
Non-keyword search values combined with keywords | https://hope-bd.com/googledocs.php class:KNOWN | NK K | NK AND K |
Multiple non-keyword values (hashes only) | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb | NK NK | (NK OR NK) |
Multiple non-keyword values | 127.0.0.1 "2620:119:35::35" google.com | NK NK NK | (NK OR NK OR NK) |
Multiple non-keyword values with an AND operator | mock@mockmail.com 127.0.*.1 AND google.com https://hope-bd.com/googledocs.php | NK NK AND NK NK | (NK OR NK) AND (NK OR NK) |
Multiple keywords combined with multiple non-keyword values | class:MALICIOUS mock@mockmail.com google.com firstseen:2018-04-05T21:11:47Z | K NK NK K | K AND (NK OR NK) AND K |
Combining queries with the NOT operator | NOT *@mockmail.com https://hope-bd.com/googledocs.php AND NOT 0000038704cb5f0e1bd87d6a75e904529af0d6ac class:MALICIOUS | NOT NK NK AND NOT NK AND K | (NOT NK OR NK) AND NOT NK AND K |
Bulk search
Bulk search can be used to search for a large number of samples in a single request. It supports the following keywords:
- sha1
- sha256
- md5
- hashes
The keyword hashes can be used to perform mixed hash searches without grouping or explicitly naming large numbers of hashes. All keywords can be used in any combination with each other.
Examples with IN criteria:
hashes:[b2cc741853154e2f08057e117cc74f2338d6ffe1, 554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294, …, e7a7392e53c55c1c66c1fa9839264c00]
Example with OR:
sha1:b2cc741853154e2f08057e117cc74f2338d6ffe1 OR sha256:554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294 … OR md5:e7a7392e53c55c1c66c1fa9839264c00
Example with IN and OR:
hashes:[b2cc741853154e2f08057e117cc74f2338d6ffe1, 554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294, …, e7a7392e53c55c1c66c1fa9839264c00] OR sha1:beeb467c917af6fd0064a265c31803e0977b6ae
Bulk search queries support only the operator OR, while AND or NOT are not supported. The maximum number of unique hashes per request is 10 000. Response can take up to one minute.
The response will always contain a field with a list of all samples that matched the queried hashes. If the query contained some invalid hashes, they will be returned in the "invalid hashes" field of the response. Valid hashes without matches will be returned in the "unknown_hashes" field of the response.
Daily sample processing can cause some differences between sample metadata returned by bulk search and regular search.
Supported Search Keywords
User-friendly modifiers
Some keywords support modifiers that serve as shorthand notation for search expressions. These modifiers are available both in string queries and in JSON queries.
Numbers
Keywords that accept numbers as values also accept a trailing plus or minus sign.
For example:
5+
(five or more)42-
(fourty-two or less)
Exceptions:
- Spaces are not allowed.
- Prefixes are also not allowed (only trailing plus or minus).
- Modifiers can't be used in range queries. For example,
[3+ to 5-]
is invalid.
List of keywords that accept numbers
av-count
av-threatlevel
document-pages
elf-section-count
filecount
macho-section-count
macho-segment-count
pe-section-count
riskscore
size
submissions
threatlevel
Dates
Keywords that accept dates also accept period abbreviations and trailing plus/minus.
Accepted abbreviations:
h
for hoursd
for daysw
for weeksm
for monthsy
for years
The trailing plus or minus sign behaves just like for numbers.
For example:
2023-04-11T08:10:00+
(on April 11 2023 at 08:10, or after that time)3d+
(three days or more)1w-
(one week or less)
Exceptions:
- Spaces are not allowed.
- Prefixes are also not allowed (only trailing plus or minus).
- Modifiers can't be used in range queries. For example,
[3d to 5w]
is invalid.
List of keywords that accept dates
firstseen
lastanalysis
lastseen
pe-timestamp
signer-valid-from
signer-valid-to
submission-time
taggant-valid-from
taggant-valid-to
Sizes
Keywords that accept sizes also accept unit abbreviations (KB, MB, GB...) and trailing plus/minus.
The abbreviations are case-insensitive. If an abbreviation is not specified, the expression is evaluated in bytes. Byte multiples are supported in both decimal (kilo-, mega-, giga-...) and binary (kibi-, mebi-, gibi-...) form.
For example:
5MB+
(five megabytes or larger)13kib-
(thirteen kibibytes or smaller)
Exceptions:
- Spaces are not allowed.
- Prefixes are also not allowed (only trailing plus or minus).
- Modifiers can't be used in range queries if they contain a trailing plus or minus sign. For example,
[3kB+ to 5MB]
is invalid. However, if you use them without a trailing plus/minus, they can be used in a range query. For example,[3kb TO 5mb]
is allowed.
The only keyword that accepts a size is size
.
Group keywords
When using group keywords, the provided search query will be used with all single keywords in the group's respective list. Refer to the single keyword descriptions for more information.
Keyword aliases are enclosed in parentheses.
certificate | Group keyword |
---|---|
Includes | cert-issuer-name cert-issuer-org cert-issuer-unit cert-subject-name cert-subject-org cert-subject-unit |
Examples | Case-insensitive wildcard matching is supported. Wildcard: certificate:*micr* |
certificate-country | Group keyword |
---|---|
Includes | cert-issuer-country cert-subject-country |
Examples | Case-insensitive wildcard matching is supported. List (any of the values): certificate-country:[HR, US] |
document | Group keyword |
---|---|
Includes | document-author document-subject document-title document-description |
Examples | Case-insensitive wildcard matching is supported. List (any of the values): document:[adobe, microsoft, *confidencial] Wildcard: document:*soft |
mutex | Group keyword |
---|---|
Includes | mutex-config mutex-dynamic |
Examples | The keyword is case-sensitive and doesn't accept wildcards. Exact: mutex:111c List (any of the values): mutex:[111c, 2124] |
ipv4 (ip ) | Group keyword |
---|---|
Includes | ipv4-static ipv4-dynamic |
Examples | Wildcard matching supported. Wildcard: ipv4:192.* List (any of the values): ipv4:[1.0.0.0,1.0.2.1] |
ipv6 | Group keyword |
---|---|
Includes | ipv6-static (IPv6 address strings detected by ReversingLabs Dynamic Services) |
Examples | If the address contains colons or brackets, enclose it in quotation marks. Wildcard matching supported. Wildcard: ipv6:c* Exact: ipv6:"2002::/16" List (any of the values): ipv6:["2001:db8*", "3731:54:"] |
section | Group keyword |
---|---|
Includes | pe-section-name elf-section-name macho-section-name |
Examples | Case-insensitive wildcard matching is supported. Wildcard: section:*data List (Any of the values): section:[.ndata, bss] |
segment | Group keyword |
---|---|
Includes | macho-segment macho-segment-name elf-segment-sha1 |
Examples | Case-insensitive wildcard matching is supported. Wildcard: segment:page* List (any of the values): segment:[pagezero, text] |
software | Group keyword |
---|---|
Includes | software-package software-description software-author |
Examples | The keyword does not accept wildcards. Exact: software:"James Newton-King" List (any of the values): software:[Microsoft, "This package consists of multiple activities that simplify the processes in Excel."] |
uri | Group keyword |
---|---|
Includes | uri-source uri-static uri-config uri-dynamic |
Examples | Case-insensitive wildcard matching is supported. (uri* keywords don't support IP addresses. For that, use ip* keywords.)Wildcard: uri:mozilla.org* List (any of the values): uri:[\*.tor,*.onion,*.exit] |
Single keywords
actor | |
---|---|
Description | Search for files by the organization name of the certificate issuer. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: cert-issuer-org:*authority List (any of the values): cert-issuer-org:[verisign, microsoft] |
android-app-name | |
---|---|
Description | Search for Android applications by their process name. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: android-app-name:*SkypeApplication* List (any of the values): android-app-name:[MainApp, *alt.ywuajgf*] |
android-features | |
---|---|
Description | Search for Android applications by their features. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: android-features:*hardware.camera* List (any of the values): android-features:[camera, telephony] |
android-import | |
---|---|
Description | Search for Android applications by one or more shared libraries that the applications are linked against. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: android-import:org.apache.http.legacy* List (any of the values): android-import:[sec_fe?ture, *google*] |
android-package | |
---|---|
Description | Search for Android applications by their package name. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: android-package:*com.picklieapps.player* List (any of the values): android-package:[*ruckygames*, *skype.raider*] |
android-permission | |
---|---|
Description | Search for Android applications by their permissions. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: android-permission:*WRITE_SETTINGS* List (any of the values): android-permission:[*storage*, *disable_keyguard*] |
appid-company-name (appid-author ) | |
---|---|
Description | Search for applications and libraries by their publisher. Case-insensitive wildcard matching is supported. |
Examples | Exact: appid-company-name:"Mozilla Foundation" List (any of the values): appid-company-name:["Mozilla Foundation", "Microsoft Corporation"] |
appid-description | |
---|---|
Description | Search for applications and libraries by their description. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: appid-description:"*Firefox Plugin Hang UI*"* |
appid-product-name | |
---|---|
Description | Search for files with a matching product name. Case-insensitive wildcard matching is supported. |
Examples | Exact: appid-product-name:"Mozilla Firefox Plugin Hang UI" List (any of the values): appid-product-name:["Mozilla Firefox Plugin Hang UI", "Mozilla Firefox Helper"] |
appid-product-type (appid-category ) | |
---|---|
Description | Search for applications and libraries by their type. Case-insensitive wildcard matching is supported. |
Examples | Exact: appid-product-type:browser List (any of the values): appid-product-type:[browser, development] |
attack-tactic | |
---|---|
Description | Search for files that use a specific Mitre ATT&CK tactic. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: attack-tactic:TA0007 List (any of the values): attack-tactic:[TA0007, TA0005] |
attack-technique | |
---|---|
Description | Search for files that use a specific Mitre ATT&CK technique. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: attack-technique:T1222 List (any of the values): attack-technique:[T1222, T1112] |
av-count (positives , p , antivirus ) | |
---|---|
Description | The number of antivirus scanners that have detected a sample as malicious. Currently supports any integer from 0 to 46 (46 being the number of active AV scanners). |
Examples | Exact: av-count:5 Range: positives:[10 TO 20] Greater than 5: positives:[5 TO *] List (any of the values): av-count:[5,3] |
av-detection (engines ) | |
---|---|
Description | Detection string generated by the antivirus engines. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: av-detection:micro* List (any of the values): av-detection:[W32.Duqu, *Vitro] |
av-<name> (<name> ) | |
---|---|
Description | Search for all samples or samples of specific malware detected by a selected antivirus vendor. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: av-[vendor]:*wannacry* List (any of the values): [vendor]:[win32, emotet] |
available (in , shareable ) | |
---|---|
Description | Indicates whether a sample is available for download from the cloud. The only supported values are true and false (case-insensitive). |
Examples | available:TRUE in: false |
browser-package | |
---|---|
Description | Search for web browser extensions by their package name. Supported package formats: Chrome, Safari, Firefox. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: browser-package:*Click2Save* List (any of the values): browser-package:[*priiceechOp*, *iCalc*] |
cert-issuer-country | |
---|---|
Description | Search for files by the country code in the country name property field of the issuer of the certificate used to sign the file. Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-issuer-country: US List (any of the values): cert-issuer-country:[Z?,G*] |
cert-issuer-name | |
---|---|
Description | Search for files by the name of the certificate authority (CA). Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-issuer-name: COMODO List (any of the values): cert-issuer-name:[microsoft,*VeriSign*] |
cert-issuer-org | |
---|---|
Description | Search for files by the organization name of the certificate issuer. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: cert-issuer-org:*authority List (any of the values): cert-issuer-org:[verisign, microsoft] |
cert-issuer-unit | |
---|---|
Description | Search for files by the organizational unit name of the issuer unit of the certificate authority (CA). Case-insensitive wildcard matching is supported. |
Examples | Wildcard: cert-issuer-unit:*root* List (any of the values): cert-issuer-unit:["trust network", *root*] |
cert-serial | |
---|---|
Description | Search for a file by the serial number of the file certificate provided by the CA that issued the certificate. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: cert-serial:6101CF3E00000000000F List (any of the values): cert-serial:[<value1>,<value2>] |
cert-subject-country | |
---|---|
Description | Search for files by the country code in the country name property field of the subject to which the certificate has been issued. Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-subject-country:DE List (any of the values): cert-subject-country:[US, B*] |
cert-subject-name | |
---|---|
Description | Search for files by the name of the organization/system to which the certificate has been issued. Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-subject-name:Piriform List (any of the values): cert-subject-name:[cinectic*, google] |
cert-subject-org | |
---|---|
Description | Search for files by the organization name of the certificate authority organization (CA). Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-subject-org:apple List (any of the values): cert-subject-org:[apple, Microsoft] |
cert-subject-unit | |
---|---|
Description | Search for files by the organizational unit name inside the organization to which the certificate has been issued. Case-insensitive wildcard matching is supported. |
Examples | Exact: cert-subject-unit:"Developer Relations" List (any of the values): cert-subject-unit:[Developer*, "Trust Network"] |
cert-thumbprint | |
---|---|
Description | Search for files by their unique certificate thumbprint. A thumbprint of a file certificate is a hash value (SHA256). The keyword doesn't accept wildcards. |
Examples | Exact: cert-thumbprint:277D42[...]2A17DD List (any of the values): cert-thumbprint:[<value1>, <value2>] |
classification (class ) | |
---|---|
Description | Search for files by their Malware Presence status designation. Accepted values: malicious, known, suspicious, unknown (case-insensitive). |
Examples | Exact: classification:malicious List (any of the values): classification:[KNOWN, suspicious] |
dex-class-name | |
---|---|
Description | Search for DEX files by the names of classes they contain. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dex-class-name:android.content.DialogInterface.On* List (any of the values): dex-class-name:[android.content.DialogInterface.On*, android.support.v4.*] |
dex-method-name | |
---|---|
Description | Search for DEX files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dex-method-name:unregisterCallB* List (any of the values): dex-method-name:[getLocation, invok*] |
document-author | |
---|---|
Description | Search for files by the contents of their document author metadata property. Case-insensitive wildcard matching is supported. |
Examples | List (any of the values): document-author:[adobe, microsoft] Wildcard: document-author:*soft |
document-description (doc-description ) | |
---|---|
Description | Search for files by the document description field, as provided by the document author. Case-insensitive wildcard matching is supported. |
Examples | List (any of the values): document-description:["Carta personal", *confidencial] Wildcard: document-description:*Math* |
document-pages (doc-pages ) | |
---|---|
Description | Search for files by their number of pages. In case of spreadsheet documents, this number represents the number of sheets. The keyword accepts only integer values. |
Examples | Exact: document-pages:73 Range: document-pages:[4 TO 20] More than 4: document-pages:[4 TO *] |
document-subject | |
---|---|
Description | Search for files by the contents of their document subject metadata property. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: document-subject:*search List (any of the values): document-subject:[free, download] |
document-title | |
---|---|
Description | Search for files by the contents of their document title metadata property. Case-insensitive wildcard matching is supported. |
Examples | Exact: document-title:"Powered by" List (any of the values): document-title:[*free*, README] |
document-version | |
---|---|
Description | Search for files by the contents of their document version metadata property. Wildcard matching is supported. |
Examples | Wildcard: document-version:1.1* List (any of the values): document-version:[1.7, 2.*] |
domain | |
---|---|
Description | Search for files by any associated domain. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: domain:mozilla.org* List (any of the values): domain:[*.tor,google.com,*.exit] |
dotnet-assembly | |
---|---|
Description | Search for .NET files by assemblies they reference. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-assembly:*mscorlib* List (any of the values): dotnet-assembly:[*iJnJWYUQA*, "NanoCore Client"] |
dotnet-method-name | |
---|---|
Description | Search for .NET files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-method-name:get_Url List (any of the values): dotnet-method-name:[?oadCompl*, *HoldEnd] |
dotnet-module-id | |
---|---|
Description | Search for .NET files by IDs of modules they contain. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-module-id:*20DEC3DA-523F* List (any of the values): dotnet-module-id:[*9249F5D0-1821*, *E133ACC7-60C9*] |
dotnet-module-name | |
---|---|
Description | Search for .NET files by names of modules they contain. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-module-name:*TeSt.exe* List (any of the values): dotnet-module-name:[Posh.exe, adobe.exe] |
dotnet-pinvoke-function | |
---|---|
Description | Search for .NET files by pinvoke functions. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-pinvoke-function:EncodePointer* List (any of the values): dotnet-pinvoke-function:["EncodePointer", "DecodePointer"] |
dotnet-pinvoke-import | |
---|---|
Description | Search for .NET files by pinvoke imports. Case-insensitive wildcard matching is supported. |
Examples | Exact: dotnet-pinvoke-import:kernel32.dll List (any of the values): dotnet-pinvoke-import:["kernel32.dll", "user32.dll"] |
dotnet-resource | |
---|---|
Description | Search for .NET files by resources they contain. Case-insensitive wildcard matching is supported. |
Examples | Exact: dotnet-resource:"Hidden Tear" List (any of the values): dotnet-resource:[*Orcus*, *Clientloaderform*] |
dotnet-type-name | |
---|---|
Description | Search for .NET files by type names found in them. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: dotnet-type-name:Form1* List (any of the values): dotnet-type-name:[Form1*, NetscapeRevocationUrl] |
elf-section-count | |
---|---|
Description | Search for ELF files by the amount of sections they contain. The keyword accepts only integer values. |
Examples | Exact: elf-section-count:5 Range: elf-section-count:[5 TO 15] More than 5: elf-section-count:[5 TO *] |
elf-section-name | |
---|---|
Description | Search for ELF files by names of the sections they contain. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: elf-section-name:*data List (any of the values): elf-section-name:[.rodata, .ndata, .bss] |
elf-segment-sha1 (elf-segment-hash ) | |
---|---|
Description | Search for files by the SHA1 hash of their ELF segment. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: elf-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc |
email-from | |
---|---|
Description | Search for files by the sender of an email associated to a file. Includes "from", "reply-to" and "sender" fields. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-from:*@kiski.net List (any of the values): email-from:[*@domain.com, *@orbitz.com] |
email-static (email ) | |
---|---|
Description | Search for files by associated email address(es) detected by Spectra Core. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-static:*@Compartir.es List (any of the values): email-static:[*@gmail.com, *@hotmail.com] |
email-subject | |
---|---|
Description | Search for files by the subject of an email associated to a file. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-subject:*HackTool List (any of the values): email-subject:[Invitation*, *Nova*] |
email-to | |
---|---|
Description | Search for files by the receiver of an email associated to a file, specified in the "to" field. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-to:*@netnook.com List (any of the values): email-to:[*@dekalb.net, *@rogers.com] |
email-x-key | |
---|---|
Description | Search for files with non-standard header fields, called X-extensions. Security vendors use X-extensions to annotate emails that have been scanned using their product. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-x-key:*MDRemoteIP List (any of the values): email-x-key:[*Indiv, *Markup] |
email-x-value | |
---|---|
Description | Search for files by values stored in non-standard (X-extension) header fields. Case-insensitive wildcard matching is supported. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: email-x-value:?HAILAND List (any of the values): email-x-value:[Produced*, BHUTAN] |
exif | |
---|---|
Description | Search for multimedia files by the contents of their EXIF metadata fields. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: exif:Picasa* List (any of the values): exif:["Paint.NET v3.5.8", Picasa*] |
exploit | |
---|---|
Description | Search for samples that are exploiting a specific vulnerability, identified either by ReversingLabs or by antivirus scanners. |
Examples | Examples Wildcard: exploit:cve-2024-* *List (any of the values): exploit:["CVE-2014-0114", "CVE-2018-15982"] |
filecount | |
---|---|
Description | Search for a file by the number of unpacked files it contains (if it's a container). Accepts any integer number. Note: this keyword currently returns only Local samples as results. |
Examples | Exact: filecount:25 Range: filecount:[3 TO 10] More than 20: filecount:[20 TO *] |
filename (name ) | |
---|---|
Description | Search for a file by its full or partial file name, predicted file name (generated by Spectra Core for samples without a file name), or file extension. Case-insensitive wildcard matching is supported. |
Examples | Exact: filename:notepad.exe List (any of the values): filename:[*.PDF, *.epub] |
firstseen (fs ) | |
---|---|
Description | Time when a file was first analyzed by Spectra Intelligence. Supported time format is UTC timestamp. |
Examples | Exact: fs:2018-04-03T12:58:27Z Range (time period): firstseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z] |
hashes | |
---|---|
Description | Allows mixing different types of hashes in one search query, without the need to explicitly name the hash type or to group hashes by type. All hash types (MD5, SHA1, SHA256) can be used with this keyword. The maximum length of a single query is 1024 characters. The keyword is case-sensitive and doesn't support wildcards. |
Examples | Exact: hashes: <sha1> List (any of the values): hashes:[<sha1>, <sha1>, <md5>, <sha256>, <md5>] |
imphash | |
---|---|
Description | Hash based on library/API names and their specific order within the executable. Used to find similar PE files. The keyword doesn't support wildcards. |
Examples | Exact: imphash:f34d5f2d4577ed6d9ceec516c1f5a744 List (any of the values): imphash [<value1>, <value2>] |
indicators | |
---|---|
Description | Search for files by their static analysis behaviors. The keyword is case-sensitive and doesn't accept wildcards. The full list of indicator IDs and their descriptions can be found here <https://fileshare.reversinglabs.com/index.php/s/qkGBJNpKzZZitiN> _. |
Examples | Exact: indicators:"2150" List (any of the values): indicators:["2150", "2102"] |
ios-app-name | |
---|---|
Description | Search for iOS applications by their name. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: ios-app-name:FruitNinja* List (any of the values): ios-app-name:[FruitNinja*, *facebook*] |
ios-author | |
---|---|
Description | Search for iOS applications by their author name. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: ios-author:*halfbrick* List (any of the values): ios-author:[*halfbrick*, Apple*] |
ios-package | |
---|---|
Description | Search for iOS applications by their package name. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: ios-package:*FruitNinja* List (any of the values): ios-package:[*FruitNinja*, *facebook*] |
ipv4-dynamic | |
---|---|
Description | Search for files by IPv4 address strings detected by ReversingLabs Dynamic Services. Wildcard matching supported. |
Examples | Wildcard: ipv4-dynamic:192.* List (any of the values): ipv4-dynamic:[1.0.0.0,1.0.2.1] |
ipv4-static | |
---|---|
Description | Search for files by IPv4 address strings detected by Spectra Core analysis. Wildcard matching supported. |
Examples | Wildcard: ipv4-static:192.* List (any of the values): ipv4-static:[1.0.0.0,1.0.2.1] |
ipv6-static | |
---|---|
Description | Search for files by IPv6 address strings detected by Spectra Core analysis. If the address contains colons or brackets, enclose it in quotation marks. Wildcard matching supported. |
Examples | Wildcard: ipv6-static:c* Exact: ipv6-static:"2002::/16" List (any of the values): ipv6-static:["2001:db8*", "3731:54:"] |
lastanalysis (la ) | |
---|---|
Description | Search for files by the date and time of their last AV scan. Supported time format is UTC timestamp. |
Examples | Exact: lastanalysis:2018-05-17T11:27:19Z Range (time period): lastanalysis:[2018-05-17T11:27:19Z TO 2018-05-24T11:27:19Z] |
lastseen (ls ) | |
---|---|
Description | Time when a file was last analyzed by Spectra Intelligence. Supported time format is UTC timestamp. |
Examples | Exact: ls:2018-04-03T12:58:27Z Range (time period): lastseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z] |
macho-import | |
---|---|
Description | Search for MachO files by the names of imported libraries found in them. Case-insensitive wildcard matching supported. |
Examples | Wildcard: macho-import:*/usr/lib/* List (any of the values): macho-import:[/usr/lib/libgcc_s.1.dylib, /usr/lib/libSystem.B.dylib] |
macho-section-count | |
---|---|
Description | Search for MachO files by the number of sections they contain. The keyword accepts only integer values. |
Examples | Exact: macho-section-count:10 Range: macho-section-count:[5 TO 15] More than 5: macho-section-count:[5 TO *] |
macho-section-name | |
---|---|
Description | Search for MachO files by the names of the sections they contain. Case-insensitive wildcard matching supported. |
Examples | Exact: macho-section-name:data List (any of the values): macho-section-name:[bss, common, data] |
macho-segment (macho-segment-name ) | |
---|---|
Description | Search for MachO files by their segment names. Case-insensitive wildcard matching supported. |
Examples | Exact: macho-segment:pagezero List (any of the values): macho-segment:[linkedit, pagezero, text] |
macho-segment-count | |
---|---|
Description | Search for MachO files by the count of segments they contain. The keyword accepts only integer values. |
Examples | Exact: macho-segment-count:30 Range: macho-segment-count:[2 TO 8] More than: macho-segment-count:[11 TO *] |
macho-segment-sha1 (macho-segment-hash ) | |
---|---|
Description | Search for files by the SHA1 hash of their MachO segment. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: macho-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc |
macho-symbol | |
---|---|
Description | Search for MachO files by their symbol names. Case-insensitive wildcard matching supported. |
Examples | Wildcard: macho-symbol:f* List (any of the values): macho-symbol:[exit, malloc, umask] |
md5 | |
---|---|
Description | String of hexadecimal digits representing a MD5 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: md5:76baa04885ec40af25294a51d8e7c006 List (any of the values): md5:[<value1>, <value2>] |
mutex-config | |
---|---|
Description | Search for files by their malware configuration mutexes detected by Spectra Core. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: mutex-config:")!VoqA.I4" Exact: mutex-config:"--((Mutex))--" List (any of the values): mutex-config:[111c, 2124] |
mutex-dynamic | |
---|---|
Description | Search for files by malware configuration mutexes detected by ReversingLabs Dynamic Services. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Wildcard: mutex-dynamic:111c* List (any of the values): mutex-dynamic:[111c, 2124] |
pdb-path (pdb) | |
---|---|
Description | Search for files associated with specific PDB (program database) paths. Used to find files with the same PDB path created during file sample compilation. If the path contains restricted characters, enclose it in quotation marks. |
Examples | Exact: pdb:"D:DevTin7InstallDir" List (any of the values): pdb:["C:Windows", "c:Program FilesPerforce"] |
pe-company-name | |
---|---|
Description | Search for PE files by the contents of their company name field in the version information metadata. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-company-name:*enix List (any of the values): pe-company-name:[microsoft, ADOBE] |
pe-copyright | |
---|---|
Description | Search for PE files by the contents of their legal copyright field in version information metadata. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-copyright:Copyright* List (any of the values): pe-copyright:[*Corporation, regsvr32] |
pe-description | |
---|---|
Description | Search for PE files by the contents of their file description field in version information metadata. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-description:*proged List (any of the values): pe-description:[DisplaySwitch, WizardFramework] |
pe-export (exports ) | |
---|---|
Description | Search for PE files by exported symbol names. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-export:MS* List (any of the values): exports:[GetMemoSize, DeleteFile] |
pe-function | |
---|---|
Description | Search for PE files by the name of the function that the PE file imports. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-function:RegEnum* List (any of the values): pe-function:[RegEnumKeyW, GetUserNameA] |
pe-import (imports) | |
---|---|
Description | Search for PE files by the name of the dynamic link library that the PE file imports. Case-insensitive wildcard matching supported. |
Examples | Exact: pe-import:URLMON.DLL List (any of the values): imports:[win*, url*] |
pe-language | |
---|---|
Description | Find PE files by languages mentioned in the PE file resources. Case-insensitive wildcard matching supported. Appendix C - Available Languages for PE and Document Formats _ |
Examples | Exact: pe-language:russian List (any of the values): pe-language:[eng*, Russian] |
pe-original-name | |
---|---|
Description | Search for PE files by the contents of their file description field in version information metadata, and any other fields using the original name of the file. The keyword can be used to investigate how the file was named during compilation. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-original-name:crack* List (any of the values): pe-original-name:[*install.exe, "sample doc.exe"] |
pe-overlay-sha1 (pe-overlay-hash ) | |
---|---|
Description | Find PE files by the SHA1 hash calculated for their overlay part. Overlay hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: pe-overlay-sha1:4b4a2436b827d42b204b1f112b45d7a6d1b7ca52 List (any of the values): pe-overlay-sha1:[<value1>, <value2>, <value3>] |
pe-product-name | |
---|---|
Description | Search for PE files by the contents of their product name field in version information metadata. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-product-name:*shop List (any of the values): pe-product-name:[Firefox, "Microsoft Word"] |
pe-resource | |
---|---|
Description | Search for PE files by name or type of resources they contain. Case-insensitive wildcard matching supported. |
Examples | Exact: pe-resource:Properties List (any of the values): pe-resource:[Tcpview, Aboutbox] |
pe-resource-sha1 (pe-resource-hash ) | |
---|---|
Description | Find PE files by the SHA1 hash calculated for their resources part. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: pe-resource-sha1:4260284ce14278c397aaf6f389c1609b0ab0ce51 List (any of the values): pe-resource-sha1:[<value1>, <value2>] |
pe-section-count | |
---|---|
Description | Search for PE files by the count of sections they contain. The keyword accepts only integer values. |
Examples | Exact: pe-section-count:15 Range: pe-section-count:[2 TO 10] More than: pe-section-count:[5 TO *] |
pe-section-name | |
---|---|
Description | Search for PE files by names of the sections they contain. The maximum section name length is 8 characters. Case-insensitive wildcard matching supported. |
Examples | Wildcard: pe-section-name:*rdata List (any of the values): pe-section-name:[.Rdata, .Ndata, *rsrc] |
pe-section-sha1 (pe-section-hash ) | |
---|---|
Description | Find PE files by the SHA1 hash calculated for their section part. Section hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: pe-section-sha1:7640a007e39b487bf1dbbde6487724faa131f6a8 List (any of the values): pe-section-sha1:[<value1>, <value2>, <value3>] |
pe-timestamp (pets ) | |
---|---|
Description | Search for a PE file by the date when it was compiled. Supported time format is UTC timestamp. |
Examples | Exact: pets:2017-06-26T00:00:00Z Range (newer than): pets:[2018-03-06T10:57:29Z TO *] |
sampletype (filetype , type , format ) | |
---|---|
Description | Search for files by type as detected by Spectra Core. Case-insensitive wildcard matching supported. Appendix B - Supported Sample Types _ |
Examples | Exact: sampletype:Image/None List (any of the values): type:[elf*,macho*] |
sha1 | |
---|---|
Description | String of hexadecimal digits representing a SHA-1 hash of the file. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: sha1:f1a62a7092e49577206b7361bf1a7ff0776bb6a4 List (any of the values): sha1:[<value1>, <value2>] |
sha256 | |
---|---|
Description | String of hexadecimal digits representing a SHA-256 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: sha256:f35a3(...)1d2d5 List (any of the values): sha256:[<value1>, <value2>] |
signer-valid-from (cert-valid-from ) | |
---|---|
Description | Search for files that have been signed by certificates valid from a specific time. |
Examples | Range (newer than): signer-valid-from:[2018-03-06T10:57:29Z TO *] |
signer-valid-to (cert-valid-to ) | |
---|---|
Description | Search for files that have been signed by certificates valid to a specific time. |
Examples | Range (newer than): signer-valid-to:[2018-03-06T10:57:29Z TO *] |
similar-to | |
---|---|
Description | Search for files that are functionally similar to the requested file hash. Functionally similar files are defined by RHA (ReversingLabs Hashing Algorithm) that identifies code similarity between unknown samples and previously seen malware samples. All hash types (MD5, SHA1, SHA256) can be used with this keyword. Only one similar-to keyword can be used in a single query. The keyword is case-sensitive and doesn't support wildcards. |
Examples | Exact: similar-to: <sha1> |
size | |
---|---|
Description | Search for files by size (in bytes). Accepts integers up to 2147483647. |
Examples | Exact: size:30000 Range: size:[1000 TO 50000] Greater than: size:[500000 TO *] |
software-author | |
---|---|
Description | Search for software packages by their author/publisher. |
Examples | Exact: software-author:"James Newton-King" List (any of the values): software-author:["Amazon Web Services", Microsoft] |
software-description | |
---|---|
Description | Search for software packages by their description. |
Examples | Exact: software-description:"This package consists of multiple activities that simplify the processes in Excel." |
software-package | |
---|---|
Description | Search for specific software packages. The keyword is case-sensitive and doesn't accept wildcards. |
Examples | Exact: software-package:tidal List (any of the values): software-package:[tidal, "AWSSDK.WorkLink"] |
submissions | |
---|---|
Description | Search for files by the amount of times they have been submitted for analysis. The keyword accepts only integer values. |
Examples | Exact: submissions:3 Greater than: submissions:[3 TO *] Less than: submissions:[* TO 4] |
tag | |
---|---|
Description | Search for files by metadata tags generated by Spectra Core. Tags identify interesting properties of a sample, such as being packed, password-protected, or digitally signed. Appendix E - Supported Tags _ |
Examples | Exact: tag:packed List (any of the values): tag:[capability-execution, cert, crypto] |
tag-yara | |
---|---|
Description | YARA supports adding custom tags to rules. Files that match those rules get automatically tagged after analysis. This keyword looks for files tagged by YARA rules, including those that were classified by YARA tags ("malicious" and "suspicious"). Case-insensitive wildcard matching is supported. Note that changes to YARA tags are not immediately reflected in search results. For example, if a tag is removed from a YARA rule, it will still return search results until files that match the rule are reanalyzed with Spectra Core. |
Examples | Exact: tag-yara:malicious List (any of the values): tag-yara:[malicious, suspicious] |
taggant-name | |
---|---|
Description | Search for PE files by name of the packer that was used to pack them. Taggant is a technology that guarantees the packed file came from a reliable source. Case-insensitive wildcard matching supported. |
Examples | Exact: taggant-name:themida List (any of the values): taggant-name:[enigma*, vmprotect*] |
taggant-valid-from | |
---|---|
Description | Search for files by the time it was signed using taggant. |
Examples | Range (newer than): taggant-valid-from:[2018-03-06T10:57:29Z TO *] |
taggant-valid-to | |
---|---|
Description | Search for files by the expiry time provided by taggant. |
Examples | Range (newer than): taggant-valid-to:[2018-03-06T10:57:29Z TO *] |
third-party-library | |
---|---|
Description | Search for PE files by the name(s) of third-party libraries they contain. Case-insensitive wildcard matching is supported. |
Examples | Exact: third-party-library:Microsoft.WindowsAPICodePack-Core List (any of the values): third-party-library:[*oak-json*, Microsoft.Web.WebJobs*] |
third-party-publisher | |
---|---|
Description | Search for PE files by publishers of the third-party libraries found in the files. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: third-party-publisher:Microsoft* List (any of the values): third-party-publisher:[Microsoft*, "Xamarin Inc."] |
threatlevel | |
---|---|
Description | Search for files by ReversingLabs scale of threat severity. Higher number indicates higher severity. Accepted values are 0-5. |
Examples | Exact: threatlevel:3 Greater than: threatlevel:[2 TO *] Range: threatlevel:[0 TO 3] List (any of the values): threatlevel:[2, 3] |
threatname | |
---|---|
Description | Search for files by malware threat name according to Appendix A - ReversingLabs Malware Naming Standard _. Case-insensitive wildcard matching supported. |
Examples | Exact: threatname:Win32.PUA.Casonline List (any of the values): threatname:["WIN32.PUA.casino eldorado", *crytex] |
trustfactor | |
---|---|
Description | Search for files by the ReversingLabs trust factor. Trust factor indicates the trustworthiness of files. Lower number means higher trust. Accepted values are 0-5. |
Examples | Exact: trustfactor:1 List (any of the values): trustfactor:[4, 5] Range: trustfactor:[1 TO 3] Greater than: trustfactor:[3 TO *] |
uri-config (c2 ) | |
---|---|
Description | Malware configuration C&C (Command & Control), extracted by Spectra Core. C&C infrastructure is used to control malware, particularly botnets. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: c2:*dns* List (any of the values): uri-config:[dydns.org, hldns.ru] |
uri-dynamic | |
---|---|
Description | Search for files by URI strings (URLs, domains) detected by ReversingLabs Dynamic Services. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: uri-dynamic:mozilla.org* List (any of the values): uri-dynamic:[*.tor,*.onion,*.exit] |
uri-source (itw ) | |
---|---|
Description | Search for files by the URI source from which they were downloaded. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: uri-source:*warez* List (any of the values): itw:[softonic.com, *cnet.com] |
uri-static | |
---|---|
Description | Search for files by URI strings (URLs, domains) detected by Spectra Core. Case-insensitive wildcard matching is supported. |
Examples | Wildcard: uri-static:mozilla.org* List (any of the values): uri-static:[*.tor,*.onion,*.exit] |
vertical | |
---|---|
Description | Search for files by the type of vertical feed in which they were found. Case-insensitive wildcard matching is supported. |
Examples | Exact: vertical:ransomware List (any of the values): vertical:[ransomware,apt,financial] |
Search query
POST /api/search/v1/query
This query returns a <records_per_page> records of new samples matching the search criteria sent in the request.
If more than <records_per_page> records match the requested criteria, the response will have a next_page field, which can be used in the request to fetch the next page with up to <records_per_page> results.
The maximum amount of API results that can be returned for a search query is 100,000. To avoid going over the maximum limit of results, set the increment limit to 100, and stop incrementing when the response contains more_pages = false
value, or the response status code is 400 Bad Request.
Request
Request body:
{
"query": "string",
"page": 0,
"records_per_page": 0,
"format": "string",
"sort": "string"
}
query
page
- Possibility to select a page number when there are more than <records_per_page> samples in the result. Defaults to first page ("page": 1) if omitted. The maximum amount of pages that can be fetched is the overall limit of results (100000) divided by the requested amount of results per page. For example, if the requested amount of results per page is 1000, the maximum amount of pages is 100. When there are no more results, the more_pages value in the response will be false. If the requested page doesn't exist, or the overall amount of results would be over 100000, the response "Max limit reached" with status code 400 is returned.
- Optional
records_per_page
- The number of records returned in the response. Defaults to 10000 if omitted
- Optional
format
- Possibility to choose an optional return format. Allowed values are xml (default) and json.
- Optional
sort
- Possibility to sort results by one of these fields: sha1, firstseen, threatname, sampletype, filecount, size. Query results can be sorted in ascending or descending order by using the asc or desc keywords (example: "sort": threatname asc). By default, the results are sorted by firstseen date in descending order (most recent to oldest). To ensure optimal sorting and paging of large datasets, the results are sorted in sequential 10000 row blocks.
- Optional
Quotation marks
Quotation marks match an exact string, and are necessary if the string contains spaces or any other restricted characters. To submit a query in quotation marks, they have to be escaped (for example, filename:\"Visual Studio Installer\"
). Note that this matches only those samples that are called exactly "Visual Studio Installer", and will not find "Visual Studio Installer.exe". To match files by substrings, use wildcard characters.
If the query doesn't contain any restricted characters, quotation marks can be omitted without changing the results.
Wildcard characters
The character *
matches any sequence of characters. The character ?
matches any single character. Wildcards cannot be mixed with quotation marks, as that makes them a literal part of the string to match.
To properly use wildcards, submit the query without escaping the quotation marks (threatname:"ThreatNam*"
). In this case, search will return all ThreatName
samples, but also ThreatName2
or anything else that matches the wildcard placement. Another example, using both the asterisk and the question mark: threatname:"*ThreatName?"
matches "SomeThreatName" and "OtherThreatName1". With escaped quotes, threatname:\"*ThreatName?\"
matches *ThreatName?
, and nothing else.
Wildcards can be placed anywhere in the query. The following example searches for any word that starts with p
and ends with ton
in the threatname field: threatname:p*ton
.
Restricted Words and Characters
All restricted words and characters should be escaped with double quotation marks in the search expression. Backslashes (\
) also have to be escaped, but don't have to be inside quotation marks.
Example: a query contains one of the restricted characters ( [
, ]
, (
, )
, :
). This example also contains an escaped \
character.
pdb:\"C:\\Windows*\"
Example: a query contains one of the restricted words (AND
, OR
, NOT
)
cert-subject-name:\"AND\"
If the search query contains spaces, use (escaped) double quotation marks around it.
cert-subject-org:\"microsoft corporation\"
String query
String that represents the user's search query.
Example request body:
{
"query": "<field_name>:<field_value> <field_name>:<field_value> ...",
"page": 1,
"records_per_page": 1000,
"format": "xml"
}
Expression Syntax
Every search expression must contain at least one keyword and one criterion. Search expressions are built according to the following formula: <field_name>:<field_value>.
field_name
The name of the parameter queried on. Allowed values are listed in the table of supported-keywords
.
field_value
The value against which the parameter is tested. The following operators are supported:
Equals operator
Syntax:
<field_name>:<field_value>
Examples:
classification:malicious
available:true
firstseen:2018-01-01T00:00:00Z
Range operator
Range of values between from_value and to_value, including the upper and lower boundary. An asterisk (*) may be used for either one or for both endpoints to specify an open-ended range query.
Syntax:
<field_name>:[<from_value> TO <to_value>]
<field_name>:[<from_value> TO *]
<field_name>:[* TO <to_value>]
Examples:
firstseen:[2018-01-01T00:00:00Z TO 2018-01-02T00:00:00Z]
threatlevel:[0 TO *]
size:[* TO 500]
In operator
The value of a field equals any value in the specified list.
Syntax:
<field_name>:[<value_1>, <value_2>, ...]
Examples:
classification:[malicious, suspicious]
Creating Multi-keyword Search Expressions
Search operators and parentheses can be used to combine multiple keywords and create advanced search expressions. The following search operators are supported: AND, OR, NOT.
If an operator is not provided, AND is used as the default. Operators are case-insensitive, so the following queries all return the same result:
firstseen:2018-01-01T00:00:00Z AND classification:malicious
firstseen:2018-01-01T00:00:00Z and classification:malicious
firstseen:2018-01-01T00:00:00Z classification:malicious
The NOT operator excludes search results that match the defined criteria. In the following example, malicious and suspicious files will be excluded from the results.
av-detection:linux NOT classification:[malicious, suspicious]
The OR operator can be used to look for any of the values supported by a single keyword: classification:suspicious OR classification:malicious
It can also be used to look for any of the different keywords and their values:
pdb:JigsawRansomware.pdb OR uri:"http://btc.blockr.io/api/v1/"
Note that the OR operator cannot be used instead of a comma when searching for a list of values. The following example is not a valid query:
av-detection:[emotet OR wannacry]
Parentheses can be used to combine keywords. The following two queries show how to format the same expression using square brackets versus parentheses:
firstseen:`2018`-01-01T00:00:00Z av-detection:[trojan,wannacry]
firstseen:2018-01-01T00:00:00Z (av-detection:trojan OR av-detection:wannacry)
Apart from using parentheses for the same keyword, you can use them to combine multiple different keywords, operators, and even a range:
firstseen`:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3])
List of search_field objects that represent the user query. Each search_field object is a part of the whole query.
Example:
{
"query":[
{
"name": <field_name>,
"criteria": <criteria>,
"value": <field_value>
},
{
"name": <field_name>,
"criteria": <criteria>,
"value": <field_value>,
"operator": <field_operator>
},
…
],
"page": 1,
"records_per_page": 1000,
"format": "xml"
}
JSON query
Instead of using a string, the query
field can accept an array of objects structured like so:
{
"name": <field_name>,
"criteria": <criteria>,
"value": <field_value>,
"operator": <field_operator>
}
- name (required) The name of the parameter queried on. Allowed values are listed in the table of
supported-keywords
. - value (required) The value against which the parameter is tested. The structure of the value field depends on the criteria field
- criteria (required) Operator used for testing condition. Allowed values for this field are:
eq | equal |
neq | does not equal |
gt | greater than |
gte | greater or equal |
lt | less than |
lte | less than or equal |
range | range of values between from_value and to_value |
in | the value of a field equals any value in the specified list |
nin | the value of a field does not equal any value in the specified list |
For eq, neq, gt, gte, lt, and lte the field value is a simple string, integer or datetime, depending on <field_name>.
Example:
{
"name":"classification",
"criteria":"eq",
"value": "malicious"
}
For range criteria, the field value is a JSON object with the structure:
{
"from": <from_value>,
"to": <to_value>
}
An asterisk (*) may be used for either one or for both endpoints to specify an open-ended range query.
Example:
{
"name":"firstseen",
"criteria":"range",
"value": {
"from": "2017-06-20T00:00:00Z",
"to": "*"
}
}
For in and nin criteria, field value is a list of string, integer or datetime values.
Example:
{
"name":"classification",
"criteria":"in",
"value": ["malicious", "suspicious"]
}
- operator (optional) Operator is used to combine two search fields (it is not necessary for the first element in the list). Operators are case-insensitive. Allowed values are AND and OR. If an operator is not provided, AND will be used.
Example:
[
{
"name": "classification",
"criteria": "eq",
"value": "malicious"
},
{
"name": "classification",
"criteria": "eq",
"value": "suspicious",
"operator": "OR"
}
]
This can be interpreted as:
classification:malicious OR classification:suspicious
Wildcard Characters
The character *
matches any sequence of characters. The character ?
matches any single character.
The following example searches for any word that starts with "p" and ends with "ton" in the threatname field.
{
"name":"threatname",
"criteria":"eq",
"value":"p*ton"
}
Field Restrictions
Field Name | actor * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | android-app-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | android-features * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | android-import * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | android-package * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | android-permission * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | appid-company-name (appid-author) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | appid-description * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | appid-product-name |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | appid-product-type (appid-category) * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | attack-tactic * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | attack-technique * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | av-count (positives, p, antivirus) |
---|---|
Type | integer |
String Query | eq, range, in |
JSON Query | eq, range, gt, gte, lt, lte, in |
Field Name | av-detection * (engines *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | av-(name) * ((name) *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | available (in, shareable) |
---|---|
Type | boolean |
String Query | eq |
JSON Query | eq |
Field Name | browser-package * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-issuer-country * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-issuer-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-issuer-org * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-issuer-unit * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-serial |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | cert-subject-country * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-subject-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-subject-org * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-subject-unit * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | cert-thumbprint |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | classification |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | dex-class-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dex-method-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | document-author * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | document-description (doc-description) * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | document-pages (doc-pages) |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | document-subject * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | document-title * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | document-version * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | domain * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-assembly * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-method-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-module-id * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-module-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-pinvoke-function * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-pinvoke-import * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-resource * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | dotnet-type-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | elf-section-count |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | elf-section-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | elf-segment-sha1 (elf-segment-hash) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-from * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-static * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-subject * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-to * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-x-key * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | email-x-value * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | exif * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | exploit * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | filecount |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | filename * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | firstseen (fs) |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | hashes |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | imphash |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | indicators |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | ios-app-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ios-author * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ios-package * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ipv4 * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ipv4-dynamic * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ipv4-static * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ipv6 * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | ipv6-static * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | lastanalysis (la) |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | lastseen (ls) |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | macho-import * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | macho-section-count |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | macho-section-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | macho-segment (macho-segment-name) * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | macho-segment-count |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | macho-segment-sha1 (macho-segment-hash) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | macho-symbol * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | md5 |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | mutex |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | mutex-config |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | mutex-dynamic |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | pdb-path * (pdb *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-company-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-copyright * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-description * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-export * (exports) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-function * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-import * (imports) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-language * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-original-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-overlay-sha1 (pe-overlay-hash) |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | pe-product-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-resource * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-resource-sha1 (pe-resource-hash) |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | pe-section-count |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | pe-section-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | pe-section-sha1 (pe-section-hash) |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | pe-timestamp pets |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | sampletype * (filetype *, type *, format *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | sha1 |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | sha256 |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | signer-valid-from (cert-valid-from) |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | signer-valid-to (cert-valid-to) |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | similar-to |
---|---|
Type | string |
String Query | eq |
JSON Query | eq, neq |
Field Name | size |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | software-author |
---|---|
Type | string |
String Query | eq |
JSON Query | eq, neq |
Field Name | software-description |
---|---|
Type | string |
String Query | eq |
JSON Query | eq, neq |
Field Name | software-package |
---|---|
Type | string |
String Query | eq |
JSON Query | eq, neq |
Field Name | submissions (s) |
---|---|
Type | integer |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | tag |
---|---|
Type | string |
String Query | eq, in |
JSON Query | eq, neq, in, nin |
Field Name | tag-yara * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | taggant-name * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | taggant-valid-from |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | taggant-valid-to |
---|---|
Type | datetime |
String Query | eq, range |
JSON Query | eq, range, gt, gte, lt, lte |
Field Name | third-party-library * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | third-party-publisher * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | threatlevel |
---|---|
Type | integer |
String Query | eq, range, in |
JSON Query | eq, range, gt, gte, lt, lte, in |
Field Name | threatname * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | trustfactor |
---|---|
Type | integer |
String Query | eq, range, in |
JSON Query | eq, range, gt, gte, lt, lte, in |
Field Name | uri * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | uri-config * (c2 *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | uri-dynamic * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | uri-source * (itw *) |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | uri-static * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Field Name | vertical * |
---|---|
Type | string |
String Query | eq*, in |
JSON Query | eq*, neq, in, nin |
Response Format
rl.web_search_api
{
"total_count": 0,
"next_page": 0,
"more_pages": true,
"sample_count": 0,
"entries": []
}
total_count
- Number of samples that match the search criteria.
next_page
- Page number that can be used in the request to retrieve the next batch of results.
more_pages
- Indicates whether there are multiple batches of results available.
sample_count
- Number of samples in the response.
rl.web_search_api.entries
{
"sha1": "string",
"sha256": "string",
"md5": "string",
"classification": "string",
"threatlevel": 0,
"trustfactor": 0,
"threatname": "string",
"size": 0,
"available": true,
"antivirus": 0,
"firstseen": "string",
"lastseen": "string",
"sampletype": "string",
"filename": "string",
"filecount": 0
}
sha1
- The SHA1 hash of the analyzed sample.
sha256
- The SHA256 hash of the analyzed sample.
md5
- The MD5 hash of the analyzed sample.
classification
- File classification. Possible values are MALICIOUS, SUSPICIOUS, KNOWN, UNKNOWN.
threatlevel
- Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). Applies to malicious and suspicious samples only.
trustfactor
- Trustworthiness indicator for goodware samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). Applies to known samples only.
threatname
- Complete malware threat name. Conforms to ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious and suspicious samples only.
size
- Sample size in bytes, specified as an integer. Accepts integers up to 2147483647.
available
- Indicates whether the analyzed sample was available or not (at the time of the analysis).
antivirus
- The number of antivirus scanners that have detected the sample as malicious, specified as an integer.
firstseen
- Indicates the date and time when the file was first uploaded to the system, or when it was scanned for the first time.
lastseen
- Indicates the date and time when the file was last uploaded to the system, or when it was scanned for the last time.
sampletype
- Detected sample type for the requested sample.
filename
- The name of the file.
filecount
- The number of unpacked files the sample contains (if it's a container).
Empty Response Format
If no records for given criteria are available, the following response is returned:
{
"rl":{
"web_search_api":{
"total_count":0,
"next_page":null,
"more_pages": false,
"sample_count":0,
"entries":[]
}
}
}
Examples
Example 1 - Fetching new Win32 malware from 2017-06-20 00:00:00 till 2017-06-21 00:00:00
/api/search/v1/query
POST data:
String query:
{
"query":"firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z]
classification:[malicious, suspicious] threatname:win32"
}
JSON query:
{
"query":[
{
"name":"firstseen",
"criteria":"range",
"value":{
"from":"2017-06-20T00:00:00Z",
"to":"2017-06-21T00:00:00Z"
}
},
{
"name":"classification",
"criteria":"in",
"value":[
"malicious",
"suspicious"
]
},
{
"name":"threatname",
"criteria":"eq",
"value":"Win32"
}
]
}
Example 2 - The same query from Example 1 with response format as JSON and 100 records per page
/api/search/v1/query
POST data:
String Query:
{
"query":"firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z]
classification:[malicious, suspicious] threatname:win32",
"format":"json",
"records_per_page":100
}
JSON query:
{
"query":[
{
"name":"firstseen",
"criteria":"range",
"value":{
"from":"2017-06-20T00:00:00Z",
"to":"2017-06-21T00:00:00Z"
}
},
{
"name":"classification",
"criteria":"in",
"value":[
"malicious",
"suspicious"
]
},
{
"name":"threatname",
"criteria":"eq",
"value":"Win32"
}
],
"format":"json",
"records_per_page":100
}
Example 3 - Fetching the next 100 results for the same query
/api/search/v1/query
POST data:
String Query:
{
"query":"firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z]
classification:[malicious, suspicious] threatname:win32",
"page":2,
"format":"json",
"records_per_page":100
}
JSON query:
{
"query":[
{
"name":"firstseen",
"criteria":"range",
"value":{
"from":"2017-06-20T00:00:00Z",
"to":"2017-06-21T00:00:00Z"
}
},
{
"name":"classification",
"criteria":"in",
"value":[
"malicious",
"suspicious"
]
},
{
"name":"threatname",
"criteria":"eq",
"value":"Win32"
}
],
"page":2,
"format":"json",
"records_per_page":100
}
Additional Information
Appendix A - ReversingLabs Malware Naming Standard
The ReversingLabs detection string consists of three main parts separated by dots. All parts of the string will always appear (all three parts are mandatory).
The first part of the string indicates the platform targeted by the malware. If the platform is ByteCode, Document or Script, then there will be an additional subplatform string. Platform and subplatform strings are separated by a hyphen ( - ).
The second part of the detection string describes the malware type. The third part represents the malware family name (one of most common names for that malware).
Examples
If a trojan is designed for the Windows 32 platform and its family name is "Adams", the detection string will look like this:
Win32.Trojan.Adams
If backdoor malware is a PHP script with the family name "Jones", the detection string will look like this:
Script-PHP.Worm.Jones