Py PTSandbox

https://security-experts-community.github.io/py-ptsandbox/
Admin
Py PTSandbox is a modern, fully typed, and completely asynchronous Python client library designed to...
Tokens:49,389
Snippets:606
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### NEW_VERSION_INSTALLATION_SCHEDULED Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the NEW_VERSION_INSTALLATION_SCHEDULED system event.

```json
{
    "time": 1111111
}
```

--------------------------------

### Install py-ptsandbox

Source: https://security-experts-community.github.io/py-ptsandbox

Installation commands for various package managers.

```bash
pip install ptsandbox
```

```bash
uv add ptsandbox
```

```nix
inputs.py-ptsandbox.url = "github:Security-Experts-Community/py-ptsandbox";
```

--------------------------------

### get_system_version()

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Retrieves the version of the installed product.

```APIDOC
## get_system_version()

### Description
Get the version of the installed product.

### Signature
`get_system_version() -> SandboxSystemVersionResponse`

### Raises
- **SandboxException** - if not authorized or token refresh fails
- **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 /av-distribution-packs

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves a list of AV distributions available for installation.

```APIDOC
## GET /av-distribution-packs

### Description
Retrieves a list of AV distributions available for installation.

### Method
GET

### Endpoint
/av-distribution-packs
```

--------------------------------

### List Tasks for an Entry Point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Example showing how to retrieve and print tasks associated with a specific entry point.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    tasks = await sandbox.ui.get_entry_point_tasks("....")
    print(tasks.tasks)

asyncio.run(main())
```

--------------------------------

### NODE_IS_NOT_READY Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the NODE_IS_NOT_READY system event.

```json
{
    "since": 1111111.0
}
```

--------------------------------

### Get possible entry point types

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves a list of available source types and their required parameters.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    entry_points_types = await sandbox.ui.get_entry_points_types()
    print(entry_points_types)

asyncio.run(main())
```

```python
get_entry_points_types() -> SandboxEntryPointsTypesResponse
```

--------------------------------

### Configure VM Initialization URL

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/debug-options

Defines a script to run in the VM immediately before behavioral analysis starts.

```text
extra_vm_init_url: NotRequired[str]
```

--------------------------------

### END_OF_SUPPORT_SOON Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the END_OF_SUPPORT_SOON system event.

```json
{
    "eosTs": 1111111
}
```

--------------------------------

### Define Installer Model Fields

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Field for specifying the installer package name.

```python
name: str | None = None
```

--------------------------------

### AV_ENGINE_IN_NOT_GENERAL_AVAILABILITY Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the AV_ENGINE_IN_NOT_GENERAL_AVAILABILITY system event.

```json
{
    "engineCodeName": "clamav",
    "distributionPack": "...",
    "distributionVersion": "1.1.1",
    "maintenanceStatus": "END_OF_SUPPORT"
}
```

--------------------------------

### Delete an Entry Point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Example demonstrating authorization and deletion of an entry point.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    await sandbox.ui.delete_entry_point("...")

asyncio.run(main())
```

--------------------------------

### Get added entry points

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves a list of sources currently configured for analysis.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    entry_points = await sandbox.ui.get_entry_points()
    print(entry_points)

asyncio.run(main())
```

```python
get_entry_points() -> SandboxEntryPointsResponse
```

--------------------------------

### GET /engines/sandbox/getImages

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves a list of virtual machine images installed in the PT Sandbox.

```APIDOC
## GET /engines/sandbox/getImages

### Description
Retrieves a list of virtual machine images installed in the PT Sandbox.

### Method
GET

### Endpoint
<URL>/engines/sandbox/getImages
```

--------------------------------

### Perform URL Scan

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/scan

Example of downloading and analyzing a file from a URL.

```python
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())

```

--------------------------------

### Query language example

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/tasks

An example of a query string used for filtering tasks.

```text
age < 30d AND (task.correlated.state != UNKNOWN ) ORDER BY start desc
```

--------------------------------

### Define Requirements Model Fields

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

System requirements for AV installation.

```python
os: str | None = None
```

```python
bit: str | None = None
```

--------------------------------

### Retrieve System Version

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Returns the version of the installed product. Requires authorization and may raise exceptions for network or validation errors.

```python
get_system_version() -> SandboxSystemVersionResponse
```

--------------------------------

### Get specific entry point information

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves detailed information for a specific source or iterates through all available sources.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    info = await sandbox.ui.get_entry_point("...")
    print(info)

asyncio.run(main())
```

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    entry_points = await sandbox.ui.get_entry_points()
    for entry_point in entry_points.data:
        info = await sandbox.ui.get_entry_point(entry_point.id)
        print(info.data.name, info.data.enabled)

asyncio.run(main())
```

--------------------------------

### Sandbox image list output format

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/image-info

Example representation of the data returned by the get_images method.

```text
[
    SandboxImageInfo(image_id='ubuntu-jammy-x64', ...),
    SandboxImageInfo(image_id='win10-1803-x64', ...),
    ...
]
```

--------------------------------

### Extract email headers example

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/email

Demonstrates how to use the Sandbox client to stream email headers from a local file to a destination file.

```python
import aiofiles
from pathlib import Path
from ptsandbox import Sandbox, SandboxKey

async def example() -> None:
    sandbox = Sandbox(key=SandboxKey(...))

    async with aiofiles.open("./email-headers", "wb") as fd:
        async for chunk in sandbox.get_email_headers(Path("./email.bin")):
            await fd.write(chunk)
```

--------------------------------

### POST /analysis/createScanTask

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Starts an analysis task for a file that has been previously uploaded to the sandbox.

```APIDOC
## POST /analysis/createScanTask

### Description
Starts an analysis task for a file that has been previously uploaded to the sandbox.

### Method
POST

### Endpoint
<URL>/analysis/createScanTask

### Parameters
#### Request Body
- **file_uri** (str) - Required - The file URI received when uploading the file
- **options** (Options) - Optional - Additional scanning options
```

--------------------------------

### COMPONENT_ERROR Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the COMPONENT_ERROR system event.

```json
{
    "code": "COMPONENT_ERROR",
    "group": "SANDBOX",
    "level": "ERROR",
    "objectId": "SANDBOX",
    "params": {
        "sb-worker-1": {
            "error_codes": [
                "OFFLINE"
            ]
        },
        "traps-resource-plugin": {
            "error_codes": [
                "OFFLINE"
            ]
        }
    }
    ...
}
```

--------------------------------

### Retrieve antivirus distribution packs

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/antiviruses

Lists all available antivirus distribution packs for installation.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    packs = await sandbox.ui.get_av_distribution_packs()
    print(packs)

asyncio.run(main())
```

```python
get_av_distribution_packs() -> (
    SandboxAVDistributionPacksResponse
)
```

--------------------------------

### Define ts_started attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Represents the timestamp of the start of work.

```python
ts_started: float | None = Field(
    default=None, alias="tsStarted"
)
```

--------------------------------

### get_av_distribution_packs()

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/antiviruses

Retrieves the list of antivirus distribution packs available for installation.

```APIDOC
## get_av_distribution_packs()

### Description
Get the list of antivirus distributions available for installation.

### Signature
`get_av_distribution_packs() -> SandboxAVDistributionPacksResponse`

### Returns
- **SandboxAVDistributionPacksResponse** - A model with the distribution packs.

### Exceptions
- **SandboxException** - If not authorized or token refresh fails.
- **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.
```

--------------------------------

### Fetch scan results for a specific artifact

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Example demonstrating how to authorize, retrieve a task tree, and iterate through artifact scans.

```python
import asyncio
from uuid import UUID
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    scan_id = UUID("...")
    tree = await sandbox.ui.get_task_tree(scan_id)
    for children in tree.children:
        scan = await sandbox.ui.get_task_artifact_scans(scan_id, children.node_id)

asyncio.run(main())
```

--------------------------------

### POST /analysis/createScanURLTask

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Starts an analysis task for a specified URL.

```APIDOC
## POST /analysis/createScanURLTask

### Description
Starts an analysis task for a specified URL.

### Method
POST

### Endpoint
<URL>/analysis/createScanURLTask

### Parameters
#### Request Body
- **url** (str) - Required - URL address for analysis
- **options** (Options) - Optional - Additional scanning options
```

--------------------------------

### GET /av-engines/{item_id}

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves the settings of a specific AV engine.

```APIDOC
## GET /av-engines/{item_id}

### Description
Retrieves the settings of a specific AV engine.

### Method
GET

### Endpoint
/av-engines/{item_id}

### Parameters
#### Path Parameters
- **item_id** (string) - Required - The unique identifier of the AV engine.
```

--------------------------------

### Get license method signature

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/license

Signature for the get_license asynchronous method.

```python
get_license() -> SandboxLicenseResponse
```

--------------------------------

### Retrieve all tasks

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Demonstrates how to initialize the sandbox, authorize the session, and fetch a list of tasks.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    tasks = await sandbox.ui.get_tasks()
    print(tasks)

asyncio.run(main())
```

--------------------------------

### Get task summary

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Fetches a summary for a specific task using its UUID. Ensure the sandbox is authorized before calling.

```python
import asyncio
from uuid import UUID
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    summary = await sandbox.ui.get_task_summary(UUID("..."))
    print(summary)

asyncio.run(main())
```

--------------------------------

### Retrieve sandbox images

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/image-info

Demonstrates how to initialize a Sandbox instance and fetch the list of available images.

```python
from ptsandbox import Sandbox, SandboxKey

async def example() -> None:
    key = SandboxKey(...)
    sandbox = Sandbox(key)

    images = await sandbox.get_images()
    print(images)
```

--------------------------------

### Download Logs from Entry Point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Demonstrates how to authorize and stream logs from an entry point to a local file using aiofiles.

```python
import asyncio

import aiofiles

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    async with aiofiles.open("./logs.zip", "wb") as fd:
        async for chunk in sandbox.ui.get_entry_point_logs("..."): 
            await fd.write(chunk)

asyncio.run(main())
```

--------------------------------

### Retrieve tasks using the Sandbox client

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/tasks

Demonstrates how to initialize the Sandbox client and iterate through the retrieved task list.

```python
from ptsandbox import Sandbox, SandboxKey

async def example() -> None:
    key = SandboxKey(...)
    sandbox = Sandbox(key)

    result = await sandbox.get_tasks()
    for task in result.tasks:
        print(task.id, task.name)
```

--------------------------------

### NODE_HAVE_ERROR Parameters

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Example parameters for the NODE_HAVE_ERROR system event.

```json
{
    "error_types": ["NetworkUnavailable", "MemoryPressure", "DiskPressure"]
}
```

--------------------------------

### Define Entry Point Settings

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configures connection parameters for entry points, including balancer and destination resource details.

```python
balancer_host: str | None = Field(
    default=None, alias="balancerHost"
)
```

```python
balancer_port: int | None = Field(
    default=None, alias="balancerPort"
)
```

```python
destination_login: str | None = Field(
    default=None, alias="destinationLogin"
)
```

```python
destination_options: str | None = Field(
    default=None, alias="destinationOptions"
)
```

```python
destination_password: str | None = Field(
    default=None, alias="destinationPassword"
)
```

```python
destination_port: int | None = Field(
    default=None, alias="destinationPort"
)
```

```python
destination_server: str | None = Field(
    default=None, alias="destinationServer"
)
```

```python
destination_share_path: str | None = Field(
    default=None, alias="destinationSharePath"
)
```

```python
destination_type: str | None = Field(
    default=None, alias="destinationType"
)
```

```python
destination_version: str | None = Field(
    default=None, alias="destinationVersion"
)
```

```python
destination_auth_type: (
    Literal["NTLM", "KERBEROS"] | None
) = Field(default=None, alias="destinationAuthType")
```

```python
destination_dc_ip: str | None = Field(
    default=None, alias="destinationDcIp"
)
```

```python
destination_use_ssl: bool | None = Field(
    default=None, alias="destinationUseSsl"
)
```

--------------------------------

### Create a new entry point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Registers a new analysis source. Requires specific configuration parameters based on the source type.

```python
import asyncio

from ptsandbox import Sandbox, SandboxKey
from ptsandbox.models import (
    EntryPointSettings,
    EntryPointToken,
    EntryPointType,
    SandboxCreateEntryPointRequest,
)


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    await sandbox.ui.create_entry_point(
        SandboxCreateEntryPointRequest(
            name="test-source",
            type=EntryPointType.SCAN_API,
            settings=EntryPointSettings(
                token=EntryPointToken(
                    id=1337,
                    name="test-token",
                )
            ),
        )
    )

asyncio.run(main())
```

```python
create_entry_point(
    parameters: SandboxCreateEntryPointRequest,
) -> None
```

--------------------------------

### Enable Manual Analysis

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/scan

Configure VNC mode for manual interaction during sandbox analysis.

```python
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,
    )
)

```

--------------------------------

### Initialize Sandbox with Async Context Manager

Source: https://security-experts-community.github.io/py-ptsandbox

Use the async context manager to automatically handle HTTP session lifecycle.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

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

    async with Sandbox(key) as sandbox:
        print(await sandbox.api.get_images())

asyncio.run(main())
```

--------------------------------

### create_entry_point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Adds a new analysis source to the system.

```APIDOC
## create_entry_point(parameters)

### Description
Add a new analysis source.

### Signature
`async create_entry_point(parameters: SandboxCreateEntryPointRequest) -> None`

### Parameters
- **parameters** (SandboxCreateEntryPointRequest) - Required - Parameters for request.

### Exceptions
- **SandboxException**: If not authorized or token refresh fails.
- **ClientResponseError**: If the server returns an error status.
- **ClientError**: On connection or transport errors.
```

--------------------------------

### Direct API usage

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/download-files

Initializes the Sandbox client for low-level artifact downloads.

```python
from ptsandbox import Sandbox, SandboxKey

sandbox = Sandbox(SandboxKey(...))
```

--------------------------------

### Retrieve BAqueue Tasks

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/baqueue

Demonstrates how to initialize the sandbox, authorize the session, and iterate through currently running tasks in the BAqueue.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    baqueue = await sandbox.ui.get_baqueue_tasks()
    for task in baqueue.tasks:
        print(task.object_name, task.state)

asyncio.run(main())
```

--------------------------------

### Manage Sandbox Lifecycle

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/system

Demonstrates how to manage HTTP sessions using an async context manager or explicit closure.

```python
from ptsandbox import Sandbox, SandboxKey

# Using the async context manager (recommended)
async with Sandbox(SandboxKey(...)) as sandbox:
    status = await sandbox.api.get_health_status()

# Or explicitly
sandbox = Sandbox(SandboxKey(...))
try:
    status = await sandbox.api.get_health_status()
finally:
    await sandbox.close()
```

```python
close() -> None
```

--------------------------------

### source_get_status

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/ptsandbox

Checks the status of a scan started via the source API.

```APIDOC
## source_get_status(task_id, allow_preflight=True)

### Description
Checks the status of a scan started via the source API (e.g., `source_check_file` or `source_check_url`). Returns only the status without the full report.

### Parameters
- **task_id** (str | UUID) - Required - The ID of the task.
- **allow_preflight** (bool) - Optional - Whether to return intermediate results for multi-stage scans.

### Returns
- **SandboxCheckTaskResponse** - Information about the analysis status.
```

--------------------------------

### Retrieve Product Version

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/system

Fetches version information for the product. Ensure the Sandbox instance is properly authenticated.

```python
from ptsandbox import Sandbox, SandboxKey

async def example() -> None:
    key = SandboxKey(...)
    sandbox = Sandbox(key)

    version = await sandbox.api.get_version()
    print(version)
```

```python
get_version() -> SandboxGetVersionResponse
```

--------------------------------

### source_get_status

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/sandbox

Checks the status of a scan started via the source API.

```APIDOC
## source_get_status(task_id, allow_preflight=True)

### Description
Checks the status of a scan started via the source API (source_check_file / source_check_url). Returns only the status without the full report.

### Parameters
- **task_id** (str | UUID) - Required - The ID of the task to check.
- **allow_preflight** (bool) - Optional - If set, returns intermediate results for multi-stage scans.

### Returns
- **SandboxCheckTaskResponse** - Information about the analysis status.
```

--------------------------------

### GET /api/ui/v2/tasks/{scanId}/summary

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves information about a specific task.

```APIDOC
## GET /api/ui/v2/tasks/{scanId}/summary

### Description
Retrieves information about a specific task.

### Method
GET

### Endpoint
/api/ui/v2/tasks/{scanId}/summary

### Parameters
#### Path Parameters
- **scanId** (string) - Required - The unique identifier of the scan task.
```

--------------------------------

### Define bootkitmon_boot_timeout option

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Sets the maximum wait time for VM loading in seconds.

```python
bootkitmon_boot_timeout: NotRequired[int]
```

--------------------------------

### Storage and Threshold settings

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configuration for storage limits and component thresholds.

```python
bytes: int

```

```python
items: int

```

```python
bytes_percent: int = Field(alias='bytesPercent')

```

```python
items_percent: int = Field(alias='itemsPercent')

```

--------------------------------

### Metadata dictionary structure

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/ptsandbox

Example structure for the metadata dictionary used in scan requests.

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

--------------------------------

### Perform a Rescan Task

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/rescan

Demonstrates how to initialize a sandbox connection and execute a rescan task using trace and network logs.

```python
import asyncio
from pathlib import Path

from ptsandbox import Sandbox, SandboxKey


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_rescan(
        Path("./drakvuf-trace.log.zst"),
        Path("./tcpdump.pcap"),
    )

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


asyncio.run(main())
```

--------------------------------

### POST /analysis/checkTask

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves the results of a file analysis task that was previously started asynchronously.

```APIDOC
## POST /analysis/checkTask

### Description
Retrieves the results of a file analysis task, typically used for tasks started with the async_result parameter enabled.

### Method
POST

### Endpoint
/analysis/checkTask

### Parameters
#### Request Body
- **scan_id** (UUID) - Required - ID of the task
- **allow_preflight** (bool) - Optional - If set, an intermediate result with the is_preflight attribute will be returned for multi-stage scanning.

### Response
#### Success Response (200)
- **scan_id** (UUID) - ID of the created task
- **result** (SandboxResult | None) - The overall result of the check
- **is_preflight** (bool | None) - Indicates if the result is preliminary
```

--------------------------------

### GET /api/ui/v2/tasks/filter-values

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Retrieves possible values for filters based on sources and validation results.

```APIDOC
## GET /api/ui/v2/tasks/filter-values

### Description
Retrieves possible values for filters based on sources and validation results.

### Method
GET

### Endpoint
/api/ui/v2/tasks/filter-values
```

--------------------------------

### Retrieve System Settings

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Fetches the current system configuration settings.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    settings = await sandbox.ui.get_system_settings()
    print(settings)

asyncio.run(main())
```

--------------------------------

### Download System Logs

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Demonstrates how to stream and save system logs to a file using an asynchronous iterator.

```python
import aiofiles
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    async with aiofiles.open("logs.zip", "wb") as fd:
        async for chunk in sandbox.ui.get_system_logs(): 
            await fd.write(chunk)

asyncio.run(main())
```

--------------------------------

### Authorize UI API with SandboxKey

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/authorization

Initializes a SandboxKey with UI credentials and performs authorization.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

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

    sandbox = Sandbox(key)
    await sandbox.ui.authorize() 

asyncio.run(main())
```

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    key = SandboxKey(
        name="test-ui-1",
        key="", 
        host="10.10.10.10",
        ui=SandboxKey.UI(
            login="login",
            password="password",
        ),
    )

    sandbox = Sandbox(key)
    await sandbox.ui.authorize()
```

--------------------------------

### Download files using UI API

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/download-files

Demonstrates how to authorize and stream file chunks into a local ZIP file using a list of SHA256 hashes.

```python
import asyncio

import aiofiles

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


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    items: list[StorageItem] = [
        {"sha256": "..."},
        {"sha256": "...", "name": "..."}
    ]

    async with aiofiles.open("./artifacts.zip", "wb") as fd:
        async for chunk in sandbox.ui.get_files(items):
            await fd.write(chunk)
```

--------------------------------

### get_entry_point_logs

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Downloads the logs for a specific entry point as an asynchronous stream of bytes.

```APIDOC
## get_entry_point_logs

### Description
Downloads logs of a specific source as an archive.

### Signature
`get_entry_point_logs(entry_point_id: str) -> AsyncIterator[bytes]`

### Parameters
- **entry_point_id** (str) - Required - ID of entry point

### Returns
- **AsyncIterator[bytes]** - Archive with logs

### Exceptions
- **SandboxException** - If not authorized or token refresh fails
- **ClientResponseError** - If the server returns an error status
- **ClientError** - On connection or transport errors
```

--------------------------------

### Get task filter values

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Retrieves possible filter values for tasks. Requires an authorized Sandbox instance.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    values = await sandbox.ui.get_tasks_filter_values()
    print(values)

asyncio.run(main())
```

--------------------------------

### POST /analysis/createRetroTask

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Launches a retro analysis task using existing trace and network logs.

```APIDOC
## POST /analysis/createRetroTask

### Description
Allows launching a retro analysis task to scan with new drakvuf-trace.log.zst and tcpdump.pcap rules.

### Method
POST

### Endpoint
/analysis/createRetroTask

### Parameters
#### Request Body
- **file_uri** (str) - Required - The file URI received when uploading the file
- **raw_events_uri** (str) - Optional - Temporary URI of the raw trace file
- **raw_network_uri** (str) - Optional - Temporary URI of the network file
- **options** (Options) - Optional - Additional scanning options
```

--------------------------------

### Retrieve system version

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Fetches and prints the current system version. Requires an authorized sandbox session.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    version = await sandbox.ui.get_system_version()
    print(version)

asyncio.run(main())
```

--------------------------------

### Retrieve Entry Point Information

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Signature for fetching details about an analysis source by its ID.

```python
get_entry_point(
    entry_point_id: str,
) -> SandboxEntryPointResponse
```

--------------------------------

### Get Source Scan Status

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/ptsandbox

Checks the status of a scan initiated via the source API without retrieving the full report.

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

--------------------------------

### Define source options attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Source file resource settings.

```python
source_options: str | None = Field(
    default=None, alias="sourceOptions"
)
```

--------------------------------

### SandboxGetVersionResponse Attributes

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Product versioning information.

```python
version: str
```

```python
edition: str
```

--------------------------------

### Define incoming hosts attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

List of additional source IP addresses.

```python
incoming_hosts: list[str] | None = Field(
    default=None, alias="incomingHosts"
)
```

--------------------------------

### Download task artifacts

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Shows how to stream task artifacts from the sandbox and save them to a local file using aiofiles.

```python
import asyncio
import aiofiles
from uuid import UUID
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    async with aiofiles.open("artifacts.zip", "wb") as fd:
        async for chunk in sandbox.ui.get_task_artifacts(UUID("...")):
            await fd.write(chunk)

asyncio.run(main())
```

--------------------------------

### Retrieve license information

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/license

Fetches the current license details from the sandbox instance.

```python
import asyncio

from ptsandbox import Sandbox
from ptsandbox.models import SandboxKey


async def main():
    sandbox = Sandbox(SandboxKey(...))

    await sandbox.ui.authorize()

    license = await sandbox.ui.get_license()
    print(license)

asyncio.run(main())
```

--------------------------------

### Retrieve a task artifact tree

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/tasks

Demonstrates how to authorize the sandbox client and fetch the artifact tree for a specific task ID.

```python
import asyncio
from uuid import UUID
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    summary = await sandbox.ui.get_task_tree(UUID("..."))
    print(summary)

asyncio.run(main())
```

--------------------------------

### Access UI API with Authorization

Source: https://security-experts-community.github.io/py-ptsandbox

Configure UI credentials and authorize the session before accessing UI-specific system settings.

```python
import asyncio
from ptsandbox import Sandbox, SandboxKey

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

    async with Sandbox(key) as sandbox:
        # You must log in before using the UI API
        await sandbox.ui.authorize()
        print(await sandbox.ui.get_system_settings())

asyncio.run(main())
```

--------------------------------

### get_entry_point_tasks

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves a list of tasks for a specific entry point, supporting filtering, pagination, and time-based queries.

```APIDOC
## get_entry_point_tasks

### Description
Retrieves tasks associated with a specific entry point. Supports filtering via a query language, result limiting, and pagination.

### Signature
`get_entry_point_tasks(entry_point_id: str, query: str = "", limit: int = 20, offset: int = 0, utc_offset_seconds: int = 0, next_cursor: str | None = None) -> SandboxUITasksResponse`

### Parameters
- **entry_point_id** (str) - Required - ID of entry point
- **query** (str) - Optional - Filtering using the query language (default: "")
- **limit** (int) - Optional - Limit on the number of records to be returned (default: 20)
- **offset** (int) - Optional - The offset of the returned records (default: 0)
- **utc_offset_seconds** (int) - Optional - The offset of the user's time from UTC (default: 0)
- **next_cursor** (str) - Optional - Cursor for pagination

### Returns
- **SandboxUITasksResponse** - Information about requested tasks

### Exceptions
- **SandboxException** - If not authorized or token refresh fails
- **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
```

--------------------------------

### Configure Proxy for Sandbox

Source: https://security-experts-community.github.io/py-ptsandbox/usage/proxy

Pass the proxy URL to the Sandbox constructor to route traffic through a proxy server.

```python
from ptsandbox import Sandbox, SandboxKey

async def example() -> None:
    sandbox = Sandbox(
        key=SandboxKey(...),
        proxy="socks5://10.10.10.30"
    )
```

--------------------------------

### get_system_settings

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Retrieves the current system settings configuration.

```APIDOC
## get_system_settings()

### Description
Retrieves information about the current system settings.

### Signature
`async get_system_settings() -> SandboxSystemSettingsResponse`

### Returns
- **SandboxSystemSettingsResponse** - A model containing the system settings.

### Exceptions
- **SandboxException** - If not authorized or token refresh fails.
- **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_version()

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/system

Retrieves information about the product version.

```APIDOC
## get_version()

### Description
Retrieves information about the product version. Returns a `SandboxGetVersionResponse` object.

### Signature
`async def get_version() -> SandboxGetVersionResponse`

### Exceptions
- `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_entry_point

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves information about a specific analysis source entry point.

```APIDOC
## get_entry_point(entry_point_id: str)

### Description
Get information about the analysis source.

### Parameters
- **entry_point_id** (str) - Required - ID of entry point

### Returns
- **SandboxEntryPointResponse** - EntryPoint model

### Raises
- **SandboxException** - if not authorized or token refresh fails
- **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
```

--------------------------------

### Define use TLS attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Use TLS.

```python
use_tls: bool | None = Field(default=None, alias='useTls')
```

--------------------------------

### Create a standard scan

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/ptsandbox

Use this method to send a file to the sandbox for analysis. It supports custom rules, priority settings, and asynchronous result handling.

```python
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
```

--------------------------------

### Perform a default file scan

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/scan

Use this approach for standard file analysis with minimal configuration. Requires a valid SandboxKey and an asynchronous environment.

```python
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())
```

--------------------------------

### Configure Sandbox Options

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/scan

Attributes for defining behavioral analysis parameters.

```python
enabled: bool = True

```

```python
file_types: list[str] | None = None

```

```python
filter_by_properties: FilterProperties | None = None

```

--------------------------------

### Define SandboxImageInfo attributes

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configuration for VM image identification and OS details.

```python
image_id: str | None = Field(
    default=None,
    validation_alias=AliasChoices("image_id", "name", "id"),
)
```

```python
type: SandboxImageType | None = None
```

```python
version: str | None = None
```

```python
os: OS | None = None
```

--------------------------------

### Authentication Settings

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configures authentication policies for the sandbox.

```python
anonymous_deny: bool = Field(
    serialization_alias="anonymousDeny"
)
```

--------------------------------

### Configure Suspicious File Options

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Sets configuration for marking files as suspicious, defaulting to sandbox settings if None.

```python
mark_suspicious_files_options: (
    SuspiciousFilesOptions | None
) = None

```

--------------------------------

### Define ts_starting attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Represents the timestamp for recruitment attempts.

```python
ts_starting: float | None = Field(
    default=None, alias="tsStarting"
)
```

--------------------------------

### EntryPointRules Model Attributes

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configuration settings for entry point rules, including timeouts and notification settings.

```python
base_url: str | None = Field(default=None, alias='baseUrl')

```

```python
notify_destination: str | None = Field(
    default=None, alias="notifyDistention"
)

```

```python
locale: str | None = None

```

```python
quarantine: bool | None = None

```

```python
scan_timeout: int | None = Field(
    default=None, alias="scanTimeout"
)

```

```python
max_execution_time: int | None = Field(
    default=None, alias="maxExecutionTime"
)

```

```python
exclude_blocks: list[str] | None = Field(
    default=None, alias="excludeBlocks"
)

```

```python
max_unpack_level: int | None = Field(
    default=None, alias="maxUnpackLevel"
)

```

```python
notify_domains: list[str] | None = Field(
    default=None, alias="notifyDomains"
)

```

```python
notify_sender_message: str | None = Field(
    default=None, alias="notifySenderMessage"
)

```

--------------------------------

### Download artifacts by hash

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/download-files

Use download_artifact for small files or download_artifact_stream for memory-efficient streaming of large files.

```python
# Download as bytes
data = await sandbox.api.download_artifact("sha256:abc123...")

# Or stream to avoid loading into memory
async for chunk in sandbox.api.download_artifact_stream("sha256:abc123..."):
    ...
```

--------------------------------

### POST /storage/uploadScanFile

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Uploads a file to the sandbox storage to prepare it for analysis.

```APIDOC
## POST /storage/uploadScanFile

### Description
Uploads a file to the sandbox storage to prepare it for analysis. This must be called before creating a scan task.

### Method
POST

### Endpoint
<URL>/storage/uploadScanFile

### Response
#### Success Response (200)
- **file_uri** (str) - The ID of the uploaded file, used to create the analysis task.
- **ttl** (int) - The waiting time for the scan to start after uploading the file (in seconds).
```

--------------------------------

### Storage Component Settings

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Defines storage limits for components.

```python
bytes: int | None = None
```

```python
items: int | None = None
```

--------------------------------

### POST /analysis/createBAScanTask

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Initiates a behavioral analysis task for a file that has already been uploaded to the system.

```APIDOC
## POST /analysis/createBAScanTask

### Description
Starts the analysis process for a file previously uploaded to the product.

### Method
POST

### Endpoint
/analysis/createBAScanTask

### Parameters
#### Request Body
- **file_uri** (str) - Required - The file URI received when uploading the file
- **sandbox** (SandboxOptionsAdvanced) - Optional - Additional advanced scanning options
- **file_name** (str) - Optional - The name of the file to be checked
- **short_result** (bool) - Optional - Return only the overall result of the check
- **async_result** (bool) - Optional - Return only the scan_id
- **priority** (int) - Optional - The priority of the task (1-4)
```

--------------------------------

### source_check_file

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/source

Sends a file to the sandbox for analysis with source settings.

```APIDOC
## source_check_file(file, data, read_timeout=240)

### Description
Sends a file to the sandbox for analysis with source settings.

### Parameters
- **file** (str | Path | bytes | BinaryIO) - Required - The file to be sent for analysis.
- **data** (SandboxScanWithSourceFileRequest) - Required - Request parameters in model.
- **read_timeout** (int) - Optional (default: 240) - Response waiting time in seconds.

### Returns
- **SandboxBaseTaskResponse** - The task response object.

### Raises
- **SandboxException** - If incorrect arguments are passed.
- **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.
```

--------------------------------

### Interact with Sandbox instance

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/ptsandbox

Methods and properties for managing the main Sandbox client connection.

```python
ui: SandboxUI
```

```python
has_ui: bool
```

```python
close() -> None
```

--------------------------------

### Quarantine settings

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configuration for quarantine storage duration and SMTP forwarding.

```python
retention_period: int = Field(alias='retentionPeriod')

```

```python
use_smtp: bool = Field(alias='useSMTP')

```

```python
smtp_default_records: list[SMTPDefaultRecord] = Field(
    alias="smtpDefaultRecords"
)

```

--------------------------------

### Define License Model Fields

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Configuration fields for AV license requirements.

```python
extensions: list[str] = Field(default_factory=list[str])
```

```python
multiple: bool = False
```

--------------------------------

### get_entry_points

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves a list of currently added sources available for analysis.

```APIDOC
## get_entry_points()

### Description
Get a list of added sources for analysis.

### Signature
`async get_entry_points() -> SandboxEntryPointsResponse`

### Returns
- **SandboxEntryPointsResponse**: EntryPoints model.

### Exceptions
- **SandboxException**: If not authorized or token refresh fails.
- **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.
```

--------------------------------

### Define ts_ready attribute

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Represents the readiness timestamp.

```python
ts_ready: float | None = Field(
    default=None, alias="tsReady"
)
```

--------------------------------

### get_system_version

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/system

Retrieves the current version of the system.

```APIDOC
## get_system_version()

### Description
Fetches the current system version string.

### Signature
`async get_system_version() -> str`
```

--------------------------------

### Define Scan Configuration Rules

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Sets up the list of custom detection rules for the scan configuration.

```python
rules: list[FileRule | FileInverseRule | URLRule] = Field(
    default_factory=list[
        FileRule | FileInverseRule | URLRule
    ]
)
```

--------------------------------

### Create and Wait for Scan Report

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/scan

Initiates a scan and polls the sandbox until the full report is available.

```python
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)
```

--------------------------------

### SandboxOptions Configuration

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Settings for behavioral analysis, including file type filtering.

```python
enabled: bool = True
```

```python
file_types: list[str] | None = None
```

```python
filter_by_properties: FilterProperties | None = None
```

--------------------------------

### get_license()

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/license

Retrieves the current license status and details.

```APIDOC
## get_license()

### Description
Retrieves the license status and details from the system.

### Signature
`async get_license() -> SandboxLicenseResponse`

### Exceptions
- `SandboxException`: If not authorized or token refresh fails.
- `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.
```

--------------------------------

### Enable bootkit monitoring

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Toggles the execution of bootkit monitoring during the analysis process.

```python
bootkitmon: bool = False
```

--------------------------------

### Check UI availability

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/sandbox

Indicates whether UI credentials were provided in the SandboxKey.

```python
has_ui: bool
```

--------------------------------

### Export artifacts to CSV

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/artifacts

Demonstrates how to authorize and stream artifact data into a local CSV file using an asynchronous context manager.

```python
import asyncio
import aiofiles
from ptsandbox import Sandbox, SandboxKey

async def main():
    sandbox = Sandbox(...)
    await sandbox.ui.authorize()

    async with aiofiles.open("./tasks.csv", "wb") as fd:
        async for chunk in sandbox.ui.get_artifacts_csv():
            await fd.write(chunk)

asyncio.run(main())
```

--------------------------------

### get_entry_points_types

Source: https://security-experts-community.github.io/py-ptsandbox/usage/ui-api/entry-points

Retrieves a list of possible sources that can be checked, along with their required parameters.

```APIDOC
## get_entry_points_types()

### Description
Retrieves a list of possible sources to check with their parameters.

### Signature
`async get_entry_points_types() -> SandboxEntryPointsTypesResponse`

### Returns
- **SandboxEntryPointsTypesResponse**: List of possible sources.

### Exceptions
- **SandboxException**: If not authorized or token refresh fails.
- **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.
```

--------------------------------

### EntryPoint Model Attributes

Source: https://security-experts-community.github.io/py-ptsandbox/api-reference/models

Fields defining the origin and status of a task.

```python
id: str
```

```python
type: EntryPointType
```

```python
status: EntryPointStatus
```

```python
action: EntryPointAction
```

```python
quarantine: Quarantine
```

```python
client_ip: str = Field(alias='clientIp')
```

```python
check_me: CheckMe | None = None
```

--------------------------------

### Configure File Type Extension

Source: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/scanning/debug-options

Enables using the detected file type as the file extension.

```text
file_type_as_ext: NotRequired[bool]
```
Tokens:
Raw