Using the Falcon Intelligence Sandbox service collection
This service collection has code examples posted to the repository.
Table of Contents
Operation ID | Description | ||||
---|---|---|---|---|---|
| Download IOC packs, PCAP files, and other analysis artifacts. | ||||
| Get a short summary version of a sandbox report. | ||||
| Get a full sandbox report. | ||||
| Delete report based on the report ID. Operation can be checked for success by polling for the report ID on the report-summaries endpoint. | ||||
| Check the status of a sandbox analysis. Time required for analysis varies but is usually less than 15 minutes. | ||||
| Submit an uploaded file or a URL for sandbox analysis. Time required for analysis varies but is usually less than 15 minutes. | ||||
| Find sandbox reports by providing a FQL filter and paging details. Returns a set of report IDs that match your criteria. | ||||
| Find submission IDs for uploaded files by providing a FQL filter and paging details. Returns a set of submission IDs that match your criteria. | ||||
| Retrieves the file associated with the given ID (SHA256) | ||||
| Upload a file for sandbox analysis. After uploading, use /falconx/entities/submissions/v1 to start analyzing the file. | ||||
| Removes a sample, including file, meta and submissions from the collection | ||||
| Retrieves a list with sha256 of samples that exist and customer has rights to access them, maximum number of accepted items is 200 |
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.
GetArtifacts
Download IOC packs, PCAP files, and other analysis artifacts.
PEP8 method name
get_artifacts
Endpoint
Method | Route |
---|---|
/falconx/entities/artifacts/v1 |
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
headers | header | string | Format used to compress your downloaded file. Currently, you must provide the value gzip , the only valid format, as the Accept-Encoding header when using the Uber class. This keyword is not necessary when using the Service Class. | ||
id | query | string | ID of an artifact, such as an IOC pack, PCAP file, or actor image. Find an artifact ID in a report or summary. | ||
name | query | string | The name given to your downloaded file. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.get_artifacts(id="string", name="string")
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.GetArtifacts(id="string", name="string")
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
HEADERS = {
"Accept-Encoding": "gzip"
}
response = falcon.command("GetArtifacts", id="string", name="string", headers=HEADERS)
print(response)
GetSummaryReports
Get a short summary version of a sandbox report.
PEP8 method name
get_summary_reports
Endpoint
Method | Route |
---|---|
/falconx/entities/report-summaries/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | ID of a summary report. Find a summary report ID from the response when submitting a malware sample or search with query_reports . | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(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_summary_reports(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.GetSummaryReports(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(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("GetSummaryReports", ids=id_list)
print(response)
GetReports
Get a full sandbox report.
PEP8 method name
get_reports
Endpoint
Method | Route |
---|---|
/falconx/entities/reports/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | ID of a report. Find a report ID from the response when submitting a malware sample or search with query_reports . | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(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_reports(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.GetReports(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(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("GetReports", ids=id_list)
print(response)
DeleteReport
Delete report based on the report ID. Operation can be checked for success by polling for the report ID on the report-summaries endpoint.
PEP8 method name
delete_report
Endpoint
Method | Route |
---|---|
/falconx/entities/reports/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | ID of a report. Find a report ID from the response when submitting a malware sample or search with query_reports . | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.delete_report(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.DeleteReport(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(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("DeleteReport", ids=id_list)
print(response)
GetSubmissions
Check the status of a sandbox analysis. Time required for analysis varies but is usually less than 15 minutes.
PEP8 method name
get_submissions
Endpoint
Method | Route |
---|---|
/falconx/entities/submissions/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
ids | query | string or list of strings | ID of a submitted malware sample. Find a submission ID from the response when submitting a malware sample or search with query_submissions . | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(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_submissions(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.GetSubmissions(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(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("GetSubmissions", ids=id_list)
print(response)
Submit
Submit an uploaded file or a URL for sandbox analysis. Time required for analysis varies but is usually less than 15 minutes.
PEP8 method name
submit
Endpoint
Method | Route |
---|---|
/falconx/entities/submissions/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
action_script | body | string | Runtime script for sandbox analysis. Accepted values:
| ||
body | body | dictionary | Full body payload in JSON format. | ||
command_line | body | string | Command line script passed to the submitted file at runtime. Max length: 2048 characters | ||
document_password | body | string | Auto-filled for Adobe or Office files that prompt for a password. Max length: 32 characters | ||
enable_tor | body | boolean | Deprecated, please use network_settings instead. If true, sandbox analysis routes network traffic via TOR. | ||
environment_id | body | integer | Specifies the sandbox environment used for analysis. Accepted values:
| ||
network_settings | body | string | Specifies the sandbox network_settings used for analysis. Accepted values:
| ||
send_email_notification | body | boolean | Boolean indicating if an email notification should be sent. | ||
sha256 | body | string | ID of the sample, which is a SHA256 hash value. Find a sample ID from the response when uploading a malware sample or search with query_sample .The url keyword must be unset if this keyword is used. | ||
submit_name | body | string | Name of the malware sample that's used for file type detection and analysis. | ||
system_date | body | string | Set a custom date in the format yyyy-MM-dd for the sandbox environment. | ||
system_time | body | string | Set a custom time in the format HH:mm for the sandbox environment. | ||
url | body | string | A web page or file URL. It can be HTTP(S) or FTP. The sha256 keyword must be unset if this keyword is used. | ||
user_tags | body | list of strings | User tags. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
tags = ['TAG1', 'TAG2', 'TAG3']
response = falcon.submit(action_script="string",
command_line="string",
document_password="string",
enable_tor=boolean,
environment_id=integer,
network_settings="string",
send_email_notifications=boolean,
sha256="string",
submit_name="string",
submit_date="string",
submit_time="string",
url="string",
user_tags=tags
)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
tags = ['TAG1', 'TAG2', 'TAG3']
response = falcon.Submit(action_script="string",
command_line="string",
document_password="string",
enable_tor=boolean,
environment_id=integer,
network_settings="string",
send_email_notifications=boolean,
sha256="string",
submit_name="string",
submit_date="string",
submit_time="string",
url="string",
user_tags=tags
)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
tags = ['TAG1', 'TAG2', 'TAG3']
BODY = {
"sandbox": [
{
"action_script": "string",
"command_line": "string",
"document_password": "string",
"enable_tor": boolean,
"environment_id": integer,
"network_settings": "string",
"sha256": "string",
"submit_name": "string",
"system_date": "string",
"system_time": "string",
"url": "string"
}
],
"send_email_notification": boolean,
"user_tags": tags
}
response = falcon.command("Submit", body=BODY)
print(response)
QueryReports
Find sandbox reports by providing a FQL filter and paging details. Returns a set of report IDs that match your criteria.
PEP8 method name
query_reports
Endpoint
Method | Route |
---|---|
/falconx/queries/reports/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
filter | query | string | Optional filter and sort criteria in the form of an FQL query. | ||
limit | query | integer | The maximum records to return. (Max: 5000). | ||
offset | query | integer | Starting index of overall result set from which to return ids. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. | ||
sort | query | string | The property to sort on, followed by a dot (.), followed by the sort direction, either asc or desc . |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_reports(filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.QueryReports(filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.command("QueryReports",
filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
QuerySubmissions
Find submission IDs for uploaded files by providing a FQL filter and paging details. Returns a set of submission IDs that match your criteria.
PEP8 method name
query_submissions
Endpoint
Method | Route |
---|---|
/falconx/queries/submissions/v1 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
filter | query | string | Optional filter and sort criteria in the form of an FQL query. | ||
limit | query | integer | The maximum records to return. (Max: 5000). | ||
offset | query | integer | Starting index of overall result set from which to return ids. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. | ||
sort | query | string | The property to sort on, followed by a dot (.), followed by the sort direction, either asc or desc . |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_submissions(filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.QuerySubmissions(filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.command("QuerySubmissions",
filter="string",
offset="string",
limit=integer,
sort="string"
)
print(response)
GetSampleV2
Retrieves the file associated with the given ID (SHA256)
PEP8 method name
get_sample
Endpoint
Method | Route |
---|---|
/samples/entities/samples/v2 |
Content-Type
- Produces: application/octet-stream
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
id | query | string | The file SHA256. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. | ||
password_protected | query | boolean | Flag whether the sample should be zipped and password protected with password of infected . |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
save_file = "some_file.ext"
response = falcon.get_sample(password_protected=boolean, ids=file_sha)
with open(save_file, 'wb') as file_download:
file_download.write(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
save_file = "some_file.ext"
response = falcon.GetSampleV2(password_protected=boolean, ids=file_sha)
with open(save_file, 'wb') as file_download:
file_download.write(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
save_file = "some_file.ext"
response = falcon.command("GetSampleV2", password_protected=boolean, ids=file_sha)
with open(save_file, 'wb') as file_download:
file_download.write(response)
UploadSampleV2
Upload a file for sandbox analysis. After uploading, use /falconx/entities/submissions/v1
to start analyzing the file.
PEP8 method name
upload_sample
Endpoint
Method | Route |
---|---|
/samples/entities/samples/v2 |
Content-Type
- Consumes: multipart/form-data
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
comment | formData | string | A descriptive comment to identify the file for other users. | ||
data | formData | file | Content of the uploaded sample in binary format. Max file size: 256 MB. Accepted file formats:
| ||
file_data or sample or upfile | formData | string | Content of the uploaded sample in binary format. Max file size: 256 MB. Accepted file formats:
| ||
file_name | formData | string | Name to use for the file. Uses current file name if not specified. | ||
is_confidential | formData | boolean | Defines the visibility of this file in Falcon MalQuery, either via the API or the Falcon console.
true . | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()
response = falcon.upload_sample(sample=PAYLOAD,
file_name="string",
comment='string',
is_confidential=boolean
)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()
response = falcon.UploadSampleV2(file_data=PAYLOAD,
file_name="string",
comment='string',
is_confidential=boolean
)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()
response = falcon.command("UploadSampleV2",
data=PAYLOAD,
file_name="string",
comment="string",
is_confidential=boolean,
content_type="application/octet-stream"
)
print(response)
DeleteSampleV2
Removes a sample, including file, meta and submissions from the collection
PEP8 method name
delete_sample
Endpoint
Method | Route |
---|---|
/samples/entities/samples/v2 |
Content-Type
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
id | query | string | The file SHA256. | ||
parameters | query | dictionary | Full query string parameters payload in JSON format. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.delete_sample(ids=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.DeleteSampleV2(ids=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(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("DeleteSampleV2", ids=id_list)
print(response)
QuerySampleV1
Retrieves a list with sha256 of samples that exist and customer has rights to access them, maximum number of accepted items is 200
PEP8 method name
query_sample
Endpoint
Method | Route |
---|---|
/samples/queries/samples/GET/v1 |
Content-Type
- Consumes: application/json
- Produces: application/json
Keyword Arguments
Name | Service | Uber | Type | Data type | Description |
---|---|---|---|---|---|
body | body | dictionary | Full body payload in JSON format. | ||
sha256s | body | string or list of strings | Pass a list of sha256s to check if the exist. You will be returned the list of existing hashes. |
Usage
Service class example (PEP8 syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'SHA1,SHA2,SHA3' # Can also pass a list here: ['SHA1', 'SHA2', 'SHA3']
response = falcon.query_sample(sha256s=id_list)
print(response)
Service class example (Operation ID syntax)
from falconpy import FalconXSandbox
# Do not hardcode API credentials!
falcon = FalconXSandbox(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'SHA1,SHA2,SHA3' # Can also pass a list here: ['SHA1', 'SHA2', 'SHA3']
response = falcon.QuerySampleV1(sha256s=id_list)
print(response)
Uber class example
from falconpy import APIHarness
# Do not hardcode API credentials!
falcon = APIHarness(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
BODY = {
"sha256s": [
"string"
]
}
response = falcon.command("QuerySampleV1", body=BODY)
print(response)