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.
Example 1 - Critical or High vulnerabilities only:
curl -G -X GET 'https://localhost:3000/api/ss/vulnerabilities' --data-urlencode 'q={ 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={ $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={ $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={ $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'
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.name: { $eq: "NessusID" }, custom_fields.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 }
    }
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: "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" }
    }
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") }
    }
custom_tags
The custom tags for the vulnerabilities.
Example: get vulnerabilities which have a custom tag 'is_pci' and value 'Yes'.
    {
        custom_tags.name: { $eq: "is_pci" },
        custom_tags.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.name: { $eq: "qa_passed" },
        custom_fields.value: { $eq: "Yes" }
    }
Vulnerability Library Fields
The following fields are supported in filters for the 'Vulnerability Library' type:
id
The id for the vulnerability library writeup.
Example: get writeup with id 62a190f7793b8ccd085e0d9d
    {
        id: { $eq: "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" }
    }
description
Description of writeup.
Example: get writeups which have SQL in the description.
    {
        description: { $regex: "SQL" }
    }
attack_scenario
Attack Scenario for writeup.
Example: get writeups which have SQL in the attack scenario.
    {
        attack_scenario: { $regex: "SQL" }
    }
remediation_recommendation
Remediation recommendation for writeup.
Example: get writeups which have SQL in the recommendation.
    {
        remediation_recommendation: { $regex: "SQL" }
    }
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.name: { $eq: "is_pci" },
        custom_tags.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.name: { $eq: "NessusID" },
        custom_fields.value: { $eq: "53360" }
    }
EXPORTING TO CSV
ActivateUser
Last modified 14d ago