Artifacts

Export artifacts data and get filter values for artifact queries.

Export in csv

Code example

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

ptsandbox.sandbox.ui._artifacts.ArtifactsMixin.get_artifacts_csv async

get_artifacts_csv(
    query: str = "",
    columns: list[
        Literal[
            "behavioralAnalysis",
            "bwListStatus",
            "createProcess",
            "detects.avast",
            "detects.clamav",
            "detects.drweb",
            "detects.eset",
            "detects.kaspersky",
            "detects.nano",
            "detects.ptesc",
            "detects.ptav",
            "detects.vba",
            "detects.yara",
            "detects.yara.test",
            "emlBcc",
            "emlCC",
            "emlFrom",
            "emlTo",
            "fileExtensionTypeGroup",
            "fileLabels",
            "fileMd5",
            "fileName",
            "fileSha1",
            "fileSha256",
            "fileSize",
            "fileType",
            "fromTo",
            "imageDuration",
            "imageName",
            "mimeType",
            "nodeType",
            "priority",
            "receivedFrom",
            "ruleEngineDetects",
            "ruleEngineVerdict",
            "sandboxBehavioral",
            "sandboxBootkitmon",
            "sandboxDetects",
            "sandboxVerdict",
            "smtpFrom",
            "smtpTo",
            "source",
            "ssdeep",
            "status",
            "subject",
            "taskId",
            "time",
            "verdict",
            "verdict.avast",
            "verdict.clamav",
            "verdict.drweb",
            "verdict.eset",
            "verdict.kaspersky",
            "verdict.nano",
            "verdict.ptesc",
            "verdict.ptav",
            "verdict.vba",
            "verdict.yara",
            "verdict.yara.test",
            "verdictPriority",
            "verdictReason",
        ]
    ]
    | None = None,
    utc_offset_seconds: int = 0,
) -> AsyncIterator[bytes]

Export an artifacts listing to CSV

Parameters:

• query (str, default: '' ) –

  filtering using the query language. For the syntax, see the user documentation.

• columns (list[Literal['behavioralAnalysis', 'bwListStatus', 'createProcess', 'detects.avast', 'detects.clamav', 'detects.drweb', 'detects.eset', 'detects.kaspersky', 'detects.nano', 'detects.ptesc', 'detects.ptav', 'detects.vba', 'detects.yara', 'detects.yara.test', 'emlBcc', 'emlCC', 'emlFrom', 'emlTo', 'fileExtensionTypeGroup', 'fileLabels', 'fileMd5', 'fileName', 'fileSha1', 'fileSha256', 'fileSize', 'fileType', 'fromTo', 'imageDuration', 'imageName', 'mimeType', 'nodeType', 'priority', 'receivedFrom', 'ruleEngineDetects', 'ruleEngineVerdict', 'sandboxBehavioral', 'sandboxBootkitmon', 'sandboxDetects', 'sandboxVerdict', 'smtpFrom', 'smtpTo', 'source', 'ssdeep', 'status', 'subject', 'taskId', 'time', 'verdict', 'verdict.avast', 'verdict.clamav', 'verdict.drweb', 'verdict.eset', 'verdict.kaspersky', 'verdict.nano', 'verdict.ptesc', 'verdict.ptav', 'verdict.vba', 'verdict.yara', 'verdict.yara.test', 'verdictPriority', 'verdictReason']] | None, default: None ) –

  the list of csv columns to be exported.

• 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:

• AsyncIterator[bytes] –

  AsyncIterator with chunks of CSV file

Raises:

• SandboxException –

  if not authorized or token refresh fails

• ClientResponseError –

  if the server returns an error status

• ClientError –

  on connection or transport errors

Get filter values

Code example

import asyncio
from ptsandbox import Sandbox, SandboxKey

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

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

asyncio.run(main())

ptsandbox.sandbox.ui._artifacts.ArtifactsMixin.get_artifacts_filter_values async

get_artifacts_filter_values(
    from_: str = "",
    to: str = "",
    scan_id: UUID | None = None,
) -> SandboxArtifactsFilterValuesResponse

Get possible values for filters based on sources and validation results

Parameters:

• from_ (str, default: '' ) –

  for which period possible values are being searched: minimum time

• to (str, default: '' ) –

  for which period possible values are being searched: maximum time

• scan_id (UUID | None, default: None ) –

  filter by task ID

Returns:

• SandboxArtifactsFilterValuesResponse –

  Possible filter values

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