FQL Documentation
Table of Contents
Grammar
expr := clause | expr bool expr | [not] ( expr )
clause := name op value
bool := and | or
op := eq | = |
ne | != |
gt | > |
ge | >= |
lt | < |
le | <= |
like | ~
Operators
Operator availability depends on the field type.
For fields of type number (int, float) the following operators are allowed (plus their symbolic counter part):
- eq, ne, gt, ge, lt, le
- (Info) Please make sure that you use the correct number format for a field (e.g. 0 for integer fields and 0.0 for float fields)
- (Info) Float numbers must be entered with dot as decimal mark (e.g. 0.9). Please note that entering comma as decimal mark (e.g. 0,9) will not work
For fields of type string the following operators are allowed (plus their symbolic counter part):
- eq, ne, gt, ge, lt, le, like
- (Info) Strings must be delimited by double quotes ( e.g. "this is a string" )
- (Info) The like operator supports _ as wildcard for any single character and % as wildcard for zero or more characters
For fields of type boolean the following operators are allowed (plus their symbolic counter part):
- eq, ne
For fields of type date the following operators are allowed (plus their symbolic counter part):
- eq, ne, gt, ge, lt, le
- (Info) Dates must be delimited by double quotes ( e.g. "this is a string" )
- (Info) The format for the date is of: yyyy-MM-dd HH:mm:ss
For fields of type uuid the following operators are allowed (plus their symbolic counter part):
- eq, ne
- (Info) UUID must be delimited by double quotes ( e.g. "this is a string" )
For the equality operators (eq, ne) it is also possible to test for the absence of a value (check for null).
Fields
Each filter in the API operates on 1 target per URL. Each target has different fields and field types. The following tables first list all available targets and then describe the available fields for each target.
URL | Filter | target |
---|---|---|
/v2/domain | domain | object |
/v2/infected | result | object |
/v2/bundle | bundle | object |
/v2/user | user | object |
/v2/user/ |
notification | object |
/v2/agent/download | agent | object |
/v2/agent/token | agent | token object |
The following fields can be filtered:
domain object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/domain of the API.
field | type | description |
---|---|---|
id | int | Unique ID of a domain object |
bundle | uuid | ID of the bundle to which a domain is assigned |
name | string | Domain Name (e.g. www.example.com) |
scheme | string | Either http or https |
result object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/infected of the API.
field | type | description |
---|---|---|
event | string | Event which the result signifies. |
category | string | Category into which the result falls (e.g. text, blacklist) |
severity | int | [1-3] Severity of the result ranging from 1 (yellow) to 3 (red) |
probability | float | Probability that the result was create because of malicious act |
safetodelete | boolean | Flag to indicate if the file linked to this result can be deleted safely (e.g. if the file was uploaded by an attacker and does not belong to the rest of the website) |
createdate | date | Date on which the event causing this result was first found |
lastdate | date | Date on which the event causing this result was last found |
threatname | string | Name of the threat detected. This information is not available for all types of events |
resource | string | File linked with this result on which the event occured |
md5 | string | MD5 checksum of the file |
diff | string | Difference between the last and current verison of the file. This information is not available for all types of events |
Events
event | description |
---|---|
added-file | A file has been added to the baseline of a website |
blacklist | The domain is on a blacklist |
blacklist-ref | The website contains links to a suspicious domain or URL |
changed-file | A file of the baseline of a website has been modified |
changed-template | A change that appears on every website aggregated in this result |
cms-version | The detected cms version do not match the most recent version and can/should be updated |
cms-vulnerable | The detected cms version has one or more known CVE (Common Vulnerabilities and Exploits) |
defacement | A defacement found on a website |
deleted-file | A file of the baseline of the website has been deleted |
malware | Malware found on the website |
renamed-executable | A file that appears to be source code (e.g. PHP), but has a different/additional file ending and could thus be downloaded and leaking sensitive information |
ssl-ciphersuite | Indicates that the server accepts unsafe ciphersuites |
ssl-expired | Indicates that a SSL/TLS certifcate is already expired |
ssl-expires | Indicates that a SSL/TLS certificate is about to expire |
ssl-notrust | Indicates that a SSL/TLS certificate is not trustworthy |
ssl-protocol | Indicates that the server accepts unsafe protocols |
webshell | Webshell found on the baseline of a website |
bundle object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/bundle of the API.
field | type | description |
---|---|---|
id | uuid | Unique ID of the bundle |
name | string | Name of the bundle |
startdate | date | Date as of which the bundle is active |
enddate | date | Date until which the bundle is active. If enddate is not set there is no fixed duration. The bundle will be extended on a monthly basis unless it is cancelled |
contingent | int | Number of domains that can be linked to this bundle |
active | int | Number of domains currently active in this bundle |
user object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/userof the API.
field | type | description |
---|---|---|
id | int | Unique ID of the user |
login | string | Login name of the user |
company | string | Company name of the user |
surname | string | Surname of the user |
forename | string | Forename of the user |
string | e-mail address of the user | |
mobile | string | mobile phone number of the user |
notification object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/user/
field | type | description |
---|---|---|
id | int | Unique ID of a notification set |
domain | int | Domain ID to which the notification is linked |
transport | string (sms / mail) | Channel over which the notification should occur. Available values are sms or mail |
serverside | int | [1-3] Severity at/above which a user should be notified for serverside issues |
content | int | [1-3] Severity at/above which a user should be notified for content changes |
blacklist | int | [1-3] Severity at/above which a user should be notified for blacklistings |
(Info) the values for serverside, content and blacklist reflect the severity as described in result object
agent object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/download of the API.
field | type | description |
---|---|---|
os | string (linux / windows) | Operating system on which the agent has to run. Available values: linux, windows |
arch | string(32bit / 64bit) | System Architecture on which teh agent has to run. Available values: 32bit, 64bit |
version | int | Version number of the agent |
md5 | string | MD5 Checksum of the agent executable or archive |
sha1 | string | SHA1 Checksum of the agent executable or archive |
format | string (zip / bin) | Format in which the agent should be offered for download. Available values: zip (zip-archive), bin (binary executable) |
agent token object
The following table describes all fields that can be filtered when you are interacting with the URL /v2/token of the API.
field | type | description |
---|---|---|
id | int | Unique ID of an agent token |
name | string | Name of the agent token |
key | string | API key of the agent token |
secret | string | API secret of the agent token |
lastcall | date | Date of the last call to the API for which this agent token was used |
version | int | Version of the agent that issued the last call to the API with this agent token |
Examples
Symbolic Operators
domain with id 10
id = 10
domain with id 10 and starting with example (matches e.g. example.com)
id = 10 and name ~ "example%"
(domain with id 10 and schema "https") or domains that are not "blog.example.com"
(id = 10 and schema = "https") or name != "blog.example.com"
results that have category "text" and a probability greater or equal 0.9
category = "text" and probability >= 0.9
results that refer to files which are safe to delete
safetodelete = "true"
results that last occurred on or before 2015-07-01 00:00:00
lastdate <= "2015-07-01 00:00:00"
domains that do not have the bundle identifier a39649ff-ddb5-47ce-8b97-9758961534b1
not (bundle = "a39649ff-ddb5-47ce-8b97-9758961534b1")
bundles that do not have an end date set
enddate = null
Textual Operators
domain with id 10
id eq 10
domain with id 10 and starting with example (matches e.g. example.com)
id eq 10 and name like "example%"
(domain with id 10 and schema "https") or domains that are not "blog.example.com"
(id eq 10 and schema eq "https") or name ne "blog.example.com"
results that have category "text" and a probability greater or equal 0.9
category eq "text" and probability ge 0.9
results that refer to files which are safe to delete
safetodelete eq "true"
results that last occurred on or before 2015-07-01 00:00:00
lastdate le "2015-07-01 00:00:00"
domains that do not have the bundle identifier a39649ff-ddb5-47ce-8b97-9758961534b1
not (bundle eq "a39649ff-ddb5-47ce-8b97-9758961534b1")
bundles that do not have an end date set
enddate eq null
Textual Operators
domain with id 10
id eq 10
domain with id 10 and starting with example (matches e.g. example.com)
id eq 10 and name like "example%"
(domain with id 10 and schema "https") or domains that are not "blog.example.com"
(id eq 10 and schema eq "https") or name ne "blog.example.com"
results that have category "text" and a probability greater or equal 0.9
category eq "text" and probability ge 0.9
results that refer to files which are safe to delete
safetodelete eq "true"
results that last occurred on or before 2015-07-01 00:00:00
lastdate le "2015-07-01 00:00:00"
domains that do not have the bundle identifier a39649ff-ddb5-47ce-8b97-9758961534b1
not (bundle eq "a39649ff-ddb5-47ce-8b97-9758961534b1")
bundles that do not have an end date set
enddate eq null