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 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
mail 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//notification of the API.

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
Still need help? Get in touch!
Last updated on 23rd Aug 2022