sandbox-cli 0.2.26__py3-none-any.whl

sandbox_cli/__main__.py

@@ -0,0 +1,28 @@
+import sys
+from http import HTTPStatus
+
+import aiohttp
+import aiohttp.client_exceptions
+
+from sandbox_cli.cli import app
+from sandbox_cli.console import console
+
+
+def main() -> None:
+    if sys.platform == "win32":
+        import asyncio
+
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+    try:
+        app()
+    except aiohttp.client_exceptions.ClientResponseError as e:
+        # global handler for 401 error
+        if e.status == HTTPStatus.UNAUTHORIZED:
+            console.error(f"The specified token is not valid. {e}")
+    except Exception:
+        console.print_exception()
+
+
+if __name__ == "__main__":
+    main()

sandbox_cli/cli/__init__.py

@@ -0,0 +1,46 @@
+"""
+Register all commands here
+"""
+
+from cyclopts import App
+
+from sandbox_cli.cli.reporter import generate_report
+from sandbox_cli.cli.unpack import unpack_logs
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import configpath, settings
+
+
+def get_version() -> str:
+    import importlib.metadata
+
+    version = importlib.metadata.version("sandbox-cli")
+    return f"sandbox-cli {version}"
+
+
+app = App(
+    name="sandbox-cli",
+    help="Work with sandbox like a pro"
+    + (
+        f"\n\nTo access other commands, specify at least one sandbox in the config at **{configpath}**"
+        if len(settings.sandbox_keys) == 0
+        else ""
+    ),
+    help_format="markdown",
+    version=get_version,
+    console=console,
+)
+
+app.command(name=["conv", "unpack"])(unpack_logs)
+app.command(name="report")(generate_report)
+
+if len(settings.sandbox_keys) > 0:
+    from sandbox_cli.cli.downloader import download_command, download_email
+    from sandbox_cli.cli.images import get_images
+    from sandbox_cli.cli.rules import rules
+    from sandbox_cli.cli.scanner import scanner
+
+    app.command(scanner)
+    app.command(rules)
+    app.command(name="images")(get_images)
+    app.command(name="download")(download_command)
+    app.command(name="email")(download_email)

sandbox_cli/cli/downloader.py

@@ -0,0 +1,308 @@
+import asyncio
+from collections.abc import Coroutine
+from http import HTTPStatus
+from pathlib import Path
+from typing import Annotated, Any
+from urllib.parse import urlparse
+from uuid import UUID
+
+import aiofiles
+import aiohttp
+import aiohttp.client_exceptions
+from cyclopts import Parameter
+from ptsandbox import Sandbox
+from ptsandbox.models import Artifact, SandboxBaseTaskResponse
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import settings
+from sandbox_cli.internal.helpers import (
+    get_key_by_name,
+    get_sandbox_key_by_host,
+    validate_key,
+)
+from sandbox_cli.utils.downloader import download
+from sandbox_cli.utils.unpack import Unpack
+
+
+def get_key_and_task(key: str, task: str) -> tuple[Sandbox, UUID] | tuple[None, None]:
+    try:
+        uuid = UUID(task)
+        sandbox_key = get_key_by_name(key)
+        return Sandbox(sandbox_key), uuid
+    except ValueError:
+        url = urlparse(task)
+        if not (url.scheme and url.path and "/tasks" in url.path):
+            console.warning(f"Invalid task_id: {task}")
+            return None, None
+
+        try:
+            uuid = UUID(url.path.split("/")[2])
+            sandbox_key = get_sandbox_key_by_host(url.hostname or "")
+            return Sandbox(sandbox_key), uuid
+        except ValueError:
+            console.error(f"Invalid task id: {task}")
+            return None, None
+
+
+async def download_command(
+    tasks_id: Annotated[
+        list[str],
+        Parameter(
+            help="Links to tasks or task ids",
+            negative="",
+            required=True,
+        ),
+    ],
+    /,
+    *,
+    key: Annotated[
+        str,
+        Parameter(
+            name=["--key", "-k"],
+            help=f"The key to access the sandbox **{'**,**'.join(x.name for x in settings.sandbox_keys)}**",
+            validator=validate_key,
+            group="Sandbox",
+        ),
+    ] = settings.sandbox_keys[0].name,
+    out_dir: Annotated[
+        Path,
+        Parameter(
+            name=["--out", "-o"],
+            help="Output directory",
+        ),
+    ] = Path("./downloads"),
+    decompress: Annotated[
+        bool,
+        Parameter(
+            name=["--decompress", "-D"],
+            help="Decompress downloaded files",
+            negative="",
+        ),
+    ] = False,
+    unpack: Annotated[
+        bool,
+        Parameter(
+            name=["--unpack", "-U"],
+            help="Unpack downloaded files",
+            negative="",
+        ),
+    ] = False,
+    all: Annotated[
+        bool,
+        Parameter(
+            name=["--all", "-a"],
+            help="Download all artifacts",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    debug: Annotated[
+        bool,
+        Parameter(
+            name=["--debug", "-d"],
+            help="Download debug artifacts",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    artifacts: Annotated[
+        bool,
+        Parameter(
+            name=["--artifacts", "-A"],
+            help="Download artifacts",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    files: Annotated[
+        bool,
+        Parameter(
+            name=["--files", "-f"],
+            help="Download files",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    crashdumps: Annotated[
+        bool,
+        Parameter(
+            name=["--crashdumps", "-c"],
+            help="Download crashdumps (maybe be more 1GB)",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    procdumps: Annotated[
+        bool,
+        Parameter(
+            name=["--procdumps", "-p"],
+            help="Download procdumps",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    video: Annotated[
+        bool,
+        Parameter(
+            name=["--video", "-v"],
+            help="Download video",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+    logs: Annotated[
+        bool,
+        Parameter(
+            name=["--logs", "-l"],
+            help="Download logs",
+            negative="",
+            group="Download options",
+        ),
+    ] = False,
+) -> None:
+    """
+    Download any artifact from the sandbox.
+    """
+
+    async def worker(
+        report: SandboxBaseTaskResponse.LongReport,
+        sandbox: Sandbox,
+        out_dir: Path,
+        all: bool = False,
+        artifacts: bool = False,
+        crashdumps: bool = False,
+        debug: bool = False,
+        decompress: bool = False,
+        files: bool = False,
+        logs: bool = False,
+        procdumps: bool = False,
+        video: bool = False,
+        progress: Progress | None = None,
+    ) -> None:
+        await download(
+            report=report,
+            sandbox=sandbox,
+            out_dir=out_dir,
+            all=all,
+            debug=debug,
+            artifacts=artifacts,
+            files=files,
+            crashdumps=crashdumps,
+            procdumps=procdumps,
+            video=video,
+            logs=logs,
+            decompress=decompress,
+            progress=progress,
+        )
+
+        if unpack and out_dir.exists():
+            Unpack(out_dir).run()
+
+    progress = Progress(
+        SpinnerColumn(),
+        TextColumn("{task.description}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    )
+
+    tasks: list[Coroutine[Any, Any, Artifact.EngineResult | None]] = []
+
+    for task in tasks_id:
+        sandbox, task_id = get_key_and_task(key, task)
+        if not sandbox or not task_id:
+            continue
+
+        try:
+            result = await sandbox.get_report(task_id=task_id)
+        except aiohttp.client_exceptions.ClientResponseError as e:
+            if e.status == HTTPStatus.NOT_FOUND:
+                console.warning(
+                    f"The report cannot be accessed from {task_id}.\n"
+                    "Read more about it in: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/download-files/"
+                )
+            continue
+
+        if (report := result.get_long_report()) is None:
+            console.warning(
+                f"The report cannot be accessed from {task_id}.\n"
+                "Read more about it in: https://security-experts-community.github.io/py-ptsandbox/usage/public-api/download-files/"
+            )
+            continue
+
+        tasks.append(
+            worker(
+                report=report,
+                sandbox=sandbox,
+                out_dir=out_dir / str(task_id),
+                all=all,
+                debug=debug,
+                artifacts=artifacts,
+                files=files,
+                crashdumps=crashdumps,
+                procdumps=procdumps,
+                video=video,
+                logs=logs,
+                decompress=decompress,
+                progress=progress,
+            )
+        )
+
+    with progress:
+        await asyncio.gather(*tasks)
+
+
+def download_email(
+    emails: Annotated[
+        list[Path],
+        Parameter(
+            help="The path to the email files",
+        ),
+    ],
+    /,
+    *,
+    out_dir: Annotated[
+        Path,
+        Parameter(
+            name=["--out", "-o"],
+            help="Output directory",
+        ),
+    ] = Path("./downloads"),
+    key: Annotated[
+        str,
+        Parameter(
+            name=["--key", "-k"],
+            help=f"The key to access the sandbox **{'**,**'.join(x.name for x in settings.sandbox_keys)}**",
+            validator=validate_key,
+            group="Sandbox",
+        ),
+    ] = settings.sandbox_keys[0].name,
+) -> None:
+    """
+    Upload an email and get its headers.
+    """
+
+    # some path prepartions
+    out_dir.mkdir(exist_ok=True, parents=True)
+    out_dir = out_dir.expanduser().resolve()
+
+    async def _func(out_dir: Path) -> None:
+        sandbox = Sandbox(get_key_by_name(key))
+
+        async def _internal(email: Path, out_dir: Path) -> None:
+            async with aiofiles.open(out_dir / f"{email}.headers", "wb") as fd:
+                async for chunk in sandbox.get_email_headers(email):
+                    await fd.write(chunk)
+
+        # small validation
+        files: list[Path] = []
+        for email in emails:
+            if not email.exists():
+                console.warning(f"{email} doesn't exists")
+                continue
+            files.append(email)
+
+        await asyncio.gather(*(_internal(email, out_dir) for email in files))
+
+    asyncio.run(_func(out_dir))

sandbox_cli/cli/images.py

@@ -0,0 +1,45 @@
+from typing import Annotated
+
+from cyclopts import Parameter
+from ptsandbox import Sandbox
+from rich.table import Table
+
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import settings
+from sandbox_cli.internal.helpers import get_key_by_name, validate_key
+
+
+async def get_images(
+    *,
+    key: Annotated[
+        str,
+        Parameter(
+            name=["--key", "-k"],
+            help=f"The key to access the sandbox **{'**,**'.join(x.name for x in settings.sandbox_keys)}**",
+            validator=validate_key,
+            group="Sandbox",
+        ),
+    ] = settings.sandbox_keys[0].name,
+) -> None:
+    """
+    Get available images in the sandbox.
+    """
+
+    sandbox = Sandbox(get_key_by_name(key))
+    images = await sandbox.get_images()
+
+    table = Table()
+    table.add_column("Name")
+    table.add_column("Image ID", style="turquoise2")
+    table.add_column("Version")
+    table.add_column("Product version")
+    table.add_column("Locale")
+
+    for image in images:
+        if not image.os:
+            console.warning(f"{image.image_id} doesn't contain OS information")
+            continue
+
+        table.add_row(image.os.name, image.image_id, image.os.version, image.version, image.os.locale)
+
+    console.print(table)

sandbox_cli/cli/reporter.py

@@ -0,0 +1,146 @@
+import datetime
+import gzip
+import textwrap
+from pathlib import Path
+from typing import Annotated, Literal, TypedDict
+
+from cyclopts import Parameter
+from ptsandbox.models import SandboxBaseTaskResponse
+from rich.table import Table
+
+from sandbox_cli.console import console
+from sandbox_cli.utils.extractors import (
+    extract_memory,
+    extract_network_from_trace,
+    extract_static,
+    extract_verdict_from_trace,
+)
+
+
+class TableData(TypedDict):
+    sample: str
+    image: str
+    sandbox: str
+    verdict: str
+    static: str
+    memory: str
+    network: str
+
+
+def generate_report(
+    src: Annotated[
+        list[Path],
+        Parameter(
+            help="Folder(s) with sandbox reports (recursive search will be used)",
+        ),
+    ],
+    /,
+    *,
+    mode: Annotated[
+        Literal["cli", "md"],
+        Parameter(
+            name=["--mode", "-m"],
+            help="Report output format",
+        ),
+    ] = "cli",
+    latest: Annotated[
+        bool,
+        Parameter(
+            name=["--latest", "-l"],
+            help="Reports created in the last 2 hours",
+            negative="",
+        ),
+    ] = False,
+) -> None:
+    """
+    Generate short report from sandbox scans.
+    """
+
+    data: list[TableData] = []
+    match mode:
+        case "md":
+            delimeter = " "
+        case _:
+            delimeter = "\n"
+
+    for directory in src:
+        for root in directory.rglob("*"):
+            if not root.is_dir():
+                continue
+
+            report_file = root / "report.json"
+            if not report_file.exists():
+                continue
+
+            if latest and (
+                datetime.datetime.now() - datetime.datetime.fromtimestamp(report_file.stat().st_mtime)
+            ) > datetime.timedelta(hours=2):
+                continue
+
+            with open(report_file, encoding="utf-8") as fd:
+                report_data = fd.read()
+                scan_data = SandboxBaseTaskResponse.model_validate_json(report_data)
+
+            if (report := scan_data.get_long_report()) is None:
+                console.warning(f"A report without behavioral analysis: {root}")
+                continue
+
+            corr_trace_path = root / "events-correlated.log.gz"
+            if not corr_trace_path.exists():
+                corr_trace_path = root / "raw" / "events-correlated.log.gz"
+
+            if not corr_trace_path.exists():
+                console.error(f"Can't find events-correlated.log.gz: {root}")
+                continue
+
+            corr_trace = gzip.open(corr_trace_path, "rb").read()
+            image = root.name
+            try:
+                image = report.artifacts[0].find_sandbox_result().details.sandbox.image.image_id  # type: ignore
+            finally:
+                if image is None:
+                    image = root.name
+
+            data.append(
+                {
+                    "sample": report.artifacts[0].file_info.file_path,  # type: ignore
+                    "image": image,
+                    "verdict": delimeter.join(extract_verdict_from_trace(corr_trace)),
+                    "static": delimeter.join(extract_static(report)),
+                    "memory": delimeter.join(extract_memory(report)),
+                    "network": delimeter.join(extract_network_from_trace(corr_trace)),
+                }
+            )
+
+    match mode:
+        case "md":
+            md_report_head = textwrap.dedent(
+                """
+            | Sample | Image | Verdict | Static | Memory | Network |
+            | --- | --- | --- | --- | --- | --- |"""
+            ).strip()
+
+            md_report_base = "|{sample}|{image}|{verdict}|{static}|{memory}|{network}|"
+            table_md = md_report_head + "\n"
+            table_md += "\n".join(md_report_base.format(**d) for d in data)
+            print(table_md)
+        case "cli":
+            table = Table(highlight=True, show_lines=True)
+            table.add_column("File", overflow="fold")
+            table.add_column("Image", overflow="fold")
+            table.add_column("Verdict", overflow="fold", style="bold")
+            table.add_column("Static", overflow="fold", style="bold")
+            table.add_column("Memory", overflow="fold")
+            table.add_column("Network", overflow="fold")
+            for d in data:
+                table.add_row(
+                    d["sample"],
+                    d["image"],
+                    d["verdict"],
+                    d["static"],
+                    d["memory"],
+                    d["network"],
+                )
+            console.print(table)
+        case _:
+            pass

sandbox_cli/cli/rules/__init__.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Parameter, validators
+
+from sandbox_cli.console import console
+from sandbox_cli.utils.compiler import compile_rules_internal, test_rules_internal
+
+rules = App(
+    name="rules",
+    help="Working with raw sandbox rules.",
+    help_format="markdown",
+)
+
+
+@rules.command(name="compile")
+async def compile_rules(
+    *,
+    rules: Annotated[
+        Path,
+        Parameter(
+            name=["--rules", "-r"],
+            help="The path to the folder with the rules",
+            validator=validators.Path(exists=True),
+        ),
+    ],
+    out: Annotated[
+        Path,
+        Parameter(
+            name=["--out", "-o"],
+            help="The path where to save the compiled rules",
+            required=False,
+        ),
+    ] = Path("compiled-rules.local.tmp"),
+    is_local: Annotated[
+        bool,
+        Parameter(
+            name=["--local", "-l"],
+            negative="",
+            help="The rules will be compiled locally using Docker (unix only)",
+        ),
+    ] = False,
+) -> None:
+    """
+    Get compiled rules for working with third-party services.
+    """
+
+    out.mkdir(exist_ok=True, parents=True)
+    out = out.expanduser().resolve()
+
+    with console.status(f"{console.INFO} Waiting for the rules to be compiled"):
+        data = await compile_rules_internal(rules_dir=rules, is_local=is_local, compiled_rules_dir=out)
+        (out / "compiled-rules.local.tar.gz").write_bytes(data)
+
+    console.info(f"Rules saved to {out / 'compiled-rules.local.tar.gz'}")
+
+
+@rules.command(name="test")
+async def test_rules(
+    *,
+    rules: Annotated[
+        Path,
+        Parameter(
+            name=["--rules", "-r"],
+            help="The path to the folder with the rules",
+            validator=validators.Path(exists=True),
+        ),
+    ],
+    is_local: Annotated[
+        bool,
+        Parameter(
+            name=["--local", "-l"],
+            negative="",
+            help="The rules will be compiled locally using Docker (unix only)",
+        ),
+    ] = False,
+) -> None:
+    """
+    Testing written rules.
+    """
+
+    with console.status(f"{console.INFO} Testing rules"):
+        await test_rules_internal(rules=rules, is_local=is_local)