Using the Sample Uploads service collection

This service collection has code examples posted to the repository.

Table of Contents

Operation ID	Description
ArchiveListV1 PEP8 list_archive	Retrieves the archives files in chunks.
ArchiveGetV1 PEP8 get_archive	Retrieves the archives upload operation statuses. Status done means that archive was processed successfully. Status error means that archive was not processed successfully.
ArchiveUploadV1 PEP8 upload_archive_v1	Uploads an archive and extracts files list from it. Operation is asynchronous use ArchiveGet to check the status. After uploading, use ExtractionCreateV1 to copy the file to internal storage making it available for content analysis.
ArchiveDeleteV1 PEP8 delete_archive	Delete an archive that was uploaded previously
ArchiveUploadV2 PEP8 upload_archive	Uploads an archive and extracts files list from it. Operation is asynchronous use ArchiveGet to check the status. After uploading, use ExtractionCreateV1 to copy the file to internal storage making it available for content analysis.
ExtractionListV1 PEP8 list_extraction	Retrieves the files extractions in chunks. Status done means that all files were processed successfully. Status error means that at least one of the file could not be processed.
ExtractionGetV1 PEP8 get_extraction	Retrieves the files extraction operation statuses. Status done means that all files were processed successfully. Status error means that at least one of the file could not be processed.
ExtractionCreateV1 PEP8 create_extraction	Extracts files from an uploaded archive and copies them to internal storage making it available for content analysis.
GetSampleV3 PEP 8 get_sample	Retrieves the file associated with the given ID (SHA256).
UploadSampleV3 PEP 8 upload_sample	Upload a file for further cloud analysis. After uploading, call the specific analysis API endpoint.
DeleteSampleV3 PEP 8 delete_sample	Removes a sample, including file, meta and submissions from the collection.

Passing credentials

WARNING

client_id and client_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.

ArchiveListV1

Retrieves the archives files in chunks.

PEP8 method name

list_archive

Endpoint

Method	Route
	/archives/entities/archive-files/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
id			query	string	The archive SHA256.
parameters			query	dictionary	Full query string parameters payload in JSON format.
limit			query	integer	Maximum number of files to retrieve. (Default: 100)
offset			query	string	Offset from where to retrieve files.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.list_archive(id="string",
                               limit=integer,
                               offset="string"
                               )

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.ArchiveListV1(id="string",
                                limit=integer,
                                offset="string"
                                )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("ArchiveListV1",
                          id="string",
                          limit=integer,
                          offset="string"
                          )

print(response)

Back to Table of Contents

ArchiveGetV1

Retrieves the archives upload operation statuses. Status done means that archive was processed successfully. Status error means that archive was not processed successfully.

PEP8 method name

get_archive

Endpoint

Method	Route
	/archives/entities/archives/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
id			query	string	The archive SHA256.
parameters			query	dictionary	Full query string parameters payload in JSON format.
include_files			query	boolean	If true includes processed archive files in response.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.get_archive(id="string", include_files=boolean)

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.ArchiveGetV1(id="string", include_files=boolean)

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("ArchiveGetV1", id="string", include_files="string")

print(response)

Back to Table of Contents

ArchiveUploadV1

Uploads an archive and extracts files list from it. Operation is asynchronous use ArchiveGetV1 to check the status. After uploading, use ExtractionCreateV1 to copy the file to internal storage making it available for content analysis.

This method is deprecated in favor of ArchiveUploadV2.

PEP8 method name

archive_upload_v1

Endpoint

Method	Route
	/archives/entities/archives/v1

Required Scope

Content-Type

• Consumes: application/octet-stream
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	dictionary	Content of the uploaded archive in binary format. The keywords file_data, sample, and upfile will also be accepted for this argument. Max file size: 100 MB. Accepted file formats: zip 7z
comment			query	string	A descriptive comment to identify the file for other users.
is_confidential			query	boolean	Defines visbility of this file, either via the API or the Falcon console. true: File is only show to users within your customer account false: File can be seen by other CrowdStrike customers Defaults to true.
name			query	string	Name of the archive.
parameters			query	dictionary	Full query string parameters payload in JSON format.
password			query	string	Archive password.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.ArchiveUploadV1(name="string",
                                  password="string",
                                  is_confidential=boolean,
                                  comment="string",
                                  file_data=PAYLOAD
                                  )

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.ArchiveUploadV1(name="string",
                                  password="string",
                                  is_confidential=boolean,
                                  comment="string",
                                  file_data=PAYLOAD
                                  )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.command("ArchiveUploadV1",
                          name="string",
                          password="string",
                          is_confidential=boolean,
                          comment="string",
                          file_data=PAYLOAD
                          )

print(response)

Back to Table of Contents

ArchiveDeleteV1

Delete an archive that was uploaded previously

PEP8 method name

delete_archive

Endpoint

Method	Route
	/archives/entities/archives/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
id			query	string	The archive SHA256.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.delete_archive(id="string")

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.ArchiveDeleteV1(id="string")

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("ArchiveDeleteV1", id="string")

print(response)

Back to Table of Contents

ArchiveUploadV2

Uploads an archive and extracts files list from it. Operation is asynchronous use ArchiveGet to check the status. After uploading, use ExtractionCreateV1 to copy the file to internal storage making it available for content analysis.

PEP8 method name

upload_archive

Endpoint

Method	Route
	/archives/entities/archives/v2

Required Scope

Content-Type

• Consumes: multipart/form-data
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
file_data			formData	dictionary	Content of the uploaded archive in binary format. The keywords archive and file will also be accepted for this argument. Max file size: 100 MB. Accepted file formats: zip 7z
comment			formData	string	A descriptive comment to identify the file for other users.
is_confidential			formData	boolean	Defines visbility of this file, either via the API or the Falcon console. true: File is only show to users within your customer account false: File can be seen by other CrowdStrike customers Defaults to true.
file_type			query	string	Archive format, either zip or 7zip. Defaults to zip.
name			formData	string	Name of the archive.
parameters			query	dictionary	Full query string parameters payload in JSON format.
password			formData	string	Archive password.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = "archive.ext"
with open(FILENAME, "rb") as archive_payload:
    PAYLOAD = archive_payload.read()

response = falcon.upload_archive(file_data=PAYLOAD,
                                 comment="string",
                                 is_confidential=boolean,
                                 file_type="string",
                                 name="string",
                                 password="string"
                                 )

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = "archive.ext"
with open(FILENAME, "rb") as archive_payload:
    PAYLOAD = archive_payload.read()

response = falcon.ArchiveUploadV2(file_data=PAYLOAD,
                                  comment="string",
                                  is_confidential=boolean,
                                  file_type="string",
                                  name="string",
                                  password="string"
                                  )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

FILENAME = "archive.ext"
with open(FILENAME, "rb") as archive_payload:
    PAYLOAD = archive_payload.read()

response = falcon.command("ArchiveUploadV2",
                          file_data=PAYLOAD,
                          comment="string",
                          is_confidential=boolean,
                          file_type="string",
                          name="string",
                          password="string"
                          )

print(response)

Back to Table of Contents

ExtractionListV1

Retrieves the files extractions in chunks. Status done means that all files were processed successfully. Status error means that at least one of the file could not be processed.

PEP8 method name

list_extraction

Endpoint

Method	Route
	/archives/entities/extraction-files/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
id			query	string	The extraction operation ID.
parameters			query	dictionary	Full query string parameters payload in JSON format.
limit			query	integer	Maximum number of files to retrieve. (Default: 100)
offset			query	string	Offset from where to retrieve files.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.list_extraction(id="string",
                                  limit=integer,
                                  offset="string"
                                  )

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.ExtractionListV1(id="string",
                                   limit=integer,
                                   offset="string"
                                   )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("ExtractionListV1",
                          id="string",
                          limit=integer,
                          offset="string"
                          )

print(response)

Back to Table of Contents

ExtractionGetV1

Retrieves the files extraction operation statuses. Status done means that all files were processed successfully. Status error means that at least one of the file could not be processed.

PEP8 method name

get_extraction

Endpoint

Method	Route
	/archives/entities/extractions/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
id			query	string	The extraction operation ID.
include_files			query	boolean	If true, includes processed archive files in response.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.get_extraction(id="string", include_files=boolean)

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

response = falcon.ExtractionGetV1(id="string", include_files=boolean)

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("ExtractionGetV1", id="string", include_files=boolean)

print(response)

Back to Table of Contents

ExtractionCreateV1

Extracts files from an uploaded archive and copies them to internal storage making it available for content analysis.

PEP8 method name

create_extraction

Endpoint

Method	Route
	/archives/entities/extractions/v1

Required Scope

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.
extract_all			body	boolean	Flag indicating if all files should be extracted.
files			body	list of dictionaries	List of files to be extracted from the archive. Each dictionary will contain three keys, comment (string), is_confidential (boolean), and name (string).
sha256			body	string	SHA256 of the archive.

Usage

Service class example (PEP8 syntax)

from falconpy.sample_uploads import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

file_list = [{
    "comment": "string",
    "is_confidential": boolean,
    "name": "string"
}]

response = falcon.create_extraction(extract_all=boolean,
                                    files=file_list,
                                    sha256="string"
                                    )

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

file_list = [{
    "comment": "string",
    "is_confidential": boolean,
    "name": "string"
}]

response = falcon.ExtractionCreateV1(extract_all=boolean,
                                     files=file_list,
                                     sha256="string"
                                     )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )
file_list = [{
    "comment": "string",
    "is_confidential": boolean,
    "name": "string"
}]

BODY = {
    "extract_all": boolean,
    "files": file_list,
    "sha256": "string"
}

response = falcon.command("ExtractionCreateV1", body=BODY)

print(response)

Back to Table of Contents

GetSampleV3

Retrieves the file associated with the given ID (SHA256)

PEP8 method name

get_sample

Endpoint

Method	Route
	/samples/entities/samples/v3

Required Scope

Content-Type

• Produces: application/octet-stream

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			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 the password infected.

Usage

Service class example (PEP8 syntax)

from falconpy import SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(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)
open(save_file, 'wb').write(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"

save_file = "some_file.ext"

response = falcon.GetSampleV3(password_protected=boolean, ids=file_sha)
open(save_file, 'wb').write(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"

save_file = "some_file.ext"

response = falcon.command("GetSampleV3", password_protected=boolean, ids=file_sha)
open(save_file, 'wb').write(response)

Back to Table of Contents

UploadSampleV3

Upload a file for further cloud analysis. After uploading, call the specific analysis API endpoint.

PEP8 method name

upload_sample

Endpoint

Method	Route
	/samples/entities/samples/v3

Required Scope

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: Portable executables: .exe, .scr, .pif, .dll, .com, .cpl, etc. Office documents: .doc, .docx, .ppt, .pps, .pptx, .ppsx, .xls, .xlsx, .rtf, .pub PDF APK Executable JAR Windows script component: .sct Windows shortcut: .lnk Windows help: .chm HTML application: .hta Windows script file: .wsf Javascript: .js Visual Basic: .vbs, .vbe Shockwave Flash: .swf Perl: .pl Powershell: .ps1, .psd1, .psm1 Scalable vector graphics: .svg Python: .py Linux ELF executables Email files: MIME RFC 822 .eml, Outlook .msg.
is_confidential			formData	boolean	Defines visibility of this file in Falcon MalQuery, either via the API or the Falcon console. true: File is only shown to users within your customer account false: File can be seen by other CrowdStrike customers Default: true.
file_data or sample or upfile			formData	file	Content of the uploaded sample in binary format. Max file size: 256 MB. Accepted file formats: Portable executables: .exe, .scr, .pif, .dll, .com, .cpl, etc. Office documents: .doc, .docx, .ppt, .pps, .pptx, .ppsx, .xls, .xlsx, .rtf, .pub PDF APK Executable JAR Windows script component: .sct Windows shortcut: .lnk Windows help: .chm HTML application: .hta Windows script file: .wsf Javascript: .js Visual Basic: .vbs, .vbe Shockwave Flash: .swf Perl: .pl Powershell: .ps1, .psd1, .psm1 Scalable vector graphics: .svg Python: .py Linux ELF executables Email files: MIME RFC 822 .eml, Outlook .msg.
file_name			formData	string	Name to use for the file. Uses current file name if not specified.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(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 SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.UploadSampleV3(file_data=PAYLOAD,
                                 file_name="string",
                                 comment='string',
                                 is_confidential=boolean
                                 )

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.command("UploadSampleV3",
                          data=PAYLOAD,
                          file_name="string",
                          comment="string",
                          is_confidential=boolean,
                          content_type="application/octet-stream"
                          )

print(response)

Back to Table of Contents

DeleteSampleV3

Removes a sample, including file, meta and submissions from the collection

PEP8 method name

delete_sample

Endpoint

Method	Route
	/samples/entities/samples/v3

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string	The file SHA256 of the file to delete.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"

response = falcon.delete_sample(ids=file_sha)

print(response)

Service class example (Operation ID syntax)

from falconpy import SampleUploads

# Do not hardcode API credentials!
falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"

response = falcon.DeleteSampleV3(ids=file_sha)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

file_sha = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"

response = falcon.command("DeleteSampleV3", ids=file_sha)

print(response)

Back to Table of Contents