Using the Search Grammar With the API

How to use the search grammar through Delve's public API.

When using Delve's public API, it is important to provide a search grammar to narrow down the results to what is really needed.

⚠️ Search grammar MUST be a valid JSON.

Grammar structure

Single operator case

The use of a single operator is done by simply calling the operator with its arguments

{"my_operator":{
// arguments
}}

 

Examples
Searching for text containing "XSS":

{"global":{
"text": "XSS"
}}

 

Searching per software:

{"software":{
"name": "nginx"
}}

 

Searching per tag:

{"tag":{
"id": "42"
}}

 

Advanced: Boolean operator

To compose a more complex query, use the bool operator. It will result in a Boolean search within the Delve indexes.

{"bool":{
"boolean_keyword":[
// operators
]
}}

 

Boolean keywords

  • must : list of operators that MUST be present in the search
  • must_not : list of operators that MUST be excluded in the search
  • should : list of operators that will be included in the search but not mandatory

Examples
Search parameters:

  • Containing "XSS" as text
  • On an Edge Service with id "6"
  • With an IP within 192.168.0.0/16
  • BUT not the CVE-2000-1001
{
"bool": {
"must": [
{
"global": {
"text": "XSS"
}
},
{
"edge": {
"id": 6
}
},
{
"ip": {
"match": "192.168.0.0/16"
}
}
],
"must_not": [
{
"cve": {
"number": "CVE-2000-1001"
}
}
]
}
}
✔️ It is possible to nest bool operator for more precise control over the result.

Example

Searching for (not a linux within 192.168.10.0/24) OR (with tag #12 without CVE-1234-1234):

{
"bool": {
"should": [
{
"bool": {
"must_not": [
{
"os": {
"name": "linux"
}
}
],
"must": [
{
"ip": {
"match": "192.168.10.0/24"
}
}
]
}
},
{
"bool": {
"must_not": [
{
"cve": {
"number": "CVE-1234-1234"
}
}
],
"must": [
{
"tag": {
"id": 12
}
}
]
}
}
]
}
}

Example

Searching for vulnerabilities first discovered after a certain date and last seen before a certain date.

{
"bool": {
"must": [
{
"first_discovery_date": {
"gt": "2020-01-01"
}
},
{
"last_seen_date": {
"lt": "2020-03-01"
}
},
{
"is": {
"flag": "vulnerability"
}
}
]
}
}

Operators

✔️  If an operator is not available in a given context, the API will respond with an error 400 : Invalid input data provided.
Operator Arguments sample Description
authentication
{"authentication": {"status": "ok"}}

 

Filter asset by authentication status.
Status accepts: ok, failed, unused or insufficient_privilege.
content_type
{"content_type": {"mimetype": "text/json"}}
Filter by response content type.
Mimetype accepts any valid MIME type.
Supports a single entry or a list of mimetype*.
creation_type
{"creation_type": {"name": "discovered_host"}}
Filter assets by creation type.
Name accepts: discovered_host, discovered_hidden_vhost or manually_added.
cve
{"cve": {"number": "CVE-1234-1234"}}
Filter by CVE numbers.
Matches the exact CVE number.
Supports a single entry or a list of CVE numbers*.
cvss
{"cvss": {"value": 7.5}}
must_not: [{cvss: {compare: "GTE", value: "7"}}]
Filter by CVSS value.
Accepts comparison symbols: <=, <, >= or >.
discovery
{"discovery": {"id": 999}}
Filter by discovery id.
Supports a single entry or a list of id*.
edge
{"edge": {"id": 12}}

Filter by edge-service id,

0 is public internet.

Supports a single entry or a list of id*.

global
{"global": {"text":"sql injection"}}

Filter by text.
If a word sequence is provided, all the words will be required in the specified order.

id
{"id": {"match": "b4bc2f52-b8bd-4078-9a98-ac2806820620"}}

This filter will match the id(s) depending of the context.
Support a single entry or a list of id*.

ip
{"ip": {"match": "192.168.10.0/24"}}

Filter by IP address.
Accepting either full IP address or IP address range.

note
{"note": {"content": "content to search for in the note"}}

Filter by note content.

os
{"os": {"name": "linux"}}

Filter by OS name.

port
{"port": {
"number": 22,
"protocol": "tcp",
"state": "filtered",
"banner": "debian",
"service" : "ssh"
}}

Filter by port specification. All fields are optional.

When multiple fields are specified, they must all match the same entry.

  • banner performs term and ngram lookups.
  • number must be an integer.
  • protocol accepts: tcp or udp.
  • state accepts: open, filtered, unfiltered or closed.
  • service matches the confirmed services.
recognized_response
{"recognized_response": {"type": "webmail"}}

Filter by recognized response. Type accepts:  default_vhost, hypervisorwebmail or vpn_firewall

Supports a single entry or a list of recognized responses*

related_asset
{"related_asset": {"id": 12}}

Filter by related asset id.
Supports a single entry or a list of id*

response_status
{"response_status": {"code": "200"}}

Filter by HTTP response status code. Supports a single entry or a list of status codes*

scan
{"scan": {"id": 42}}

Filter by scan id (reports and scan ids are the same)

scheme
{"scheme": {"name": "http"}}

Filter by scheme. Only accepts http or https. Supports a single entry or a list of schemes*

score
{"score": {"value": 10.00}}
{score: {compare: "GTE", value: "9.80"}

Filter by score value.

severity
{"severity": {"level": "medium"}}

Filter by severity level. Level accepts: critical, medium, warning or info

software
{"software": {"name": "nginx", "version": "1.0.0.0"}}

Filter by software. Version is optional.

tag
{"tag": {"id": 12}}

Filter by tag id. Supports a single entry or a list of id*

team
{"team": {"id": 12}}

Filter by team id. Supports a single entry or a list of id*

user
{"user": {"id": 12}}

Filtre by user id. Supports a single entry or a list of id*

* Operator supporting "single entry or a list of" entities means that it is possible to pass either a single entry or a list with all the possible matches. Here is an example with the response status operator: {"response_status": {"code": "200"}} that will match all entries where the status code is 200 ; where {"response_status": {"code": [ "200", "201", "202" ]}} will match all entries where the status code is 200 or 201 or 202.