ptsandbox

Async API connector for PT Sandbox instances

SandboxKey

Bases: BaseModel

Abstraction over the key that is used to send to the sandbox

name `instance-attribute`

name: str

Custom key name

key `instance-attribute`

key: SecretStr

The key received in the sandbox interface

host `instance-attribute`

host: str

Hostname of the sandbox instance

For example: 1.1.1.1 or sandbox.example.com without https etc

description `class-attribute` `instance-attribute`

description: str = ''

A description of the key for easy representation somewhere in the interface

max_workers `class-attribute` `instance-attribute`

max_workers: int = Field(default=8, ge=1)

The maximum number of simultaneously running behavioral nodes

The quantity can be found in the interface

ui `class-attribute` `instance-attribute`

ui: UI | None = None

If necessary, you can also access the sandbox via the UI API

url `property`

url: str

https address for connecting via API

debug_url `property`

debug_url: str

https address for connecting via debug API

ui_url `property`

ui_url: str

https address for connecting via UI API

Sandbox

The main class describing interaction with the sandbox via the API

ui `property`

ui: SandboxUI

The UI API client. Raises if no UI credentials were provided in SandboxKey.

has_ui `property`

has_ui: bool

Whether UI credentials were provided in SandboxKey.

close `async`

close() -> None

Close all underlying HTTP sessions (api and ui).

create_rescan `async`

create_rescan(
    trace: str | Path | bytes | BytesIO,
    network: str | Path | bytes | BytesIO,
    /,
    *,
    rules: str | Path | bytes | BytesIO | None = None,
    priority: int = 3,
    short_result: bool = False,
    async_result: bool = True,
    read_timeout: int = 300,
    options: Options = SandboxBaseScanTaskRequest.Options(),
) -> SandboxBaseTaskResponse

Run a retro scan to check for detects without running a behavioral analysis.

It is useful if there is a trace from a malware that can't connect to C2C.

Or is it necessary to check the new correlation rules on the same trace.

Parameters:

trace (str | Path | bytes | BytesIO) –

path to drakvuf-trace.log.zst or just bytes
network (str | Path | bytes | BytesIO) –

path to tcpdump.pcap or just bytes
rules (str | Path | bytes | BytesIO | None, default: None ) –

if you have compiled the rules, then you can rescan with them, rather than using the sandbox embedded inside
priority (int, default: 3 ) –

the priority of the task, between 1 and 4. The higher it is, the faster it will get to work
short_result (bool, default: False ) –

Return only the overall result of the check.

The parameter value is ignored (true is used) if the value of the async_result parameter is also true.
async_result (bool, default: True ) –

Return only the scan_id.

Enabling this option may be usefull to send async requests for file checking.

You can receive full report in a separate request.
read_timeout (int, default: 300 ) –

response waiting time in seconds
options (Options, default: Options() ) –

additional sandbox options

Returns:

SandboxBaseTaskResponse –

The response from the sandbox is either with partial information (when using async_result), or with full information.

Raises:

SandboxUploadException –

if an error occurred when uploading files to the server
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

create_scan `async`

create_scan(
    file: str | Path | bytes | BinaryIO,
    /,
    *,
    file_name: str | None = None,
    rules: str | Path | bytes | BytesIO | None = None,
    priority: int = 3,
    short_result: bool = False,
    async_result: bool = True,
    read_timeout: int = 300,
    upload_timeout: float = 300,
    options: Options = SandboxBaseScanTaskRequest.Options(),
) -> SandboxBaseTaskResponse

Send the specified file to the sandbox for analysis

Parameters:

file (str | Path | bytes | BinaryIO) –

the file to be sent for analysis
file_name (str | None, default: None ) –

The name of the file to be checked, which will be displayed in the sandbox web interface.

If possible, the name of the uploaded file will be taken as the default value.

If not specified, the hash value of the file is calculated using the SHA—256 algorithm.
rules (str | Path | bytes | BytesIO | None, default: None ) –

if you have compiled the rules, then you can scan with them, rather than using the sandbox embedded inside
priority (int, default: 3 ) –

the priority of the task, between 1 and 4. The higher it is, the faster it will get to work
short_result (bool, default: False ) –

Return only the overall result of the check.

The parameter value is ignored (true is used) if the value of the async_result parameter is also true.
async_result (bool, default: True ) –

Return only the scan_id.

Enabling this option may be usefull to send async requests for file checking.

You can receive full report in a separate request.
read_timeout (int, default: 300 ) –

response waiting time in seconds
upload_timeout (float, default: 300 ) –

if a large enough file is being uploaded, increase timeout (in seconds).
options (Options, default: Options() ) –

additional sandbox options

Returns:

SandboxBaseTaskResponse –

The response from the sandbox is either with partial information (when using async_result), or with full information.

Raises:

SandboxUploadException –

if an error occurred when uploading files to the server
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

create_advanced_scan `async`

create_advanced_scan(
    file: str | Path | bytes | BinaryIO,
    /,
    *,
    file_name: str | None = None,
    rules: str | Path | bytes | BytesIO | None = None,
    extra_files: list[Path]
    | list[tuple[BinaryIO, FileName]]
    | None = None,
    short_result: bool = False,
    async_result: bool = True,
    read_timeout: int = 300,
    upload_timeout: float = 300,
    priority: int = 3,
    sandbox: SandboxOptionsAdvanced = SandboxOptionsAdvanced(),
) -> SandboxBaseTaskResponse

Send the specified file to the sandbox for analysis using advanced API

It may not be available in older versions of the sandbox.

Parameters:

file (str | Path | bytes | BinaryIO) –

the file to be sent for analysis
file_name (str | None, default: None ) –

The name of the file to be checked, which will be displayed in the sandbox web interface.

If possible, the name of the uploaded file will be taken as the default value.

If not specified, the hash value of the file is calculated using the SHA—256 algorithm.
rules (str | Path | bytes | BytesIO | None, default: None ) –

if you have compiled the rules, then you can scan with them, rather than using the sandbox embedded inside
priority (int, default: 3 ) –

the priority of the task, between 1 and 4. The higher it is, the faster it will get to work
short_result (bool, default: False ) –

Return only the overall result of the check.

The parameter value is ignored (true is used) if the value of the async_result parameter is also true.
async_result (bool, default: True ) –

Return only the scan_id.

Enabling this option may be usefull to send async requests for file checking.

You can receive full report in a separate request.
read_timeout (int, default: 300 ) –

response waiting time in seconds
upload_timeout (float, default: 300 ) –

if a large enough file is being uploaded, increase timeout (in seconds).
sandbox (SandboxOptionsAdvanced, default: SandboxOptionsAdvanced() ) –

additional sandbox options

Returns:

SandboxBaseTaskResponse –

The response from the sandbox is either with partial information (when using async_result), or with full information.

Raises:

SandboxUploadException –

if an error occurred when uploading files to the server
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

create_url_scan `async`

create_url_scan(
    url: str,
    /,
    *,
    rules: str | Path | bytes | BytesIO | None = None,
    priority: int = 3,
    short_result: bool = False,
    async_result: bool = True,
    read_timeout: int = 300,
    options: Options = SandboxBaseScanTaskRequest.Options(),
) -> SandboxBaseTaskResponse

Send the url to the sandbox

Parameters:

url (str) –

the url to be sent for analysis
rules (str | Path | bytes | BytesIO | None, default: None ) –

if you have compiled the rules, then you can scan with them, rather than using the sandbox embedded inside
priority (int, default: 3 ) –

the priority of the task, between 1 and 4. The higher it is, the faster it will get to work
short_result (bool, default: False ) –

Return only the overall result of the check.

The parameter value is ignored (true is used) if the value of the async_result parameter is also true.
async_result (bool, default: True ) –

Return only the scan_id.

Enabling this option may be usefull to send async requests for file checking.

You can receive full report in a separate request.
read_timeout (int, default: 300 ) –

response waiting time in seconds
options (Options, default: Options() ) –

additional sandbox options

Returns:

SandboxBaseTaskResponse –

The response from the sandbox is either with partial information (when using async_result), or with full information.

Raises:

SandboxUploadException –

if an error occurred when uploading rules to the server
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

wait_for_report `async`

wait_for_report(
    base_report: SandboxBaseTaskResponse,
    wait_time: float = 120,
    *,
    error_limit: int = 3,
    scan_with_source: bool = False,
) -> SandboxBaseTaskResponse

Waiting for a full response from the sandbox if the request was with the async_result=True flag

Parameters:

wait_time (float, default: 120 ) –

how many seconds should I wait?

Example of a formula for calculating a parameter:

wait_time = options.sandbox.analysis_duration * 4 + (
    300 if sandbox_options.sandbox.analysis_duration < 80 else 120
)

Returns:

SandboxBaseTaskResponse –

The response from the sandbox with full information.

Raises:

SandboxException –

there is nothing to wait, because there is not even a short report
SandboxTooManyErrorsException –

if there are too many errors while waiting for the report
SandboxScanNotFullException –

the scan reached a terminal state (per the status endpoint) but no full report arrived within wait_time. Error codes (e.g. sandbox_run_sample) are attached when available.
SandboxWaitTimeoutException –

if the specified waiting time is exceeded

check_task `async`

check_task(
    task_id: str | UUID, allow_preflight: bool = True
) -> SandboxCheckTaskResponse

Checking the result of a scan running with the async_result flag

Parameters:

task_id (str | UUID) –

task id :)
allow_preflight (bool, default: True ) –

If this flag is set, an intermediate result with the is_preflight attribute will be returned for scanning with multiple stages (for example, static + BA).

Returns:

SandboxCheckTaskResponse –

Information about the analysis status

Raises:

SandboxException –

if the passed task_id is not in UUID format
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

source_get_status `async`

source_get_status(
    task_id: str | UUID, allow_preflight: bool = True
) -> SandboxCheckTaskResponse

Check the status of a scan started via the source API (source_check_file / source_check_url).

Returns only the status without the full report. For the full report, use source_get_report.

Parameters:

task_id (str | UUID) –

task id :)
allow_preflight (bool, default: True ) –

If this flag is set, an intermediate result with the is_preflight attribute will be returned for scanning with multiple stages (for example, static + BA).

Returns:

SandboxCheckTaskResponse –

Information about the analysis status

Raises:

SandboxException –

if the passed task_id is not in UUID format
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

get_report `async`

get_report(task_id: str | UUID) -> SandboxBaseTaskResponse

Getting the full task scan report

The check was completed successfully. The results are in the message body. If the scan result is not ready yet, the result and artifacts keys are missing.

The results will be returned only for the key that the analysis was started with. Sandbox restrictions for now.

Parameters:

task_id (str | UUID) –

task id :)

Returns:

SandboxBaseTaskResponse –

The response from the sandbox is either with partial information (when using async_result), or with full information.

Raises:

SandboxException –

if the passed task_id is not in UUID format
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

get_file `async`

get_file(hash: str, read_timeout: int = 120) -> bytes

Download file from the sandbox by hash

Parameters:

hash (str) –

sha256 hash of the file

Returns:

bytes –

file data

Raises:

SandboxException –

if the hash type cannot be determined
ClientResponseError –

if the server returns an error status (404 if the file is not found)
ClientError –

on connection or transport errors

get_file_stream `async`

get_file_stream(
    hash: str, read_timeout: int = 120
) -> AsyncIterator[bytes]

Download file from the sandbox by hash

Parameters:

hash (str) –

sha256 hash of the file

Returns:

AsyncIterator[bytes] –

streaming file data

Raises:

SandboxException –

if the hash type cannot be determined
ClientResponseError –

if the server returns an error status (404 if the file is not found)
ClientError –

on connection or transport errors

get_images `async`

get_images() -> list[SandboxImageInfo]

Get a list of available images in the sandbox

Raises:

ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

get_email_headers `async`

get_email_headers(
    file: str | Path | bytes | BinaryIO,
) -> AsyncIterator[bytes]

Upload an email to receive headers

Parameters:

file (str | Path | bytes | BinaryIO) –

path to .eml file or just binary data

Returns:

AsyncIterator[bytes] –

The header file

Raises:

SandboxException –

if the file type is not supported or the file cannot be opened
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors

source_check_file `async`

source_check_file(
    file: str | Path | bytes | BinaryIO,
    /,
    *,
    file_name: str | None = None,
    short_result: bool = True,
    async_result: bool = False,
    priority: int = 3,
    passwords_for_unpack: list[str] | None = None,
    product: str | None = None,
    metadata: dict[str, str] | None = None,
    read_timeout: int = 240,
) -> SandboxBaseTaskResponse

Your application can run a file check with predefined parameters and in response receive the results of the check and/or the ID of the task.

Parameters:

file (str | Path | bytes | BinaryIO) –

The file to be sent for analysis
file_name (str | None, default: None ) –

The name of the file to be checked, which will be displayed in the sandbox web interface.

If possible, the name of the uploaded file will be taken as the default value.

If not specified, the hash value of the file is calculated using the SHA—256 algorithm.
short_result (bool, default: True ) –

Return only the overall result of the check.

Attention. When using a query with the full result (short_result=false), the response waiting time can be increased by 2 seconds.

For example, scanning a file without BA takes an average of hundreds of milliseconds, and you will have to wait seconds to get the full result, which is much longer.
async_result (bool, default: False ) –

Return only the scan_id without waiting for the scan to finish.

The "result" key is missing in the response.
priority (int, default: 3 ) –

The priority of the task is from 1 to 4. The higher it is, the faster it will get to work.
passwords_for_unpack (list[str] | None, default: None ) –

A list of passwords for unpacking encrypted archives
product (str | None, default: None ) –

The source ID string is "EDR" or "CS" ("PT_EDR" or "PT_CS").

You only need to fill it out during integration

metadata (dict[str, str] | None, default: None ) –

Source metadata for special scanning

{
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
}

read_timeout (int, default: 240 ) –

Response waiting time in seconds

Raises:

ValueError –

if passed values incorrect
SandboxException –

if incorrect file type is passed (usually when ignoring type hints)
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

source_check_url `async`

source_check_url(
    url: str,
    /,
    *,
    short_result: bool = True,
    async_result: bool = False,
    priority: int = 3,
    passwords_for_unpack: list[str] | None = None,
    product: str | None = None,
    metadata: dict[str, str] | None = None,
    read_timeout: int = 240,
) -> SandboxBaseTaskResponse

Your application can run a URL scan and receive the scan results and/or the ID of the task.

Parameters:

url (str) –

The file to be sent for analysis
short_result (bool, default: True ) –

Return only the overall result of the check.

Attention. When using a query with the full result (short_result=false), the response waiting time can be increased by 2 seconds.

For example, scanning a file without BA takes an average of hundreds of milliseconds, and you will have to wait seconds to get the full result, which is much longer.
async_result (bool, default: False ) –

Return only the scan_id without waiting for the scan to finish.

The "result" key is missing in the response.
priority (int, default: 3 ) –

The priority of the task is from 1 to 4. The higher it is, the faster it will get to work.
passwords_for_unpack (list[str] | None, default: None ) –

A list of passwords for unpacking encrypted archives
product (str | None, default: None ) –

The source ID string is "EDR" or "CS" ("PT_EDR" or "PT_CS").

You only need to fill it out during integration

metadata (dict[str, str] | None, default: None ) –

Source metadata for special scanning

{
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
}

read_timeout (int, default: 240 ) –

Response waiting time in seconds

Raises:

ValueError –

if passed values incorrect
ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

get_tasks `async`

get_tasks(
    query: str = "",
    limit: int = 20,
    offset: int = 0,
    utc_offset_seconds: int = 0,
    next_cursor: str | None = None,
) -> SandboxTasksResponse

Get tasks listing

Warning: Unstable API (can be changed in future release)

Parameters:

query (str, default: '' ) –
filtering using the query language. For the syntax, see the user documentation.
```
age < 30d AND (task.correlated.state != UNKNOWN ) ORDER BY start desc
```
limit (int, default: 20 ) –

limit on the number of records to be returned
utc_offset_seconds (int, default: 0 ) –

the offset of the user's time from UTC, which will be used for the time in QL queries
next_cursor (str | None, default: None ) –

the value from the previous request

Returns:

SandboxTasksResponse –

Information about requested tasks

Raises:

ClientResponseError –

if the server returns an error status
ClientError –

on connection or transport errors
ValidationError –

if the response body does not match the expected model

ptsandbox

ptsandbox

SandboxKey

name instance-attribute

key instance-attribute

host instance-attribute

description class-attribute instance-attribute

max_workers class-attribute instance-attribute

ui class-attribute instance-attribute

url property

debug_url property

ui_url property

Sandbox

ui property

has_ui property

close async

create_rescan async

create_scan async

create_advanced_scan async

create_url_scan async

wait_for_report async

check_task async

source_get_status async

get_report async

get_file async

get_file_stream async

get_images async

get_email_headers async

source_check_file async

source_check_url async

get_tasks async

name `instance-attribute`

key `instance-attribute`

host `instance-attribute`

description `class-attribute` `instance-attribute`

max_workers `class-attribute` `instance-attribute`

ui `class-attribute` `instance-attribute`

url `property`

debug_url `property`

ui_url `property`

ui `property`

has_ui `property`

close `async`

create_rescan `async`

create_scan `async`

create_advanced_scan `async`

create_url_scan `async`

wait_for_report `async`

check_task `async`

source_get_status `async`

get_report `async`

get_file `async`

get_file_stream `async`

get_images `async`

get_email_headers `async`

source_check_file `async`

source_check_url `async`

get_tasks `async`