Scan

Default scan

Regular scanning sends files to the sandbox without fine-tuning the settings.

Code example

import asyncio
from pathlib import Path

from ptsandbox import Sandbox, SandboxKey
from ptsandbox.models import SandboxBaseScanTaskRequest, SandboxOptions


async def main():
    key = SandboxKey(
        name="test-key-1",
        key="<TOKEN_FROM_SANDBOX>",
        host="10.10.10.10",
    )

    sandbox = Sandbox(key)

    task = await sandbox.create_scan(
        Path("./example.py"),
        options=SandboxBaseScanTaskRequest.Options(
            sandbox=SandboxOptions(
                image_id="ubuntu-jammy-x64",
                analysis_duration=30,
            )
        ),
    )

    result = await sandbox.wait_for_report(task)
    if (report := result.get_long_report()) is not None:
        print(report.result.verdict)


asyncio.run(main())

Usecase

This is useful when you need to send a file for analysis with a minimum number of options.

ptsandbox.sandbox.sandbox.Sandbox.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

Low-level API

Under the hood, Sandbox.create_scan uploads the file via upload_file and then calls create_scan on the API. You can use these methods directly for more control:

Direct API usage

from pathlib import Path

from ptsandbox import Sandbox, SandboxKey
from ptsandbox.models import SandboxScanTaskRequest, SandboxOptions

sandbox = Sandbox(SandboxKey(...))

# Step 1: upload the file
uploaded = await sandbox.api.upload_file(Path("./example.py"))

# Step 2: create the scan task
scan = SandboxScanTaskRequest(
    file_uri=uploaded.data.file_uri,
    file_name="example.py",
    short_result=False,
    async_result=True,
    priority=3,
)
task = await sandbox.api.create_scan(scan)

ptsandbox.sandbox.api._storage.StorageMixin.upload_file async

upload_file(
    file: str | Path | bytes | BinaryIO,
    upload_timeout: float = 300,
) -> SandboxUploadScanFileResponse

Uploads the file to the sandbox

Parameters:

• file (str | Path | bytes | BinaryIO) –

  a path in the form of a string, either a Path object or binary data

• upload_timeout (float, default: 300 ) –

  if a large enough file is being uploaded, increase timeout (in seconds).

Returns:

• SandboxUploadScanFileResponse –

  The link to the file in the temporary storage and the lifetime of this file are returned, or an exception is thrown.

Raises:

• SandboxException –

  if incorrect arguments are 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

ptsandbox.sandbox.api._analysis.AnalysisMixin.create_scan async

create_scan(
    data: SandboxScanTaskRequest, read_timeout: int = 0
) -> SandboxBaseTaskResponse

Send the specified file to the sandbox for analysis

Parameters:

• data (SandboxScanTaskRequest) –

  sandbox parameters in model

• read_timeout (int, default: 0 ) –

  response waiting time in seconds

Returns:

• SandboxBaseTaskResponse –

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

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

Options

Options for configuring analysis parameters. You can set the scan image, custom run command, etc.

ptsandbox.models.api.analysis.SandboxOptions

Bases: SandboxBaseOptions

Parameters of behavioral analysis.

In the absence, the source parameters are used for analysis, which are set in the system by default.

enabled class-attribute instance-attribute

enabled: bool = True

Perform a behavioral analysis

file_types class-attribute instance-attribute

file_types: list[str] | None = None

A list of the final file types or groups of files that will be sent for behavioral analysis

For example: ["adobe-acrobat/", "databases/", "executable-files/", "presentations/", "spreadsheets/", "word-processor/"]

filter_by_properties class-attribute instance-attribute

filter_by_properties: FilterProperties | None = None

Filtering a group of files by properties to send to the sandbox for analysis

URL

You can also scan URLs. The sandbox downloads the file from the URL and analyzes it.

Code example

import asyncio

from ptsandbox import Sandbox, SandboxKey
from ptsandbox.models import SandboxOptions, SandboxScanURLTaskRequest


async def main():
    key = SandboxKey(
        name="test-key-1",
        key="<TOKEN_FROM_SANDBOX>",
        host="10.10.10.10",
    )

    sandbox = Sandbox(key)

    task = await sandbox.create_url_scan(
        "http://malware.com/malicious-file",
        options=SandboxScanURLTaskRequest.Options(
            sandbox=SandboxOptions(
                image_id="ubuntu-jammy-x64",
                analysis_duration=30,
            )
        ),
    )

    result = await sandbox.wait_for_report(task)
    if (report := result.get_long_report()) is not None:
        print(report.result.verdict)


asyncio.run(main())

ptsandbox.sandbox.sandbox.Sandbox.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

ptsandbox.sandbox.api._analysis.AnalysisMixin.create_url_scan class-attribute instance-attribute

create_url_scan = creat_url_scan

Advanced scan

Use advanced scanning when you need to fine-tune launch parameters or upload additional files alongside the sample.

Code example

import asyncio
from pathlib import Path

from ptsandbox import Sandbox, SandboxKey
from ptsandbox.models import SandboxOptionsAdvanced


async def main():
    key = SandboxKey(
        name="test-key-1",
        key="<TOKEN_FROM_SANDBOX>",
        host="10.10.10.10",
    )

    sandbox = Sandbox(key)

    task = await sandbox.create_advanced_scan(
        Path("./example.elf"),
        extra_files=[Path("./file.txt"), Path("./file.sh")], # (1)!
        sandbox=SandboxOptionsAdvanced( # (2)!
            image_id="ubuntu-jammy-x64",
            analysis_duration=30,
            disable_clicker=True,
        ),
    )

    result = await sandbox.wait_for_report(task)
    if (report := result.get_long_report()) is not None:
        print(report.result.verdict)


asyncio.run(main())

1. The library does not check the existence of files
2. We specify SandboxOptionsAdvanced instead of SandboxOptions

Tip - enable manual analysis

from ptsandbox.models import VNCMode

task = await sandbox.create_advanced_scan(
    Path("./example.exe"),
    sandbox=SandboxOptionsAdvanced(
        image_id="win11-23H2-x64",
        analysis_duration=600,
        disable_clicker=True,
        vnc_mode=VNCMode.FULL,
    )
)

ptsandbox.sandbox.sandbox.Sandbox.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

ptsandbox.sandbox.api._analysis.AnalysisMixin.create_advanced_scan async

create_advanced_scan(
    data: SandboxAdvancedScanTaskRequest,
    read_timeout: int = 0,
) -> SandboxBaseTaskResponse

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

Parameters:

• data (SandboxAdvancedScanTaskRequest) –

  sandbox parameters in model

• read_timeout (int, default: 0 ) –

  response waiting time in seconds

Returns:

• SandboxBaseTaskResponse –

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

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

Options

Options for configuring analysis parameters. You can set the scan image, custom run command, etc.

ptsandbox.models.api.analysis.SandboxOptionsAdvanced

Bases: SandboxBaseOptions

Run an advanced analysis of the uploaded file in the VM without unpacking.

Provides an opportunity to fine-tuning.

The options are in beta, so they may change in the future.

disable_clicker class-attribute instance-attribute

disable_clicker: bool = False

Disable auto-clicker startup

Useful when enabling manual analysis.

skip_sample_run class-attribute instance-attribute

skip_sample_run: bool = False

Disable sample launch

vnc_mode class-attribute instance-attribute

vnc_mode: VNCMode = DISABLED

Manual analysis mode

extra_files class-attribute instance-attribute

extra_files: list[ExtraFile] = Field(
    default_factory=list[ExtraFile]
)

A list of additional files that are placed in the VM

ExtraFile

Bases: BaseModel

An additional file to be placed next to the sample

uri instance-attribute

uri: str

Link to the uploaded object

name instance-attribute

name: str

Name in the VM

Waiting for the report

When using async_result=True (the default), the sandbox returns a short report immediately. To get the full report, use wait_for_report which polls the sandbox until the analysis is complete.

Code example

task = await sandbox.create_scan(Path("./example.py"))

result = await sandbox.wait_for_report(
    task,
    wait_time=120,
    error_limit=3,
)
if (report := result.get_long_report()) is not None:
    print(report.result.verdict)

Waiting for the report

wait_for_report polls the sandbox until a full (long) report is available and returns it as-is — including for retro scans (create_rescan), whose SANDBOX engine state may be UNKNOWN/UNSCANNED since no fresh behavioral analysis runs.

If the scan reached a terminal state but no full report ever arrives within wait_time, wait_for_report raises SandboxScanNotFullException; otherwise it waits the full wait_time and raises SandboxWaitTimeoutException.

Calculating wait_time

A good formula for wait_time:

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

ptsandbox.sandbox.sandbox.Sandbox.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