sandbox-cli 0.2.26__py3-none-any.whl

sandbox_cli/cli/unpack.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import Parameter, validators
+
+from sandbox_cli.console import console
+from sandbox_cli.utils.unpack import Unpack
+
+
+def unpack_logs(
+    traces: Annotated[
+        list[Path],
+        Parameter(
+            help="The path to the folder with the raw traces or with the sandbox-logs.zip",
+            negative="",
+            validator=validators.Path(exists=True),
+        ),
+    ],
+    /,
+) -> None:
+    """
+    Convert sandbox logs into an analysis-friendly format.
+
+    Output file structure:
+    * drakvuf-trace
+        * drakvuf-trace.log
+    * correlated
+        * events-correlated.log
+        * events-correlated.log.<DETECT_NAME>
+    * normalized
+        * events-normalized.log
+        * events-normalized.log.<DETECT_NAME>
+    * network
+        * tcpdump.pcap
+    * raw
+        * drakvuf-trace.log.zst
+        * tcpdump.pcap
+
+    Usage examples:
+    * Checks for drakvuf-trace.log.gz or drakvuf-trace.log.zst in the current directory:
+    _sandbox-cli unpack ._
+    * Extracts and processes logs into the sandbox_logs directory:
+    _sandbox-cli unpack sandbox_logs.zip_
+    * Handles multiple archives simultaneously:
+    _sandbox-cli unpack sandbox_logs.zip sandbox_logs_1.zip_
+    """
+
+    for trace in traces:
+        console.info(f"Unpacking {trace}")
+        Unpack(trace=trace).run()

sandbox_cli/console.py

@@ -0,0 +1,24 @@
+from rich.console import Console
+
+
+class SandboxConsole(Console):
+    INFO = "[turquoise2 bold][INFO][/]"
+    WARNING = "[yellow1 bold][WARN][/]"
+    ERROR = "[red3 bold][ERROR][/]"
+    DONE = "[green3 bold][DONE][/]"
+
+    def done(self, message: str) -> None:
+        self.print(f"{self.DONE} {message}")
+
+    def info(self, message: str) -> None:
+        self.print(f"{self.INFO} {message}")
+
+    def warning(self, message: str) -> None:
+        self.print(f"{self.WARNING} {message}", style="bold")
+
+    def error(self, message: str) -> None:
+        self.print(f"{self.ERROR} {message}", style="bold")
+
+
+console = SandboxConsole(color_system="auto", emoji=True)
+console = SandboxConsole(color_system="auto", emoji=True)

sandbox_cli/internal/config.py

@@ -0,0 +1,143 @@
+import os
+import sys
+import tomllib
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import pydantic
+from ptsandbox import SandboxKey
+from pydantic import BaseModel, Field
+
+from sandbox_cli.console import console
+
+
+class VMImage(str, Enum):
+    """
+    A list of all known images
+
+    Please note that not all images are supported or available anymore (left as a legacy)
+    """
+
+    ALTWORKSTATION_X64 = "altworkstation-10-x64"
+    ASTRALINUX_SMOLENSK_X64 = "astralinux-smolensk-x64"
+    REDOS_8_X64 = "redos-8-x64"
+    REDOS_MUROM_X64 = "redos-murom-x64"
+    UBUNTU_JAMMY_X64 = "ubuntu-jammy-x64"
+
+    WIN10_1803_X64 = "win10-1803-x64"
+    WIN10_22H2_X64 = "win10-22H2-x64"
+    WIN11_23H2_X64 = "win11-23H2-x64"
+    WIN7_SP1_X64 = "win7-sp1-x64"
+    WIN7_SP1_X64_ICS = "win7-sp1-x64-ics"
+    WIN81_UPDATE1_X64 = "win8.1-update1-x64"
+    WINSERV2016_1198_X64 = "winserv2016-1198-x64"
+    WINSERV2019_1879_X64 = "winserv2019-1879-x64"
+
+    LINUX = "linux"
+    WINDOWS = "windows"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        return str(self.value)
+
+
+class Settings(BaseModel):
+    class Docker(BaseModel):
+        username: str = ""
+        token: str = ""
+        registry: str = ""
+        image_name: str = Field(default="", alias="image-name")
+        image_tag: str = Field(default="", alias="image-tag")
+
+        @property
+        def path(self) -> str:
+            return f"{self.registry}/{self.image_name}"
+
+    class Sandbox(BaseModel):
+        class SSH(BaseModel):
+            username: str = ""
+            password: str = ""
+
+        name: str = ""
+        key: str = ""
+        host: str = ""
+        max_workers: int = Field(default=8, alias="max-workers")
+        description: str = ""
+
+        ssh: SSH = SSH()
+
+        @property
+        def sandbox_key(self) -> SandboxKey:
+            return SandboxKey(
+                name=self.name,
+                key=self.key,
+                host=self.host,
+                max_workers=self.max_workers,
+                description=self.description,
+            )
+
+    # default settings (not changable)
+    linux_images: set[VMImage] = {
+        VMImage.ALTWORKSTATION_X64,
+        VMImage.ASTRALINUX_SMOLENSK_X64,
+        VMImage.REDOS_8_X64,
+        VMImage.REDOS_MUROM_X64,
+        VMImage.UBUNTU_JAMMY_X64,
+    }
+
+    windows_images: set[VMImage] = {
+        VMImage.WIN10_1803_X64,
+        VMImage.WIN10_22H2_X64,
+        VMImage.WIN11_23H2_X64,
+        VMImage.WIN7_SP1_X64,
+        VMImage.WIN7_SP1_X64_ICS,
+        VMImage.WIN81_UPDATE1_X64,
+        VMImage.WINSERV2016_1198_X64,
+        VMImage.WINSERV2019_1879_X64,
+    }
+
+    rules_archive_name_zip: str = "rules.zip"
+    rules_archive_name_gz: str = "rules.tar.gz"
+
+    report_name: str = "report.json"
+    default_image: VMImage = VMImage.WIN10_22H2_X64
+    default_duration: int = 300
+
+    # post init params
+    sandbox_keys: list[SandboxKey] = []
+
+    # configurable parameters
+    passwords: list[str] = ["infected", "311138", "password", "12345678", "P@ssw0rd!"]
+    docker: Docker = Docker()
+    sandbox: list[Sandbox] = []
+
+    def model_post_init(self, __context: Any) -> None:
+        self.sandbox_keys = [x.sandbox_key for x in self.sandbox]
+
+
+def load_config(path: Path) -> Settings:
+    if not path.exists():
+        return Settings()
+
+    with open(path, "rb") as fd:
+        raw = tomllib.load(fd)
+
+    try:
+        settings = Settings.model_validate(raw)
+    except pydantic.ValidationError as e:
+        console.print(f"invalid config at {path}: {e}", style="bold red")
+        sys.exit(1)
+
+    return settings
+
+
+configpath = os.path.join(
+    os.environ.get("APPDATA") or os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.environ["HOME"], ".config"),
+    "sandbox-cli",
+    "config.toml",
+)
+
+settings = load_config(Path(configpath))

sandbox_cli/internal/helpers.py

@@ -0,0 +1,32 @@
+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)

sandbox_cli/models/detections.py

@@ -0,0 +1,91 @@
+import json
+from dataclasses import dataclass
+from enum import Enum
+
+
+class DetectionType(str, Enum):
+    """
+    Enum with sandbox detections levels
+    """
+
+    silent = "silent"
+    suspicious = "suspicious"
+    malware = "malware"
+
+
+@dataclass(frozen=True)
+class Detect:
+    """
+    Dataclass for sandbox detect, comparable by key (weight ignored)
+    """
+
+    name: str
+    weight: int | None
+
+    def __key(self) -> tuple[str]:
+        return (self.name,)
+
+    def __hash__(self) -> int:
+        return hash(self.__key())
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Detect):
+            return self.__key() == other.__key()
+        return NotImplemented
+
+
+class Detections:
+    """
+    Class for stroing/parsing detections from correlated-logs
+    """
+
+    detections: dict[DetectionType, set[Detect]]
+
+    _real_name: str
+
+    def __init__(self, trace: bytes) -> None:
+        """
+        trace: UN-gzipped correlated-logs bytes.
+        """
+
+        self.detections = {
+            DetectionType.silent: set(),
+            DetectionType.suspicious: set(),
+            DetectionType.malware: set(),
+        }
+
+        for line in trace.decode().splitlines(keepends=False):
+            event = json.loads(line)
+            if event.get("auxiliary.type", None) == "init":
+                self._real_name = event.get("object.name")
+            detect_type = event.get("detect.type")
+            if detect_type in DetectionType.__members__.keys():
+                self.detections[DetectionType[detect_type]].add(
+                    Detect(
+                        name=event.get("detect.name"),
+                        weight=event.get("weight", None),
+                    )
+                )
+
+    def __repr__(self) -> str:
+        return repr(self.detections)
+
+    @property
+    def silent(self) -> set[Detect]:
+        """Only silent detects"""
+        return self.detections[DetectionType.silent]
+
+    @property
+    def suspicious(self) -> set[Detect]:
+        """Only suspicious detects"""
+        return self.detections[DetectionType.suspicious]
+
+    @property
+    def malware(self) -> set[Detect]:
+        """Only malware detects"""
+        return self.detections[DetectionType.malware]
+
+    @property
+    def real_name(self) -> str:
+        """Real sample name, extracted from 'init' auxiliary event"""
+        return self._real_name

sandbox_cli/utils/compiler/__init__.py

@@ -0,0 +1,60 @@
+import sys
+from functools import lru_cache
+from pathlib import Path
+
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import settings
+from sandbox_cli.utils.compiler.abc import AbstractCompiler
+from sandbox_cli.utils.compiler.docker import DockerCompiler
+from sandbox_cli.utils.compiler.ssh import RemoteCompiler
+
+default_out_dir: str = "compiled-rules.local.tmp"
+
+
+@lru_cache
+def get_compiler(*, is_local: bool) -> AbstractCompiler:
+    if is_local:
+        if not settings.docker.token and not settings.docker.registry:
+            console.warning("If you want use local docker container specify options in config")
+            sys.exit(1)
+
+        return DockerCompiler()
+    return RemoteCompiler()
+
+
+async def compile_rules_internal(*, rules_dir: Path, is_local: bool, compiled_rules_dir: Path | None = None) -> bytes:
+    compiler = get_compiler(is_local=is_local)
+
+    if rules := await compiler.compile_rules(rules_dir, compiled_rules_dir):
+        return rules
+
+    console.error("Bad rules")
+    sys.exit(1)
+
+
+async def test_rules_internal(*, rules: Path, is_local: bool) -> None:
+    compiler = get_compiler(is_local=is_local)
+
+    root_rules_dir: Path | None = None
+
+    # maybe bug or feature
+    # don't scan folder ~/rules/<platform>/correlation to avoid stupidly long testing
+    for parent in rules.parents:
+        if parent.name in {"correlation", "normalization"}:
+            root_rules_dir = parent
+            break
+
+    if not root_rules_dir:
+        console.error(f"Invalid rule path (read help): {rules}")
+        sys.exit(1)
+
+    # Generate special path for remote container
+    container_rules_dir = root_rules_dir.name / rules.relative_to(root_rules_dir)
+
+    # after extracting special path take path without correlation/normalization suffix
+    root_rules_dir = root_rules_dir.parent
+
+    if await compiler.test_rules(root_rules_dir, container_rules_dir):
+        console.info("Rules fine")
+    else:
+        console.error("Bad rules")

sandbox_cli/utils/compiler/abc.py

@@ -0,0 +1,51 @@
+import io
+import sys
+import tarfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from sandbox_cli.console import console
+
+
+class AbstractCompiler(ABC):
+    @abstractmethod
+    async def pull_image(self) -> None:
+        pass
+
+    @abstractmethod
+    async def compile_rules(self, rules_dir: Path, compiled_rules_dir: Path | None) -> bytes | None:
+        pass
+
+    @abstractmethod
+    async def test_rules(self, root_rules_dir: Path, container_rules_dir: Path) -> bool:
+        pass
+
+    def normalize_paths(self, rules_dir: Path, compiled_rules_dir: Path) -> tuple[Path, Path]:
+        """
+        Check and normalize rules_dir and compiled_rules_dir
+        """
+
+        rules_dir = rules_dir.expanduser().resolve()
+        if not rules_dir.is_dir():
+            console.error(f"Invalid directory with raw rules: {rules_dir}, {rules_dir.is_dir()}")
+            sys.exit(1)
+
+        compiled_rules_dir = compiled_rules_dir.expanduser()
+        compiled_rules_dir.mkdir(exist_ok=True)
+        compiled_rules_dir = compiled_rules_dir.resolve()  # until directory created, we can't resolve it
+
+        return rules_dir, compiled_rules_dir
+
+    def compress_rules(self, compiled_rules: Path) -> bytes:
+        compiled_rules = compiled_rules.expanduser().resolve()
+
+        fake_file = io.BytesIO()
+
+        with tarfile.open(mode="w:gz", fileobj=fake_file) as tar:
+            for file_name in [
+                "event_correlation_graph.json",
+                "event_normalization_graph.json",
+            ]:  # compiled_rules.glob("*.json")
+                tar.add(compiled_rules / file_name, arcname=file_name)
+
+        return fake_file.getvalue()

sandbox_cli/utils/compiler/docker.py

@@ -0,0 +1,136 @@
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+import requests.exceptions
+from docker import DockerClient, from_env
+from docker.errors import APIError, DockerException, ImageNotFound
+from docker.models.containers import Container
+from rich.markup import escape
+
+from sandbox_cli.console import console
+from sandbox_cli.internal.config import settings
+from sandbox_cli.utils.compiler.abc import AbstractCompiler
+
+
+class DockerCompiler(AbstractCompiler):
+    client: DockerClient
+
+    def __init__(self) -> None:
+        super().__init__()
+        try:
+            self.client = from_env()
+        except DockerException as e:
+            console.error(f"Can't connect to docker: {e}")
+            sys.exit(1)
+
+    async def pull_image(self) -> None:
+        """
+        When image not found start pulling from remote
+        """
+
+        console.warning("Docker image not found, start pulling, be patient")
+        self.client.api.login(
+            username=settings.docker.username,
+            password=settings.docker.token,
+            registry=settings.docker.registry,
+        )
+
+        image = self.client.images.pull(repository=settings.docker.path, tag=settings.docker.image_tag)
+        console.info(f"Docker image successfully pulled: {image}")
+
+    async def run_docker(self, command: str, name: str, rules_dir: Path, compiled_rules_dir: Path) -> bool:
+        """
+        Start docker container with given command
+        :return True - if command was successfull, False - if some bad stuff happens
+        """
+
+        try:
+            self.client.images.get(f"{settings.docker.path}:{settings.docker.image_tag}")
+        except ImageNotFound:
+            await self.pull_image()
+
+        # need copy taxonomy in rules dir otherwise compiler failed
+        local_taxonomy = rules_dir / "taxonomy"
+        shutil.copytree(rules_dir.parent / "taxonomy", local_taxonomy)
+
+        container: Container | None = None
+        exit_data: dict[str, str | int] = {}
+        try:
+            container = self.client.containers.run(
+                image=f"{settings.docker.path}:{settings.docker.image_tag}",
+                command=command,
+                name=name,
+                detach=True,
+                mem_limit="2g",
+                volumes={
+                    str(rules_dir): {"bind": "/rules", "mode": "ro"},
+                    str(compiled_rules_dir): {"bind": "/compiled-rules", "mode": "rw"},
+                },
+            )
+
+            assert container is not None
+
+            logs = container.logs(stream=True, follow=True)
+            for log in logs:
+                console.print(escape(log.decode()), end="")
+        except (KeyboardInterrupt, Exception) as e:  # pylint: disable=broad-exception-caught
+            console.error(f"Exception while running docker: {e}")
+        finally:
+            if local_taxonomy.is_dir():
+                shutil.rmtree(local_taxonomy)
+
+            if container:
+                try:
+                    exit_data = container.wait(timeout=1)  # type: ignore
+                except requests.exceptions.ReadTimeout:
+                    exit_data = {"Error": "some shit happened", "StatusCode": -1}
+
+                try:
+                    container.remove(force=True)
+                except APIError as e:
+                    console.error(f"Can't remove docker image: {e} {exit_data}")
+
+        if exit_data.get("StatusCode") != 0 or exit_data.get("Error"):
+            return False
+
+        return True
+
+    async def compile_rules(self, rules_dir: Path, compiled_rules_dir: Path | None = None) -> bytes | None:
+        with tempfile.TemporaryDirectory("sandbox-cli-docker") as tmp_dir:
+            if not compiled_rules_dir:
+                compiled_rules_dir = Path(tmp_dir)
+
+            rules_dir, compiled_rules_dir = self.normalize_paths(rules_dir, compiled_rules_dir)
+
+            status = await self.run_docker(
+                command=(
+                    "bash -c 'cp -r /rules /rules.copy && "
+                    "package-builder correlation:compile -r /rules.copy -c /compiled-rules'"
+                ),
+                name="drakvuf-rules-compile",
+                rules_dir=rules_dir,
+                compiled_rules_dir=compiled_rules_dir,
+            )
+
+            if not status:
+                return None
+
+            return self.compress_rules(compiled_rules_dir)
+
+    async def test_rules(self, root_rules_dir: Path, container_rules_dir: Path) -> bool:
+        # create tmp folder for store compiled rules
+        with tempfile.TemporaryDirectory("sandbox-cli-docker") as tmp:
+            # ignore result for tests
+            await self.compile_rules(root_rules_dir, Path(tmp))
+
+            # run tests
+            status = await self.run_docker(
+                command=f"package-builder correlation:test -r {Path('/rules') / container_rules_dir} -c /compiled-rules",
+                name="drakvuf-rules-test",
+                rules_dir=root_rules_dir,
+                compiled_rules_dir=Path(tmp),
+            )
+
+            return status