Using the Search Grammar with the API

This article reviews how to use the search grammar through Secureworks® Taegis™ VDR’s public API.

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

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 VDR indexes.

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

Boolean Keywords ⫘

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

Example ⫘

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"
        }
      }
    ]
  }
}

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 ⫘

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 ids.*
edge	{"edge": {"id": 12}}	Filter by edge-service id, 0 is public internet. Supports a single entry or a list of ids.*
fingerprint	{"fingerprint": {"value": "ACD"}} or {"fingerprint": {"value": "ACD", "type: "ssl"}}	Filter by fingerprint value or by value and fingerprint type. Available for servers asset type only.
global	{"global": {"text":"sql injection"}}	Filter by text. If a word sequence is provided, all the words are required in the specified order.
id	{"id": {"match": "b4bc2f52-b8bd-4078-9a98-ac2806820620"}}	This filter will match the id(s) depending of the context. Supports a single entry or a list of ids.*
ip	{"ip": {"match": "192.168.10.0/24"}}	Filter by IP address. Accepts either a 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, hypervisor, webmail 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 ids.*
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 ids.*
team	{"team": {"id": 12}}	Filter by team id. Supports a single entry or a list of ids.*
user	{"user": {"id": 12}}	Filter by user id. Supports a single entry or a list of ids.*

* An 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. For example, if the response status operator is {"response_status": {"code": "200"}} it matches all entries where the status code is 200. A response operator of {"response_status": {"code": [ "200", "201", "202" ]}} matches all entries where the status code is 200 or 201 or 202.