Using the Spotlight Vulnerabilities service collection
This service collection has code examples posted to the repository.
Table of Contents
Operation ID | Description | ||||
---|---|---|---|---|---|
| Search for Vulnerabilities in your environment by providing a FQL filter and paging details. Returns a set of Vulnerability entities which match the filter criteria. | ||||
| Get details on remediation by providing one or more IDs. | ||||
| Get details on vulnerabilities by providing one or more IDs. | ||||
| Search for Vulnerabilities in your environment by providing a FQL filter and paging details. Returns a set of Vulnerability IDs which match the filter criteria. |
Passing credentials
WARNING
client_id
andclient_secret
are keyword arguments that contain your CrowdStrike API credentials. Please note that all examples below do not hard code these values. (These values are ingested as strings.)CrowdStrike does not recommend hard coding API credentials or customer identifiers within source code.
combinedQueryVulnerabilities
Search for Vulnerabilities in your environment by providing a FQL filter and paging details. Returns a set of Vulnerability entities which match the filter criteria.
PEP8 method name
query_vulnerabilities_combined
Endpoint
Method | Route |
---|---|
/spotlight/combined/vulnerabilities/v1 |
Content-Type
- Consumes: application/json
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
after | query | string | A pagination token used with the limit parameter to manage pagination of results. On your first request, don't provide an after token. On subsequent requests, provide the after token from the previous response to continue from that place in the results. To access more than 10k indicators, use the after parameter instead of offset . | ||
facet | query | string | Select various detail blocks to be returned for each vulnerability. Supported values:
| ||
filter | query | string | FQL Syntax formatted filter that should be used to limit the results. Wildcards * are unsupported.You must provide a filter, either via this keyword or as part of a parameters payload in order to use this method. Review the available filters table below for more detail. | ||
limit | query | integer | Maximum number of results to return. (Max: 5000, Default: 100) | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. | ||
sort | query | string | FQL Syntax formatted sort filter. Common sort options include:
|
Available filters
Name | Description |
---|---|
aid | The unique agent identifier (agent ID) of a sensor. Get all vulnerabilities for a specific agent ID: filter=aid:'abcde6b9a3427d8c4a1af416424d6231' |
apps_remediation | The unique identifier of a remediation. This filter supports multiple values and negation. Get the vulnerability ID for a specific remediation ID: filter=apps_remediation:['7bba2e543744a92962be7afeb6484858'] Get vulnerabilities for specified remediation IDs: filter=apps_remediation.ids:['ID1','ID2','ID3'] |
closed_timestamp | The date and time a vulnerability was set to a status of “closed.” Get vulnerabilities that were marked as closed after June 25, 2021 at 10:32 UTC: filter=closed_timestamp:>'2021-06-25T10:32' Get vulnerabilities that were marked as closed before October 18, 2021: filter=closed_timestamp:<'2021-10-18' |
created_timestamp | The date and time when a vulnerability was created in Spotlight. Workflow tip: Use this filter to get only the vulnerabilities created after the timestamp you last pulled data on. Get vulnerabilities created before September 30, 2021 at 13:22 UTC: filter=created_timestamp:<'2021-09-25T13:22' Get vulnerabilities created after February 12, 2021: filter=created_timestamp:>'2021-02-12' |
cve.exploit_status | Numeric value of the most severe known exploit. This filter supports multiple values and negation. Possible values:
filter=cve.exploit_status:'60' Get vulnerabilities with an exploit status of 30, 60, or 90: filter=cve.exploit_status:!'0' OR filter=cve.exploit_status:['30','60','90'] |
cve.exprt_rating | The ExPRT rating assigned by CrowdStrike's predictive AI rating system. The value must be entered in all caps. This filter supports multiple values and negation. Possible values:
filter=cve.exprt_rating:'HIGH' Get vulnerabilities with an ExPRT rating of HIGH or CRITICAL: filter=cve.exprt_rating:['HIGH','CRITICAL'] Get vulnerabilities with any ExPRT rating other than UNKNOWN: filter=cve.exprt_rating:!'UNKNOWN' |
cve.id | A unique identifier for a vulnerability as cataloged in the National Vulnerability Database (NVD). This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities with a specific single CVE ID: filter=cve.id:['CVE-2022-1234'] Get vulnerabilities for multiple CVE IDs: filter=cve.id:['CVE-2022-1234','CVE-2023-1234'] Get vulnerabilities that do not contain either of 2 specific CVE IDs: filter=cve.id:!['CVE-2022-1234','CVE-2023-1234'] |
cve.severity | The CVSS severity rating of the vulnerability. The value must be entered in all caps. This filter supports multiple values and negation. Possible values:
filter=cve.severity:'LOW' Get vulnerabilities with any CVE severity but UNKNOWN: filter=cve.severity:!'UNKNOWN' Get all vulnerabilities with a CVE severity of LOW and MEDIUM: filter=cve.severity:['LOW','MEDIUM'] |
host_info.groups | The unique system-assigned ID of a host group. Retrieve the host group ID from Host Group APIs; see Host and Host Group Management APIs. This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities on hosts in a specific host group ID: filter=host_info.groups:['03f0b54af2692e99c4cec945818fbef7'] Get vulnerabilities on hosts in all host groups except a specific host group ID: filter=host_info.groups:!['03f0b54af2692e99c4cec945818fbef7'] Get vulnerabilities on hosts in multiple host group IDs: filter=host_info.groups:['03f0b54af2692e99c4cec945818fbef7','1676624bb307f5054406a3c343d40212'] |
host_info.platform_name | The operating system platform. This filter supports negation. Possible values:
filter=host_info.platform_name:'Windows' OR filter=host_info.platform_name:!'Linux' |
host_info.product_type_desc | The type of host a sensor is running on. This filter supports multiple values and negation. Enter values as shown with the first letter capitalized. Possible values:
filter=host_info.product_type_desc:'Workstation' Get vulnerabilities on Server and Domain Controller hosts (non-Workstation hosts): filter=host_info.product_type_desc:!'Workstation' OR filter=host_info.product_type_desc:['Workstation','Server'] |
host_info.tags | The name of a tag assigned to a host. Retrieve tags from Host Tags APIs; see Host and Host Group Management APIs. This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities on hosts tagged with “ephemeral”: filter=host_info.tags:['ephemeral'] Get vulnerabilities on hosts with any tag but “search” or “ephemeral”: host_info.tags:!['search','ephemeral'] Get vulnerabilities on hosts tagged with “spotlight” and “main”: filter=host_info.tags:['spotlight','main'] |
last_seen_within | Filter for vulnerabilities based on the number of days since a host last connected to Falcon. Enter a numeric value from 3 to 45 to indicate the number of days you want to look back. All active hosts seen up to the specified number of days are returned with a host_last_seen_timestamp response field populated as follows:
filter=last_seen_within:'10' The host_last_seen_timestamp in the response shows:
|
status | The status of a vulnerability. The value must be entered in all lowercase letters. This filter supports multiple values and negation. Possible values:
filter=status:'open' Get vulnerabilities with any status except closed: filter=status:!'closed' Get vulnerabilities with a status of open or reopen: filter=status:['open','reopen'] ORfilter=status:!['closed'] |
updated_timestamp | The UTC date and time of the last update made on a vulnerability. Get vulnerabilities that were last updated before October 20, 2021 at 10:36 PM UTC: filter=updated_timestamp:<'2021-10-20T22:36' Get vulnerabilities that were last updated after September 15, 2021: filter=updated_timestamp:>'2021-09-15' |
Usage
You must provide a value for filter to make use of this operation, either by using the filter
keyword or as part of your parameters
payload.
Service class example (PEP8 syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_vulnerabilities_combined(filter="string",
facet="string",
limit=integer,
sort="string",
after="string"
)
print(response)
Service class example (Operation ID syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.combinedQueryVulnerabilities(filter="string",
facet="string",
limit=integer,
sort="string",
after="string"
)
print(response)
Uber class example
from falconpy import APIHarnessV2
# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.command("combinedQueryVulnerabilities",
filter="string",
facet="string",
limit=integer,
sort="string",
after="string"
)
print(response)
getRemediationsV2
Get details on remediation by providing one or more IDs
PEP8 method name
get_remediations_v2
Endpoint
Method | Route |
---|---|
/spotlight/entities/remediations/v2 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | One or more remediation IDs. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.get_remediations_v2(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.getRemediationsV2(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarnessV2
# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.command("getRemediationsV2", ids=id_list)
print(response)
getVulnerabilities
Get details on vulnerabilities by providing one or more IDs
PEP8 method name
get_vulnerabilities
Endpoint
Method | Route |
---|---|
/spotlight/entities/vulnerabilities/v2 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | One or more vulnerability IDs (max: 400). Find vulnerability IDs with queryVulnerabilities. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.get_vulnerabilities(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.getVulnerabilities(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarnessV2
# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.command("getVulnerabilities", ids=id_list)
print(response)
queryVulnerabilities
Search for Vulnerabilities in your environment by providing a FQL filter and paging details. Returns a set of Vulnerability IDs which match the filter criteria
PEP8 method name
query_vulnerabilities
Endpoint
Method | Route |
---|---|
/spotlight/queries/vulnerabilities/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
after | query | string | A pagination token used with the limit parameter to manage pagination of results. On your first request, don't provide an after token. On subsequent requests, provide the after token from the previous response to continue from that place in the results. | ||
limit | query | integer | The number of items to return in this response (default: 100, max: 400). Use with the after parameter to manage pagination of results. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. | ||
sort | query | string | Sort vulnerabilities by their properties. Common sort options include:
| ||
filter | query | string | Filter items using a query in Falcon Query Language (FQL). Wildcards * are unsupported. Common filter options include:
parameters payload in order to use this method. Review the available filters table below for more detail. |
Available filters
Name | Description |
---|---|
aid | The unique agent identifier (agent ID) of a sensor. Get all vulnerabilities for a specific agent ID: filter=aid:'abcde6b9a3427d8c4a1af416424d6231' |
apps_remediation | The unique identifier of a remediation. This filter supports multiple values and negation. Get the vulnerability ID for a specific remediation ID: filter=apps_remediation:['7bba2e543744a92962be7afeb6484858'] Get vulnerabilities for specified remediation IDs: filter=apps_remediation.ids:['ID1','ID2','ID3'] |
closed_timestamp | The date and time a vulnerability was set to a status of “closed.” Get vulnerabilities that were marked as closed after June 25, 2021 at 10:32 UTC: filter=closed_timestamp:>'2021-06-25T10:32' Get vulnerabilities that were marked as closed before October 18, 2021: filter=closed_timestamp:<'2021-10-18' |
created_timestamp | The date and time when a vulnerability was created in Spotlight. Workflow tip: Use this filter to get only the vulnerabilities created after the timestamp you last pulled data on. Get vulnerabilities created before September 30, 2021 at 13:22 UTC: filter=created_timestamp:<'2021-09-25T13:22' Get vulnerabilities created after February 12, 2021: filter=created_timestamp:>'2021-02-12' |
cve.exploit_status | Numeric value of the most severe known exploit. This filter supports multiple values and negation. Possible values:
filter=cve.exploit_status:'60' Get vulnerabilities with an exploit status of 30, 60, or 90: filter=cve.exploit_status:!'0' OR filter=cve.exploit_status:['30','60','90'] |
cve.exprt_rating | The ExPRT rating assigned by CrowdStrike's predictive AI rating system. The value must be entered in all caps. This filter supports multiple values and negation. Possible values:
filter=cve.exprt_rating:'HIGH' Get vulnerabilities with an ExPRT rating of HIGH or CRITICAL: filter=cve.exprt_rating:['HIGH','CRITICAL'] Get vulnerabilities with any ExPRT rating other than UNKNOWN: filter=cve.exprt_rating:!'UNKNOWN' |
cve.id | A unique identifier for a vulnerability as cataloged in the National Vulnerability Database (NVD). This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities with a specific single CVE ID: filter=cve.id:['CVE-2022-1234'] Get vulnerabilities for multiple CVE IDs: filter=cve.id:['CVE-2022-1234','CVE-2023-1234'] Get vulnerabilities that do not contain either of 2 specific CVE IDs: filter=cve.id:!['CVE-2022-1234','CVE-2023-1234'] |
cve.severity | The CVSS severity rating of the vulnerability. The value must be entered in all caps. This filter supports multiple values and negation. Possible values:
filter=cve.severity:'LOW' Get vulnerabilities with any CVE severity but UNKNOWN: filter=cve.severity:!'UNKNOWN' Get all vulnerabilities with a CVE severity of LOW and MEDIUM: filter=cve.severity:['LOW','MEDIUM'] |
host_info.groups | The unique system-assigned ID of a host group. Retrieve the host group ID from Host Group APIs; see Host and Host Group Management APIs. This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities on hosts in a specific host group ID: filter=host_info.groups:['03f0b54af2692e99c4cec945818fbef7'] Get vulnerabilities on hosts in all host groups except a specific host group ID: filter=host_info.groups:!['03f0b54af2692e99c4cec945818fbef7'] Get vulnerabilities on hosts in multiple host group IDs: filter=host_info.groups:['03f0b54af2692e99c4cec945818fbef7','1676624bb307f5054406a3c343d40212'] |
host_info.platform_name | The operating system platform. This filter supports negation. Possible values:
filter=host_info.platform_name:'Windows' OR filter=host_info.platform_name:!'Linux' |
host_info.product_type_desc | The type of host a sensor is running on. This filter supports multiple values and negation. Enter values as shown with the first letter capitalized. Possible values:
filter=host_info.product_type_desc:'Workstation' Get vulnerabilities on Server and Domain Controller hosts (non-Workstation hosts): filter=host_info.product_type_desc:!'Workstation' OR filter=host_info.product_type_desc:['Workstation','Server'] |
host_info.tags | The name of a tag assigned to a host. Retrieve tags from Host Tags APIs; see Host and Host Group Management APIs. This filter supports multiple values and negation. Note: All values must be enclosed in brackets, including single values. Get vulnerabilities on hosts tagged with “ephemeral”: filter=host_info.tags:['ephemeral'] Get vulnerabilities on hosts with any tag but “search” or “ephemeral”: host_info.tags:!['search','ephemeral'] Get vulnerabilities on hosts tagged with “spotlight” and “main”: filter=host_info.tags:['spotlight','main'] |
last_seen_within | Filter for vulnerabilities based on the number of days since a host last connected to Falcon. Enter a numeric value from 3 to 45 to indicate the number of days you want to look back. All active hosts seen up to the specified number of days are returned with a host_last_seen_timestamp response field populated as follows:
filter=last_seen_within:'10' The host_last_seen_timestamp in the response shows:
|
status | The status of a vulnerability. The value must be entered in all lowercase letters. This filter supports multiple values and negation. Possible values:
filter=status:'open' Get vulnerabilities with any status except closed: filter=status:!'closed' Get vulnerabilities with a status of open or reopen: filter=status:['open','reopen'] ORfilter=status:!['closed'] |
updated_timestamp | The UTC date and time of the last update made on a vulnerability. Get vulnerabilities that were last updated before October 20, 2021 at 10:36 PM UTC: filter=updated_timestamp:<'2021-10-20T22:36' Get vulnerabilities that were last updated after September 15, 2021: filter=updated_timestamp:>'2021-09-15' |
Usage
You must provide a value for filter to make use of this operation, either by using the filter
keyword or as part of your parameters
payload.
Service class example (PEP8 syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_vulnerabilities(after="string",
limit=integer,
sort="string",
filter="string"
)
print(response)
Service class example (Operation ID syntax)
from falconpy import SpotlightVulnerabilities
# Do not hardcode API credentials!
falcon = SpotlightVulnerabilities(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.queryVulnerabilities(after="string",
limit=integer,
sort="string",
filter="string"
)
print(response)
Uber class example
from falconpy import APIHarnessV2
# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.command("queryVulnerabilities",
after="string",
limit=integer,
sort="string",
filter="string"
)
print(response)