Skip to content

Entry Points

You can manage sources using the API.

Note

This API is not yet stable and may change in the future.

Get a list of possible sources to check with their parameters

Code example
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())

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.get_entry_points_types async 

get_entry_points_types() -> SandboxEntryPointsTypesResponse

Get a list of possible sources to check with their parameters

Returns:

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 a list of added sources for verification

Code example
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())

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.get_entry_points async 

get_entry_points() -> SandboxEntryPointsResponse

Get a list of added sources for analysis

Returns:

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

Create a new source

Warning

Creating a new source requires special configuration. Not all parameters may be suitable for each source type.

Study the documentation, or inspect the required parameters using browser dev tools.

Code example
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())

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.create_entry_point async 

create_entry_point(
    parameters: SandboxCreateEntryPointRequest,
) -> None

Add a new analysis source

Parameters:

Raises:

  • SandboxException –

    if not authorized or token refresh fails

  • ClientResponseError –

    if the server returns an error status

  • ClientError –

    on connection or transport errors

Get full information about a specific source

Code example
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())

Get info about all sources on system

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

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.get_entry_point async 

get_entry_point(
    entry_point_id: str,
) -> SandboxEntryPointResponse

Get information about the analysis source

Parameters:

  • entry_point_id (str) –

    ID of entry point

Returns:

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

Remove the source from the system

Code example
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())

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.delete_entry_point async 

delete_entry_point(entry_point_id: str) -> None

Delete the analysis source

Parameters:

  • entry_point_id (str) –

    ID of entry point

Raises:

  • SandboxException –

    if not authorized or token refresh fails

  • ClientResponseError –

    if the server returns an error status

  • ClientError –

    on connection or transport errors

Get a list of tasks from a specific source

Code example
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())

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.get_entry_point_tasks async 

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

Listing tasks from the source

Parameters:

  • entry_point_id (str) –

    ID of entry point

  • 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

  • offset (int, default: 0 ) –

    The offset of the returned records. If the next Cursor is specified, the offset from the cursor is

  • 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

Returns:

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

Download logs from the source

Code example
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("..."): # (1)!
            await fd.write(chunk)

asyncio.run(main())
  1. Log sizes can reach several gigabytes. The response is an async iterator to avoid loading everything into memory.

ptsandbox.sandbox.ui._entry_points.EntryPointsMixin.get_entry_point_logs async 

get_entry_point_logs(
    entry_point_id: str,
) -> AsyncIterator[bytes]

Download logs of a specific source

Parameters:

  • entry_point_id (str) –

    ID of entry point

Returns:

  • AsyncIterator[bytes] –

    Archive with logs

Raises:

  • SandboxException –

    if not authorized or token refresh fails

  • ClientResponseError –

    if the server returns an error status

  • ClientError –

    on connection or transport errors