sandbox-cli 0.2.29__tar.gz → 0.2.30__tar.gz

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sandbox-cli
-Version: 0.2.29
+Version: 0.2.30
 Summary: Command line tool for interaction with sandboxes
 Project-URL: Homepage, https://github.com/Security-Experts-Community/sandbox-cli
 Project-URL: Documentation, https://security-experts-community.github.io/sandbox-cli
@@ -12,13 +12,13 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.11
 Requires-Dist: aiofiles>=24.1.0
-Requires-Dist: asyncssh>=2.19.0
-Requires-Dist: cryptography>=44.0.0
-Requires-Dist: cyclopts>=3.9.0
+Requires-Dist: asyncssh>=2.20.0
+Requires-Dist: cryptography>=44.0.2
+Requires-Dist: cyclopts>=3.12.0
 Requires-Dist: docker>=7.1.0
 Requires-Dist: ptsandbox>=5.0.0
 Requires-Dist: pyzipper>=0.3.6
-Requires-Dist: rich>=13.9.4
+Requires-Dist: rich>=14.0.0
 Requires-Dist: zstandard>=0.23.0
 Description-Content-Type: text/markdown
 

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sandbox-cli"
-version = "0.2.29"
+version = "0.2.30"
 description = "Command line tool for interaction with sandboxes"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,13 +9,13 @@ license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "Alexey Kolesnikov" }]
 dependencies = [
   "aiofiles>=24.1.0",
-  "asyncssh>=2.19.0",
-  "cryptography>=44.0.0",
-  "cyclopts>=3.9.0",
+  "asyncssh>=2.20.0",
+  "cryptography>=44.0.2",
+  "cyclopts>=3.12.0",
   "docker>=7.1.0",
   "ptsandbox>=5.0.0",
   "pyzipper>=0.3.6",
-  "rich>=13.9.4",
+  "rich>=14.0.0",
   "zstandard>=0.23.0",
 ]
 

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/cli/__init__.py

@@ -4,7 +4,7 @@ Register all commands here
 
 from cyclopts import App
 
-from sandbox_cli.cli.reporter import generate_report
+from sandbox_cli.cli.reporter import generate_report, open_browser
 from sandbox_cli.cli.unpack import unpack_logs
 from sandbox_cli.console import console
 from sandbox_cli.internal.config import configpath, settings
@@ -32,6 +32,7 @@ app = App(
 
 app.command(name=["conv", "unpack"])(unpack_logs)
 app.command(name="report")(generate_report)
+app.command(name="browser")(open_browser)
 
 if len(settings.sandbox_keys) > 0:
     from sandbox_cli.cli.downloader import download_command, download_email

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/cli/reporter.py

@@ -9,6 +9,8 @@ from ptsandbox.models import SandboxBaseTaskResponse
 from rich.table import Table
 
 from sandbox_cli.console import console
+from sandbox_cli.internal.helpers import format_link, get_key_by_name, open_link
+from sandbox_cli.models.sandbox_arguments import SandboxArguments
 from sandbox_cli.utils.extractors import (
     extract_memory,
     extract_network_from_trace,
@@ -72,6 +74,10 @@ def generate_report(
             if not report_file.exists():
                 continue
 
+            scan_config_file = root / "scan_config.json"
+            if not scan_config_file.exists():
+                continue
+
             if latest and (
                 datetime.datetime.now() - datetime.datetime.fromtimestamp(report_file.stat().st_mtime)
             ) > datetime.timedelta(hours=2):
@@ -81,6 +87,10 @@ def generate_report(
                 report_data = fd.read()
                 scan_data = SandboxBaseTaskResponse.model_validate_json(report_data)
 
+            with open(scan_config_file, encoding="utf-8") as fd:
+                scan_config_data = fd.read()
+                scan_config = SandboxArguments.model_validate_json(scan_config_data)
+
             if (report := scan_data.get_long_report()) is None:
                 console.warning(f"A report without behavioral analysis: {root}")
                 continue
@@ -101,6 +111,9 @@ def generate_report(
                 if image is None:
                     image = root.name
 
+            key = get_key_by_name(scan_config.sandbox_key_name)
+            link = format_link(scan_data, key=key)
+
             data.append(
                 {
                     "sample": report.artifacts[0].file_info.file_path,  # type: ignore
@@ -109,6 +122,7 @@ def generate_report(
                     "static": delimeter.join(extract_static(report)),
                     "memory": delimeter.join(extract_memory(report)),
                     "network": delimeter.join(extract_network_from_trace(corr_trace)),
+                    "sandbox": link,
                 }
             )
 
@@ -116,8 +130,8 @@ def generate_report(
         case "md":
             md_report_head = textwrap.dedent(
                 """
-            | Sample | Image | Verdict | Static | Memory | Network |
-            | --- | --- | --- | --- | --- | --- |"""
+            | Sample | Image | Verdict | Static | Memory | Network | Sandbox |
+            | --- | --- | --- | --- | --- | --- | --- |"""
             ).strip()
 
             md_report_base = "|{sample}|{image}|{verdict}|{static}|{memory}|{network}|"
@@ -132,6 +146,8 @@ def generate_report(
             table.add_column("Static", overflow="fold", style="bold")
             table.add_column("Memory", overflow="fold")
             table.add_column("Network", overflow="fold")
+            table.add_column("Sandbox", overflow="fold")
+
             for d in data:
                 table.add_row(
                     d["sample"],
@@ -140,7 +156,44 @@ def generate_report(
                     d["static"],
                     d["memory"],
                     d["network"],
+                    d["sandbox"],
                 )
             console.print(table)
         case _:
             pass
+
+
+def open_browser(
+    path: Annotated[
+        Path,
+        Parameter(
+            help="Folder with sandbox report (report.json and scan_config.json)",
+        ),
+    ] = Path(),
+) -> None:
+    """
+    Open sandbox link in the default browser.
+    """
+
+    report_file = path / "report.json"
+    if not report_file.exists():
+        console.error(f"Can't find report.json: {path}")
+        return
+
+    scan_config_file = path / "scan_config.json"
+    if not scan_config_file.exists():
+        console.error(f"Can't find scan_config.json: {path}")
+        return
+
+    with open(report_file, encoding="utf-8") as fd:
+        report_data = fd.read()
+        report = SandboxBaseTaskResponse.model_validate_json(report_data)
+
+    with open(scan_config_file, encoding="utf-8") as fd:
+        scan_config_data = fd.read()
+        scan_config = SandboxArguments.model_validate_json(scan_config_data)
+
+    key = get_key_by_name(scan_config.sandbox_key_name)
+    link = format_link(report, key=key)
+
+    open_link(link)

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/cli/scanner/__init__.py

@@ -110,6 +110,14 @@ async def re_scan(
             group="Download options",
         ),
     ] = False,
+    open_browser: Annotated[
+        bool,
+        Parameter(
+            name=["--open-browser", "-ob"],
+            help="Open analysis link in the default browser",
+            negative="",
+        ),
+    ] = False,
 ) -> None:
     """
     Send traces to re-scan.
@@ -137,6 +145,7 @@ async def re_scan(
         is_local=is_local,
         unpack=unpack,
         debug=debug,
+        open_browser=open_browser,
     )
 
 
@@ -312,6 +321,14 @@ async def scan(
             negative="",
         ),
     ] = False,
+    open_browser: Annotated[
+        bool,
+        Parameter(
+            name=["--open-browser", "-ob"],
+            help="Open analysis link in the default browser",
+            negative="",
+        ),
+    ] = False,
 ) -> None:
     """
     Send files to scan with the sandbox.
@@ -374,6 +391,7 @@ async def scan(
         crashdumps=crashdumps,
         procdumps=procdumps,
         decompress=decompress,
+        open_browser=open_browser,
     )
 
 
@@ -630,6 +648,14 @@ async def scan_new(
             negative="",
         ),
     ] = False,
+    open_browser: Annotated[
+        bool,
+        Parameter(
+            name=["--open-browser", "-ob"],
+            help="Open analysis link in the default browser",
+            negative="",
+        ),
+    ] = False,
 ) -> None:
     """
     Send files to scan with the sandbox (advanced scan).
@@ -698,4 +724,5 @@ async def scan_new(
         crashdumps=crashdumps,
         procdumps=procdumps,
         decompress=decompress,
+        open_browser=open_browser,
     )

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/internal/config.py

@@ -84,6 +84,10 @@ class Settings(BaseModel):
                 description=self.description,
             )
 
+    class Browser(BaseModel):
+        path: Path
+        args: list[str]
+
     # default settings (not changable)
     linux_images: set[VMImage] = {
         VMImage.ALTWORKSTATION_X64,
@@ -119,10 +123,13 @@ class Settings(BaseModel):
     docker: Docker = Docker()
     sandbox: list[Sandbox] = []
     rules_path: Path | None = Field(default=None, alias="rules-path")
+    browser: Browser | None = Field(default=None)
 
     def model_post_init(self, __context: Any) -> None:
         self.sandbox_keys = [x.sandbox_key for x in self.sandbox]
         self.rules_path = Path(self.rules_path) if self.rules_path else None
+        if self.browser:
+            self.browser.args.append("%s")
 
 
 def load_config(path: Path) -> Settings:

sandbox_cli-0.2.30/sandbox_cli/internal/helpers.py

@@ -0,0 +1,88 @@
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Any, overload
+
+from ptsandbox import Sandbox, SandboxKey
+from ptsandbox.models import SandboxBaseTaskResponse
+
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import settings
+from sandbox_cli.models.sandbox_arguments import SandboxArguments
+
+
+def get_key_by_name(key_name: str) -> SandboxKey:
+    for sandbox_key in settings.sandbox_keys:
+        if sandbox_key.name == key_name:
+            return sandbox_key
+    raise KeyError()
+
+
+def get_sandbox_key_by_host(task_host: str) -> SandboxKey:
+    for sandbox_key in settings.sandbox_keys:
+        if sandbox_key.host == task_host:
+            return sandbox_key
+
+    raise KeyError()
+
+
+def validate_key(_: Any, value: Any) -> None:
+    try:
+        get_key_by_name(value)
+    except KeyError:
+        console.error(
+            f'Key "{value}" doesn\'t exists in config. Available keys: "{'","'.join(x.name for x in settings.sandbox_keys)}"'
+        )
+        sys.exit(1)
+
+
+@overload
+def format_link(
+    report: SandboxBaseTaskResponse,
+    *,
+    sandbox: Sandbox,
+    key: SandboxKey | None = None,
+) -> str: ...
+
+
+@overload
+def format_link(
+    report: SandboxBaseTaskResponse,
+    *,
+    sandbox: Sandbox | None = None,
+    key: SandboxKey,
+) -> str: ...
+
+
+def format_link(
+    report: SandboxBaseTaskResponse,
+    *,
+    sandbox: Sandbox | None = None,
+    key: SandboxKey | None = None,
+) -> str:
+    key = key or (sandbox.api.key if sandbox else None)
+
+    if not key:
+        console.error("Key not provided")
+        sys.exit(1)
+
+    if not (short_report := report.get_short_report()):
+        return "Unknown"
+
+    return f"https://{key.host}/tasks/{short_report.scan_id}"
+
+
+def save_scan_arguments(out_dir: Path, scan_args: SandboxArguments) -> None:
+    scan_config_path = out_dir / "scan_config.json"
+    scan_config_path.write_text(scan_args.model_dump_json(exclude="debug_options", indent=4), encoding="utf-8")
+
+
+def open_link(link: str) -> None:
+    if settings.browser != None:
+        webbrowser.register("new_default_browser", None, webbrowser.GenericBrowser([settings.browser.path, *settings.browser.args]), preferred=True)
+        if not webbrowser.open(link):
+            console.error("Can't open link in the specified browser. Please check browser path and args.")
+        return
+    
+    if not webbrowser.open_new_tab(link):
+        console.error("Can't open link in the default browser. Try adding path and args for your browser to the config file.")

sandbox_cli-0.2.30/sandbox_cli/models/sandbox_arguments.py

@@ -0,0 +1,22 @@
+from enum import Enum
+
+from ptsandbox.models.api import SandboxOptions, SandboxOptionsAdvanced
+from pydantic import BaseModel
+
+
+class ScanType(str, Enum):
+    SCAN = "scan"
+    RE_SCAN = "re-scan"
+    SCAN_NEW = "scan-new"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        return str(self.value)
+
+
+class SandboxArguments(BaseModel):
+    type: ScanType
+    sandbox_key_name: str
+    sandbox_options: SandboxOptions | SandboxOptionsAdvanced

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/utils/downloader/__init__.py

@@ -40,6 +40,14 @@ async def _save_artifact(
 
     # sanitize path
     path = out_dir / Path(str(path).replace(" ", "_"))
+    n = 1
+    while path.exists():
+        if not path.with_name(path.name + f"_{n}").exists():
+            path = path.with_name(path.name + f"_{n}")
+            break
+        n += 1
+    path.parent.mkdir(exist_ok=True, parents=True)
+    path.touch()
     task_id: TaskID = None  # type: ignore
 
     async with semaphore:
@@ -53,8 +61,6 @@ async def _save_artifact(
                 )
             else:
                 task_id = progress.add_task(rf"\[[green1]{scan_id}[/]] {escape(path.name)}")
-
-        path.parent.mkdir(exist_ok=True, parents=True)
         try:
             downloaded_data = await sandbox.get_file(uri)
         except SandboxFileNotFoundException:

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/utils/scanner/__init__.py

@@ -2,62 +2,27 @@ import asyncio
 import sys
 from collections.abc import Coroutine
 from pathlib import Path
-from typing import Any, overload
+from typing import Any
 
 import aiofiles
 from ptsandbox import Sandbox
-from ptsandbox.models import (
-    SandboxBaseScanTaskRequest,
-    SandboxBaseTaskResponse,
-    SandboxKey,
-    SandboxOptions,
-)
+from ptsandbox.models import SandboxBaseScanTaskRequest, SandboxKey, SandboxOptions
 
 from sandbox_cli.console import console
 from sandbox_cli.internal.config import VMImage, settings
-from sandbox_cli.internal.helpers import get_key_by_name
+from sandbox_cli.internal.helpers import (
+    format_link,
+    get_key_by_name,
+    open_link,
+    save_scan_arguments,
+)
+from sandbox_cli.models.sandbox_arguments import SandboxArguments, ScanType
 from sandbox_cli.utils.compiler import compile_rules_internal
 from sandbox_cli.utils.downloader import download
 from sandbox_cli.utils.merge_dll_hooks import merge_dll_hooks
 from sandbox_cli.utils.unpack import Unpack
 
 
-@overload
-def format_link(
-    report: SandboxBaseTaskResponse,
-    *,
-    sandbox: Sandbox,
-    key: SandboxKey | None = None,
-) -> str: ...
-
-
-@overload
-def format_link(
-    report: SandboxBaseTaskResponse,
-    *,
-    sandbox: Sandbox | None = None,
-    key: SandboxKey,
-) -> str: ...
-
-
-def format_link(
-    report: SandboxBaseTaskResponse,
-    *,
-    sandbox: Sandbox | None = None,
-    key: SandboxKey | None = None,
-) -> str:
-    key = key or (sandbox.api.key if sandbox else None)
-
-    if not key:
-        console.error("Key not provided")
-        sys.exit(1)
-
-    if not (short_report := report.get_short_report()):
-        return "Unknown"
-
-    return f"https://{key.host}/tasks/{short_report.scan_id}"
-
-
 async def _get_compiled_rules(rules_dir: Path | None, is_local: bool) -> bytes | None:
     if not rules_dir:
         return None
@@ -188,6 +153,7 @@ async def scan_internal(
     crashdumps: bool,
     procdumps: bool,
     decompress: bool,
+    open_browser: bool,
 ) -> None:
     key = get_key_by_name(key_name)
     sandbox_sem = asyncio.Semaphore(value=key.max_workers)
@@ -222,6 +188,10 @@ async def scan_internal(
             console.info(
                 rf"{idx} [magenta]\[{sandbox_options.sandbox.image_id}][/magenta] Waiting [yellow]{file_path.name}[/]: {format_link(scan_result, key=key)}"
             )
+
+            if open_browser:
+                open_link(format_link(scan_result, key=key))
+
             awaited_report = await sandbox.wait_for_report(scan_result, wait_time)
             if not awaited_report:
                 console.error(f"{idx} Scan [yellow]{file_path.name}[/] failed: {scan_result=}")
@@ -263,6 +233,13 @@ async def scan_internal(
         out_dir: Path,
         idx: str,
     ) -> None:
+        sandbox_arguments = SandboxArguments(
+            type=ScanType.SCAN,
+            sandbox_key_name=key.name,
+            sandbox_options=sandbox_options.sandbox,
+        )
+        save_scan_arguments(out_dir, sandbox_arguments)
+
         # try:
         await process_file(sandbox_options, file_path, out_dir, idx)
         # except Exception as ex:

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/utils/scanner/advanced.py

@@ -14,11 +14,16 @@ from rich.progress import Progress, SpinnerColumn, TaskID, TextColumn, TimeElaps
 
 from sandbox_cli.console import console
 from sandbox_cli.internal.config import VMImage, settings
-from sandbox_cli.internal.helpers import get_key_by_name
+from sandbox_cli.internal.helpers import (
+    format_link,
+    get_key_by_name,
+    open_link,
+    save_scan_arguments,
+)
+from sandbox_cli.models.sandbox_arguments import SandboxArguments, ScanType
 from sandbox_cli.utils.compiler import compile_rules_internal
 from sandbox_cli.utils.downloader import download
 from sandbox_cli.utils.merge_dll_hooks import merge_dll_hooks
-from sandbox_cli.utils.scanner import format_link
 from sandbox_cli.utils.unpack import Unpack
 
 DELIMETER = "\n"
@@ -200,6 +205,7 @@ async def scan_internal_advanced(
     crashdumps: bool,
     procdumps: bool,
     decompress: bool,
+    open_browser: bool,
 ) -> None:
     key = get_key_by_name(key_name)
     sandbox_sem = asyncio.Semaphore(value=key.max_workers)
@@ -259,6 +265,9 @@ async def scan_internal_advanced(
             formatted_link = f"[medium_purple]{format_link(scan_result, key=key)}[/]"
             final_output = f"{image_string} • [yellow]{file_path.name}[/] • {formatted_link}"
 
+            if open_browser:
+                open_link(format_link(scan_result, key=key))
+
             progress.update(
                 task_id=task_id,
                 description=f"Waiting [yellow]{file_path.name}[/]",
@@ -313,6 +322,13 @@ async def scan_internal_advanced(
         out_dir: Path,
         idx: str,
     ) -> None:
+        sandbox_arguments = SandboxArguments(
+            type=ScanType.SCAN_NEW,
+            sandbox_key_name=key.name,
+            sandbox_options=sandbox_options,
+        )
+        save_scan_arguments(out_dir, sandbox_arguments)
+
         # try:
         await process_file(sandbox_options, file_path, out_dir, idx)
         # except Exception as ex:

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/utils/scanner/rescan.py

@@ -18,10 +18,15 @@ from rich.progress import Progress, SpinnerColumn, TaskID, TextColumn, TimeElaps
 
 from sandbox_cli.console import console
 from sandbox_cli.internal.config import settings
-from sandbox_cli.internal.helpers import get_key_by_name
+from sandbox_cli.internal.helpers import (
+    format_link,
+    get_key_by_name,
+    open_link,
+    save_scan_arguments,
+)
+from sandbox_cli.models.sandbox_arguments import SandboxArguments, ScanType
 from sandbox_cli.utils.compiler import compile_rules_internal
 from sandbox_cli.utils.downloader import download
-from sandbox_cli.utils.scanner import format_link
 from sandbox_cli.utils.unpack import Unpack
 
 
@@ -92,6 +97,7 @@ async def rescan_internal(
     is_local: bool,
     unpack: bool,
     debug: bool,
+    open_browser: bool,
 ) -> None:
     key = get_key_by_name(key_name)
     sandbox_sem = asyncio.Semaphore(value=key.max_workers)
@@ -148,6 +154,9 @@ async def rescan_internal(
             formatted_link = f"[medium_purple]{format_link(rescan_result, key=key)}[/]"
             final_output = f"[yellow]{trace.name}[/] • {formatted_link}"
 
+            if open_browser:
+                open_link(format_link(rescan_result, key=key))
+
             progress.update(
                 task_id=task_id,
                 description=f"Waiting for full report for [yellow]{trace.name}[/]",
@@ -237,10 +246,16 @@ async def rescan_internal(
     tasks: list[Coroutine[Any, Any, None]] = []
     with progress:
         sandbox, sandbox_options = await _prepare_rescan_options(progress, rules_dir, key, is_local)
+        sandbox_arguments = SandboxArguments(
+            type=ScanType.RE_SCAN,
+            sandbox_key_name=key.name,
+            sandbox_options=sandbox_options.sandbox,
+        )
 
         if len(traces) == 1:
             local_out_dir = out_dir / "rescan"
             local_out_dir.mkdir(parents=True, exist_ok=True)
+            save_scan_arguments(local_out_dir, sandbox_arguments)
             tasks.append(wrapper(traces[0], local_out_dir, "1/1"))
         else:
             for i, trace in enumerate(traces):
@@ -251,6 +266,7 @@ async def rescan_internal(
                     local_out_dir = out_dir / trace.stem
 
                 local_out_dir.mkdir(parents=True, exist_ok=True)
+                save_scan_arguments(local_out_dir, sandbox_arguments)
                 idx = f"{i + 1}/{len(traces)}"
                 tasks.append(wrapper(trace, local_out_dir, idx))
 

{sandbox_cli-0.2.29 → sandbox_cli-0.2.30}/sandbox_cli/utils/unpack/plugins/sort_by_plugins.py

@@ -15,7 +15,7 @@ class SortByPlugins(BasePlugin):
             console.warning(f"{file} not exist")
             return
 
-        with open(file, errors="ignore") as fd:
+        with open(file, errors="ignore", encoding="utf-8") as fd:
             raw_trace = fd.readlines()
 
         plugins: defaultdict[str, list[str]] = defaultdict(list)

sandbox_cli-0.2.29/sandbox_cli/internal/helpers.py

@@ -1,32 +0,0 @@
-import sys
-from typing import Any
-
-from ptsandbox import SandboxKey
-
-from sandbox_cli.console import console
-from sandbox_cli.internal.config import settings
-
-
-def get_key_by_name(key_name: str) -> SandboxKey:
-    for sandbox_key in settings.sandbox_keys:
-        if sandbox_key.name == key_name:
-            return sandbox_key
-    raise KeyError()
-
-
-def get_sandbox_key_by_host(task_host: str) -> SandboxKey:
-    for sandbox_key in settings.sandbox_keys:
-        if sandbox_key.host == task_host:
-            return sandbox_key
-
-    raise KeyError()
-
-
-def validate_key(_: Any, value: Any) -> None:
-    try:
-        get_key_by_name(value)
-    except KeyError:
-        console.error(
-            f'Key "{value}" doesn\'t exists in config. Available keys: "{'","'.join(x.name for x in settings.sandbox_keys)}"'
-        )
-        sys.exit(1)