sandbox-cli 0.2.49__tar.gz → 0.3.0__tar.gz

{sandbox_cli-0.2.49 → sandbox_cli-0.3.0}/PKG-INFO

@@ -1,25 +1,24 @@
 Metadata-Version: 2.4
 Name: sandbox-cli
-Version: 0.2.49
+Version: 0.3.0
 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
 Project-URL: Repository, https://github.com/Security-Experts-Community/sandbox-cli
 Project-URL: Issues, https://github.com/Security-Experts-Community/sandbox-cli/issues
-Author: Alexey Kolesnikov
+Author-email: Alexey Kolesnikov <delvinru@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.11
 Requires-Dist: aiofiles>=25.1.0
-Requires-Dist: asyncssh>=2.22.0
+Requires-Dist: asyncssh>=2.24.0
 Requires-Dist: colorama>=0.4.6
-Requires-Dist: cryptography>=46.0.5
-Requires-Dist: cyclopts>=4.10.2
-Requires-Dist: docker>=7.1.0
-Requires-Dist: ptsandbox>=5.0.11
-Requires-Dist: pyzipper>=0.3.6
-Requires-Dist: rich>=14.3.3
+Requires-Dist: cryptography>=49.0.0
+Requires-Dist: cyclopts>=4.20.0
+Requires-Dist: docker>=7.2.0
+Requires-Dist: ptsandbox>=5.1.0
+Requires-Dist: rich>=15.0.0
 Requires-Dist: zstandard>=0.25.0
 Description-Content-Type: text/markdown
 

{sandbox_cli-0.2.49 → sandbox_cli-0.3.0}/pyproject.toml

@@ -1,22 +1,21 @@
 [project]
 name = "sandbox-cli"
-version = "0.2.49"
+version = "0.3.0"
 description = "Command line tool for interaction with sandboxes"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 license-files = ["LICENSE", "NOTICE"]
-authors = [{ name = "Alexey Kolesnikov" }]
+authors = [{ name = "Alexey Kolesnikov", email = "delvinru@gmail.com" }]
 dependencies = [
   "aiofiles>=25.1.0",
-  "asyncssh>=2.22.0",
+  "asyncssh>=2.24.0",
   "colorama>=0.4.6",
-  "cryptography>=46.0.5",
-  "cyclopts>=4.10.2",
-  "docker>=7.1.0",
-  "ptsandbox>=5.0.11",
-  "pyzipper>=0.3.6",
-  "rich>=14.3.3",
+  "cryptography>=49.0.0",
+  "cyclopts>=4.20.0",
+  "docker>=7.2.0",
+  "ptsandbox>=5.1.0",
+  "rich>=15.0.0",
   "zstandard>=0.25.0",
 ]
 
@@ -28,13 +27,15 @@ Issues = "https://github.com/Security-Experts-Community/sandbox-cli/issues"
 
 [dependency-groups]
 dev = [
-  "black>=24.10.0",
-  "isort>=5.13.2",
-  "mypy>=1.14.1",
-  "types-aiofiles>=24.1.0.20241221",
-  "types-docker>=7.1.0.20241229",
+  "black==26.5.1",
+  "isort==8.0.1",
+  "mypy==2.3.0",
+  "ruff==0.14.0",
+  "types-aiofiles==25.1.0.20260518",
+  "types-docker==7.2.0.20260728",
+  "types-colorama==0.4.15.20260508",
 ]
-docs = ["mkdocs>=1.6.1", "mkdocs-material>=9.6.7", "termynal>=0.13.0"]
+docs = ["mkdocs==1.6.1", "mkdocs-material==9.7.7", "termynal==0.14.0"]
 
 [project.scripts]
 sandbox-cli = "sandbox_cli.__main__:main"
@@ -82,24 +83,40 @@ exclude = '''
 
 [[tool.mypy.overrides]]
 strict = true
-module = ["ptsandbox.*", "docker.*", "pyzipper.*"]
+module = ["ptsandbox.*", "docker.*"]
 ignore_missing_imports = true
 
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+no_implicit_optional = true
+show_error_codes = true
+namespace_packages = true
+explicit_package_bases = true
+exclude = ["\\.venv/", "\\.mypy_cache/", "build/", "dist/"]
+
 [tool.ruff]
 lint.select = [
-  "E",    # pycodestyle errors
-  "W",    # pycodestyle warnings
-  "F",    # pyflakes
-  "I",    # isort
-  "B",    # flake8-bugbear
-  "C4",   # flake8-comprehensions
-  "UP",   # pyupgrade
-  "F401", # unused-imports
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "UP",  # pyupgrade
+  "SIM", # flake8-simplify
+  "RUF", # ruff-specific
 ]
 lint.ignore = [
-  "E501", # line too long, handled by black
-  "B008", # do not perform function calls in argument defaults
-  "W191", # indentation contains tabs
+  "E501",   # line too long, handled by black
+  "B008",   # do not perform function calls in argument defaults
+  "W191",   # indentation contains tabs
+  "SIM117", # nested with (readability)
 ]
 line-length = 120
 target-version = "py311"

sandbox_cli-0.3.0/sandbox_cli/__main__.py

@@ -0,0 +1,41 @@
+import os
+import sys
+from http import HTTPStatus
+
+import aiohttp
+import aiohttp.client_exceptions
+
+from sandbox_cli.cli import app
+from sandbox_cli.console import console
+from sandbox_cli.core.exceptions import SandboxCliError
+
+
+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 SandboxCliError as e:
+        console.error(str(e))
+    except KeyboardInterrupt:
+        console.warning("Operation cancelled")
+        sys.exit(130)
+    except Exception as e:
+        # Show a concise error by default; full traceback only with DEBUG env var
+        # (see https://no-color.org/ style conventions for CLI tools).
+        if os.environ.get("DEBUG"):
+            console.print_exception()
+        else:
+            console.error(f"{type(e).__name__}: {e}")
+            console.info("Set DEBUG=1 for a full traceback.")
+
+
+if __name__ == "__main__":
+    main()

sandbox_cli-0.3.0/sandbox_cli/cli/__init__.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Annotated, Literal
+
+from colorama import init
+from cyclopts import App, Parameter
+
+from sandbox_cli.console import console
+from sandbox_cli.core.config import configpath, settings
+
+init()  # enable ANSI colors on Windows
+
+__all__ = ["app"]
+
+
+def get_version() -> str:
+    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,
+)
+
+
+def completion(
+    shell: Annotated[
+        Literal["bash", "zsh", "fish"],
+        Parameter(
+            help="Shell to generate completion for",
+        ),
+    ],
+    /,
+    *,
+    install: Annotated[
+        bool,
+        Parameter(
+            name=["--install", "-i"],
+            help="Install the completion script to the default location for the current shell and add it to the RC file",
+            negative="",
+        ),
+    ] = False,
+) -> None:
+    """
+    Generate or install shell completion.
+    """
+    if install:
+        path = app.install_completion(shell=shell)
+        console.info(f"Completion installed to {path}")
+    else:
+        console.print(app.generate_completion(shell=shell), end="")
+
+
+app.command(name="completion")(completion)
+
+# Lazy-loaded commands — modules are imported only when the command is invoked,
+# keeping ``--help`` and ``--version`` fast by avoiding heavy imports
+app.command(
+    "sandbox_cli.cli.unpack:unpack_logs",
+    name=["conv", "unpack"],
+    help="Convert sandbox logs into an analysis-friendly format.",
+)
+app.command(
+    "sandbox_cli.cli.report:generate_report",
+    name="report",
+    help="Generate short report from sandbox scans.",
+)
+app.command(
+    "sandbox_cli.cli.browser:open_browser",
+    name="browser",
+    help="Open sandbox link in the default browser.",
+)
+
+if len(settings.sandbox_keys) > 0:
+    scanner_app = App(name="scanner", help="Scan with the sandbox.", help_format="markdown", console=console)
+    scanner_app.command(
+        "sandbox_cli.cli.scanner.scan:scan",
+        name="scan",
+        help="Send files to scan with the sandbox.",
+    )
+    scanner_app.command(
+        "sandbox_cli.cli.scanner.scan_new:scan_new",
+        name="scan-new",
+        help="Send files to scan with the sandbox (advanced scan).",
+    )
+    scanner_app.command(
+        "sandbox_cli.cli.scanner.re_scan:re_scan",
+        name="re-scan",
+        help="Send traces to re-scan.",
+    )
+    app.command(scanner_app)
+
+    rules_app = App(
+        name="rules",
+        help="Working with raw sandbox rules.",
+        help_format="markdown",
+        console=console,
+    )
+    rules_app.command(
+        "sandbox_cli.cli.rules.compile:compile_rules",
+        name="compile",
+        help="Get compiled rules for working with third-party services.",
+    )
+    rules_app.command(
+        "sandbox_cli.cli.rules.test:test_rules",
+        name="test",
+        help="Testing written rules.",
+    )
+    app.command(rules_app)
+
+    app.command(
+        "sandbox_cli.cli.images:get_images",
+        name="images",
+        help="Get available images in the sandbox.",
+    )
+    app.command(
+        "sandbox_cli.cli.download:download_command",
+        name="download",
+        help="Download any artifact from the sandbox.",
+    )
+    app.command(
+        "sandbox_cli.cli.download:download_email",
+        name="email",
+        help="Upload an email and get its headers.",
+    )

sandbox_cli-0.3.0/sandbox_cli/cli/_converters.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import sys
+from collections import deque
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from cyclopts import validators
+
+from sandbox_cli.console import console
+from sandbox_cli.core.config import Platform, VMImage, parse_image, settings
+from sandbox_cli.core.exceptions import ConfigError
+
+if TYPE_CHECKING:
+    from cyclopts import Token
+
+__all__ = [
+    "files_path_resolver",
+    "image_converter",
+    "out_dir_converter",
+    "out_dir_validator",
+    "rules_path_resolver",
+    "trace_converter",
+    "trace_validator",
+]
+
+
+def image_converter(_: Any, tokens: Sequence[Token]) -> set[VMImage | str]:
+    """
+    Convert ``--image`` tokens into a set of ``VMImage`` or custom image ids.
+    """
+    return {parse_image(token.value) for token in tokens}
+
+
+def out_dir_converter(_: Any, tokens: Sequence[Token]) -> Path:
+    """
+    Resolve ``--out`` value: expand ``~``, create the directory, return absolute path.
+    """
+    path = Path(tokens[0].value).expanduser()
+    path.mkdir(exist_ok=True, parents=True)
+    return path.resolve()
+
+
+def out_dir_validator(_: Any, value: Any) -> None:
+    """
+    Ensure the output directory exists (also covers default values).
+    """
+    if isinstance(value, Path):
+        value.mkdir(exist_ok=True, parents=True)
+
+
+def trace_converter(_: Any, tokens: Sequence[Token]) -> list[Path]:
+    """
+    Resolve trace paths: expand ``~`` and return absolute paths.
+    """
+    return [Path(t.value).expanduser().resolve() for t in tokens]
+
+
+def trace_validator(_: Any, value: Any) -> None:
+    """
+    Validate that all trace paths exist.
+    """
+    path_validator = validators.Path(exists=True)
+    if isinstance(value, list):
+        for v in value:
+            path_validator(_, v)
+    elif isinstance(value, Path):
+        path_validator(_, value)
+
+
+def rules_path_resolver(_: Any, tokens: Sequence[Token]) -> Path | None:
+    """
+    Resolve ``--rules`` tokens into a rules directory path.
+
+    Accepts either a platform alias (``windows``/``linux``) resolved
+    against ``settings.rules_path``, or an explicit path.
+    """
+    path: Path | None = None
+    for token in tokens:
+        if token.value in {Platform.LINUX, Platform.WINDOWS}:
+            if not settings.rules_path:
+                raise ConfigError("You can't use aliases without specifying the path in the config")
+
+            path = settings.rules_path / token.value
+            break
+        else:
+            # no platform alias — use the specified value as a path
+            path = Path(token.value)
+
+    return path
+
+
+def files_path_resolver(files: list[Path]) -> list[Path] | None:
+    """
+    Expand a list of file/folder paths into a flat list of files.
+
+    Handles wildcards on Windows and recurses into directories. Returns
+    ``None`` when one or more inputs are invalid so the caller can bail out.
+    """
+    files_queue: deque[Path] = deque(files)
+    files_for_analysis: set[Path] = set()
+
+    is_ok = True
+    while files_queue:
+        file = files_queue.popleft()
+
+        # process wildcards
+        if sys.platform == "win32" and "*" in str(file):
+            for f in Path.cwd().glob(str(file)):
+                if f.is_file():
+                    files_queue.append(f)
+            continue
+
+        file = file.expanduser().resolve()
+
+        if not file.exists():
+            console.error(f"{file!s} doesn't exist")
+            is_ok = False
+
+        if file.is_dir():
+            files_for_analysis.update(file.glob("**/*"))
+            continue
+
+        files_for_analysis.add(file)
+
+    if len(files_for_analysis) == 0:
+        console.error("Nothing to scan")
+        is_ok = False
+
+    return list(files_for_analysis) if is_ok else None

sandbox_cli-0.3.0/sandbox_cli/cli/browser.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from sandbox_cli.console import console
+from sandbox_cli.core.browser import open_link
+from sandbox_cli.core.sandbox import (
+    format_link,
+    get_key_by_name,
+)
+from sandbox_cli.core.scan import load_report, load_scan_arguments
+
+__all__ = ["open_browser"]
+
+
+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
+
+    report = load_report(report_file)
+    scan_config = load_scan_arguments(scan_config_file)
+
+    key = get_key_by_name(scan_config.sandbox_key_name)
+    link = format_link(report, key=key)
+
+    open_link(link)

sandbox_cli-0.3.0/sandbox_cli/cli/download/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from sandbox_cli.cli.download.artifacts import download_command
+from sandbox_cli.cli.download.email import download_email
+
+__all__ = ["download_command", "download_email"]