ADVANCED QUERY FILTER

Vulnerabilities

q= Filter

Query Filter (q=) is used to select the exact data set you would like the API to return. The filter works similar to a database query, where you can specify fields & operators - these help to narrow down the results to the data you would need. This filter is only supported for selected API endpoints. Please check the documentation for each endpoint for more details.

Examples for querying vulnerabilities:

Example 1 - Critical or High vulnerabilities only:

curl -G -X GET 'https://localhost:3000/api/ss/vulnerabilities' --data-urlencode 'q_vulnerability={ priority: { $in: ["Critical", "High" ] } }' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Example 2 - Open Critical or Open High vulnerabilities only:

curl -G -X GET 'https://localhost:3000/api/ss/vulnerabilities' --data-urlencode 'q_vulnerability={ $and: [ { priority: { $in: [ "Critical", "High" ] } }, { status: { $eq: "Open" } } ] }' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Example 3 - Critical or High Ready for Retest vulnerabilities only:

curl -G -X GET 'https://localhost:3000/api/ss/vulnerabilities' --data-urlencode 'q_vulnerability={ $and: [ { priority: { $in: [ "Critical", "High" ] } }, { is_retest: { $eq: "Yes" } } ] }' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Example 4 - Critical or High vulnerabilities discovered in last 24 hours:

curl -G -X GET 'https://localhost:3000/api/ss/vulnerabilities' --data-urlencode 'q_vulnerability={ $and: [ { priority: { $in: [ "Critical" ] } }, { status: { $eq: "Open" } }, { created: { $gte: datetime("now", "-1 days") } } ] }' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Examples for querying writeups:

Example 5 - Writeups with title SQL Injection:

curl -G -X GET 'https://localhost:3000/api/ss/library' --data-urlencode 'q={title: { $eq: "SQL Injection" }}' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Example 6 - Writeups with the tag pluginID:53360:

curl -G -X GET 'https://localhost:3000/api/ss/library' --data-urlencode 'q={tags: { $in: "pluginID:53360" }}' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Example 7 - Writeups with the custom field NessusID and value 53360:

curl -G -X GET 'https://localhost:3000/api/ss/library' --data-urlencode 'q={custom_fields: { $elemMatch: { name: { $eq: "NessusID" }, value: { $eq: "53360" } } }' -H 'Host: localhost:3000' -H 'X-SSAPI-KEY: ********' -H 'Content-Type: application/json' -H 'Connection: close'

Operators

Query Filter supports the following operators:

$and

Can be used to AND two or more conditions.

Example: Filter vulnerabilities which are Open and Critical

$and: [
    {
        status: { $eq: "Open" }
    },
    {
        priority: { $eq: "Critical" }
    }
]

$or

Can be used to OR two or more conditions.

Example: Filter vulnerabilities which are Critical or High

$or: [
    {
        priority: { $eq: "Critical" }
    },
    {
        priority: { $eq: "High" }
    }
]

$eq

Used to check that a field is equal to a value. A value can be a string, boolean, number, null or a function.

Example: Filter vulnerabilities which are Critical

    {
        priority: { $eq: "Critical" }
    }

$ne

Used to check that a field is not equal to a value. A value can be a string, boolean, number, null or a function.

Example: Filter vulnerabilities which are not Informational

    {
        priority: { $ne: "Info" }
    }

$in

Used to check that a value exists in a list. Supports an array of values.

Example: Filter vulnerabilities which have a tag 'OWASP Top 10' (Top 10 Vulnerability)

    {
        tags: { $in: ["OWASP Top 10"] }
    }

$nin

Used to check that a value does not exist in a list. Supports an array of values.

Example: Filter vulnerabilities which do not have a tag 'OWASP Top 10' (Not a Top 10 Vulnerability)

    {
        tags: { $nin: ["OWASP Top 10"] }
    }

$gt

Used to check that a field is greater than a value. Supports strings, numbers and functions.

Example: Filter vulnerabilities which have a likelihood of exploitation greater than 7

    {
        likelihood_of_exploitation: { $gt: 7 }
    }

$gte

Used to check that a field is greater than or equal to a value. Supports strings, numbers and functions.

Example: Filter vulnerabilities which have a likelihood of exploitation greater than or equal to 7

    {
        likelihood_of_exploitation: { $gte: 7 }
    }

$lt

Used to check that a field is less than a value. Supports strings, numbers and functions.

Example: Filter vulnerabilities which have a likelihood of exploitation less than 7

    {
        likelihood_of_exploitation: { $lt: 7 }
    }

$lte

Used to check that a field is less than or equal to a value. Supports strings, numbers and functions.

Example: Filter vulnerabilities which have a likelihood of exploitation less than or equal to 7

    {
        likelihood_of_exploitation: { $lte: 7 }
    }

$regex

Used to perform a regular expression for a field. Support Javascript regular expressions.

Example: Filter vulnerabilities which have SQL in the title, using a case insensitive search.

    {
        title: { $regex: /SQL/i }
    }

$elemMatch

This operator matches documents that contain an array field with at least one element that matches all the specified query criteria.

Example: Filter vulnerabilities by a specific custom field name and value.

    {
        custom_fields: { $elemMatch: { name: { $eq: "is_pci" }, value: { $eq: "Yes" } } }
    }

$all

This operator selects the documents where the value of a field is an array that contains all the specified elements.

Example: Filter vulnerabilities which both CWE-520 and Web App in the tags.

    {
        tags: { $all: ["CWE-520", "Web App"] }
    }

Functions

The following functions are currently supported:

• datetime()

datetime(timeValue, modifiers)

datetime can be used to construct a date & time and then modify it (if needed).

• timeValue - must be either:

  • now

  • YYYY-MM-DD

  • YYYY-MM-DD HH:MM

• modifiers - must be either:

  • +999 years

  • -999 years

  • +999 months

  • -999 months

  • +999 days

  • -999 days

  • +999 hours

  • -999 hours

  • +999 minutes

  • -999 minutes

  • start of year

  • start of month

  • start of day

Example 1: Filter vulnerabilities created greater than June 1st, 2022.

    {
        created: { $gt: datetime("2022-06-01") }
    }

Example 2: Filter vulnerabilities created greater than UTC 12:00 on June 1st, 2022.

    {
        created: { $gt: datetime("2022-06-01 12:00") }
    }

Example 3: Filter vulnerabilities created greater than 7 days ago.

    {
        created: { $gt: datetime("now", "-7 days") }
    }

Example 4: Filter vulnerabilities with SLA greater than 7 days from now.

    {
        sla: { $gt: datetime("now", "+7 days") }
    }

Example 5: Filter vulnerabilities with SLA greater than 7 days + 1 year from now. Multiple modifiers will execute in order i.e. add 7 days, then add 1 year.

    {
        sla: { $gt: datetime("now", "+7 days", "+1 year") }
    }

Vulnerability Fields

The following fields are supported in filters for the 'Vulnerability' type:

id

The id for the vulnerability.

Example: get vulnerability with id 62a190f7793b8ccd085e0d9d

    {
        id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") }
    }

alternate_id

The alternate id for the vulnerability (set by the vulnerability code on the project).

Example: get vulnerability with alternate id GLOBEX-1

    {
        alternate_id: { $eq: "GLOBEX-1" }
    }

created

The created date for the vulnerability.

Example: get vulnerabilities which have been created in the past 7 days.

    {
        created: { $gte: datetime("now", "-7 days") }
    }

modified

The modified date for the vulnerability.

Example: get vulnerabilities which have been modified in the past 7 days.

    {
        modified: { $gte: datetime("now", "-7 days") }
    }

priority

The priority for the vulnerability. Supports Critical, High, Medium, Low & Info.

Example: get vulnerabilities which are Critical.

    {
        priority: { $eq: "Critical" }
    }

title

The title for the vulnerability.

Example: get vulnerabilities which have SQL in the title.

    {
        title: { $regex: /SQL/i }
    }

zero_day

Whether the vulnerability is a zero day or not. Supports Yes or No.

Example: get vulnerabilities which are a zero day.

    {
        zero_day: { $eq: "Yes" }
    }

likelihood_of_exploitation

The likelihood of exploitation for a vulnerability. Supports 1, 2, 3, 4, 5, 6, 7, 8, 9, 10.

Example: get vulnerabilities which have a likelihood of exploitation greater than or equal to 7.

    {
        likelihood_of_exploitation: { $gte: 7 }
    }

status

The status for the vulnerability. Supports Open or Closed.

Example: get all open vulnerabilities.

    {
        status: { $eq: "Open" }
    }

status_updated

The date when the status was last updated for the vulnerability.

Example: get vulnerabilities which have had their status change in the past 7 days.

    {
        status_updated: { $gte: datetime("now", "-7 days") }
    }

is_retest

Whether the vulnerability is flagged for retesting or not. Supports Yes or No.

Example: get vulnerabilities which are currently flagged for retesting.

    {
        is_retest: { $eq: "Yes" }
    }

sla

The SLA date for the vulnerability.

Example: get open vulnerabilities which have exceeded/breached their assigned SLA by 7 days.

$and: [
    {
        status: { $eq: "Open" }
    },    
    {
        sla: { $lte: datetime("now", "-7 days") }
    }
]

target_remediation_date

The target remediation date for the vulnerability.

Example: get open vulnerabilities which have target remediation date exactly 7 days from now.

$and: [
    {
        status: { $eq: "Open" }
    },    
    {
        target_remediation_date: { $lte: datetime("now", "+7 days") }
    },
    {
        target_remediation_date: { $gte: datetime("now", "+6 days") }
    }
]

release_date

The release date for the vulnerability.

Example: get vulnerabilities which have been released in the past 7 days.

    {
        release_date: { $gte: datetime("now", "-7 days") }
    }

tags

The tags for the vulnerabilities.

Example: get vulnerabilities which have a tag "OWASP Top 10".

    {
        tags: { $in: ["OWASP Top 10"] }
    }

custom_tags

The custom tags for the vulnerabilities.

Example: get vulnerabilities which have a custom tag "is_pci" and value "Yes".

    {
        custom_tags: { 
            $elemMatch: { 
                name: { $eq: "is_pci" },
                value: { $eq: "Yes" }
            }
        }
    }

custom_fields

The custom fields for the vulnerabilities.

Example: get vulnerabilities which have a custom field "qa_passed" and value "Yes".

    {       
        custom_fields: { 
            $elemMatch: { 
                name: { $eq: "qa_passed" },
                value: { $eq: "Yes" }
            }
        }
    }

Vulnerability Library (Writeup) Fields

The following fields are supported in filters for the 'Vulnerability Library' or 'Writeup' type:

id

The id for the vulnerability library writeup.

Example: get writeup with id 62a190f7793b8ccd085e0d9d

    {
        id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") }
    }

created

The created date for the vulnerability library writeup.

Example: get writeups which have been created in the past 7 days.

    {
        created: { $gte: datetime("now", "-7 days") }
    }

modified

The modified date for the vulnerability library writeup.

Example: get writeups which have been modified in the past 7 days.

    {
        modified: { $gte: datetime("now", "-7 days") }
    }

priority

The priority for the writeup. Supports Critical, High, Medium, Low & Info.

Example: get writeups which are Critical.

    {
        priority: { $eq: "Critical" }
    }

title

The title for the writeup.

Example: get writeups which have SQL in the title.

    {
        title: { $regex: /SQL/i }
    }

description

Description of writeup.

Example: get writeups which have SQL in the description.

    {
        description: { $regex: /SQL/i }
    }

attack_scenario

Attack Scenario for writeup.

Example: get writeups which have SQL in the attack scenario.

    {
        attack_scenario: { $regex: /SQL/i }
    }

remediation_recommendation

Remediation recommendation for writeup.

Example: get writeups which have SQL in the recommendation.

    {
        remediation_recommendation: { $regex: /SQL/i }
    }

severity

The severity for the writeup. Supports 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Example: get writeups which have a severity greater than or equal to 7.

    {
        severity: { $gte: 7 }
    }

likelihood_of_exploitation

The likelihood of exploitation for a vulnerability. Supports 1, 2, 3, 4, 5, 6, 7, 8, 9, 10.

Example: get vulnerabilities which have a likelihood of exploitation greater than or equal to 7.

    {
        likelihood_of_exploitation: { $gte: 7 }
    }

category

The category for the vulnerability.

Example: get all writeups with category Web App

    {
        category: { $eq: "Web App" }
    }

impact_on_confidentiality

The confidentiality rating for the writeup.

Example: get all writeups with confidentiality rating of High

    {
        impact_on_confidentiality: { $in: ["High"] }
    }

impact_on_integrity

The integrity rating for the writeup.

Example: get all writeups with integrity rating of High

    {
        impact_on_integrity: { $in: ["High"] }
    }

impact_on_availability

The availability rating for the writeup.

Example: get all writeups with availability rating of High

    {
        impact_on_availability: { $in: ["High"] }
    }

import_source

The import source for the writeups.

Example: get writeups which have an import source of Nessus

    {
        import_source: { $eq: "Nessus" }
    }

import_source_id

The import source id for the writeups.

Example: get writeups which have an import source id of 53360

    {
        import_source_id: { $eq: "53360" }
    }

tags

The tags for the writeups.

Example: get writeups which have a tag pluginID:53360

    {
        tags: { $in: ["pluginID:53360"] }
    }

custom_tags

The custom tags for the writeups.

Example: get writeups which have a custom tag "is_pci" and value "Yes".

    {
        custom_tags: { 
            $elemMatch: { 
                name: { $eq: "is_pci" },
                value: { $eq: "Yes" }
            }
        }
    }

custom_fields

The custom fields for the writeups.

Example: get writeups which have a custom field "NessusID" and value "53360".

    {
        custom_fields: { 
            $elemMatch: { 
                name: { $eq: "NessusID" },
                value: { $eq: "53360" }
            }
        }
    }

Project Fields

The following fields are supported in filters for the 'Project' type:

id

The id for the project.

Example: get project with id 62a190f7793b8ccd085e0d9d

    {
        id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") }
    }

created

The created date for the project.

Example: get projects which have been created in the past 7 days.

    {
        created: { $gte: datetime("now", "-7 days") }
    }

modified

The modified date for the project.

Example: get projects which have been modified in the past 7 days.

    {
        modified: { $gte: datetime("now", "-7 days") }
    }

name

The name of the project.

Example: get projects with the name "ACME Corp".

    {
        name: { $eq: "ACME Corp" }
    }

code

The code for the project.

Example: get projects which have "9999" in the code.

    {
        code: { $regex: /9999/ }
    }

start_date

The start date for the project.

Example: get projects which have a start date in the past 7 days. NOTE: You must specify "isostring" at the end for this field.

    {
        start_date: { $gte: datetime("now", "-7 days", "isostring") }
    }

end_date

The end date for the project.

Example: get projects which have a end date in the past 7 days. NOTE: You must specify "isostring" at the end for this field.

    {
        end_date: { $gte: datetime("now", "-7 days", "isostring") }
    }

group_names

Group names associated to the project.

Example: get projects with the group "ACME Developers" associated.

    {
        groups_names: { $in: ["ACME Developers"] }
    }

status

Status of the project. Must be either "Waiting to Start", "Testing", "On-Hold", "Overrun", "Retest", "Completed".

Example: get Completed projects.

    {
        status: { $eq: "Completed" }
    }

org_code

Organization code for the project.

Example: get projects with "ACME1" in the org code.

    {
        org_code: { $regex: /ACME1/i }
    }

vuln_code

The vulnerability code for the project.

Example: get projects which have a vulnerability code of "ACME18".

    {
        vuln_code: { $eq: "ACME18" }
    }

custom_tags

The custom tags for the project.

Example: get projects which have a custom tag "is_pci" and value "Yes".

    {
        custom_tags: { 
            $elemMatch: { 
                name: { $eq: "is_pci" },
                value: { $eq: "Yes" }
            }
        }
    }

custom_fields

The custom fields for the project.

Example: get projects which have a custom field "exported_to_jira" and value "No".

    {
        custom_fields: { 
            $elemMatch: { 
                name: { $eq: "exported_to_jira" },
                value: { $eq: "No" }
            }
        }
    }

Asset Fields

The following fields are supported in filters for the 'Asset' type:

id

The id for the asset.

Example: get asset with id 62a190f7793b8ccd085e0d9d

    {
        id: { $eq: ObjectId("62a190f7793b8ccd085e0d9d") }
    }

created

The created date for the asset.

Example: get assets which have been created in the past 7 days.

    {
        created: { $gte: datetime("now", "-7 days") }
    }

modified

The modified date for the asset.

Example: get assets which have been modified in the past 7 days.

    {
        modified: { $gte: datetime("now", "-7 days") }
    }

name

The name of the asset.

Example: get assets with the name "ACME Corp".

    {
        name: { $eq: "ACME Corp" }
    }

type

The type of the asset.

Example: get assets with the type "Web App".

    {
        type: { $eq: "Web App" }
    }

details

The details of the asset.

Example: get assets with "Used for XYZ" in the details.

    {
        details: { $regex: /Used for XYZ/i }
    }

external_id

The external Id of the asset.

Example: get assets with the external Id "SNOW-123".

    {
        external_id: { $eq: "ACME Corp" }
    }

asset_library_keys

A list of asset library keys. Use this to query assets in libraries.

You can retrieve the key for a asset library from the URL when viewing the asset library.

Example: get assets in a library with the library key "662f1bafcdd044fcc3e4e28d".

    {
        asset_library_keys: { 
            $in: [
                ObjectId("662f1bafcdd044fcc3e4e28d")
            ] 
        }
    }

custom_fields

The custom fields for the asset.

Example: get assets which have a custom field "from_cmdb" and value "SNOW".

    {
        custom_fields: { 
            $elemMatch: { 
                name: { $eq: "from_cmdb" },
                value: { $eq: "SNOW" }
            }
        }
    }