sierra-dev 2.0.0__tar.gz → 2.2.0__tar.gz

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sierra-dev
-Version: 2.0.0
+Version: 2.2.0
 Summary: Modern framework for building investigation invoker scripts with APT-like package management
 Home-page: https://github.com/xsyncio/sierra-dev
 Author: Xsyncio

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sierra-dev"
-version = "2.0.0"
+version = "2.2.0"
 description = "Modern framework for building investigation invoker scripts with APT-like package management"
 readme = "README.md"
 requires-python = ">=3.12"

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-with open("README.md", "r", encoding="utf-8") as fh:
+with open("README.md", encoding="utf-8") as fh:
     long_description = fh.read()
 
 # MkDocs documentation dependencies
@@ -43,7 +43,7 @@ dev_requirements: list[str] = [
 # Core runtime dependencies
 requirements: list[str] = [
     "colorama==0.4.6",  # Terminal colors
-    "httpx==0.28.1",     # HTTP client for package manager
+    "httpx==0.28.1",  # HTTP client for package manager
     "dnspython==2.6.1",  # DNS operations for OSINT tools
     "requests==2.32.0",  # HTTP requests for OSINT tools
     "beautifulsoup4==4.12.3",  # HTML parsing for tech detection
@@ -51,7 +51,7 @@ requirements: list[str] = [
 
 setup(
     name="sierra-dev",
-    version="2.1.0",
+    version="2.2.0",
     author="Xsyncio",
     author_email="dev@xsyncio.com",
     description="Sierra Dev - Modern Invoker Package Manager and Development Framework",

sierra_dev-2.2.0/sierra/__init__.py

@@ -0,0 +1,321 @@
+"""
+sierra-dev.
+==========
+
+A framework for building and managing invoker scripts that can be used across different nodes in Sierra during any investigation.
+
+# Overview
+--------
+
+This package provides a comprehensive framework for building, compiling, and loading Sierra applications, including abstract base classes, core components, and internal utilities.
+
+# Exposed Components
+-----------------
+
+- `create_error_result`: Function to create an error result.
+- `create_tree_result`: Function to create a tree result.
+- `SierraABC`: Abstract base class for Sierra components.
+- `SierraBuilder`: Base class for building Sierra components.
+- `SierraCompiler`: Base class for compiling Sierra components.
+- `SierraConfig`: Top-level configuration for SIERRA invoker scripts.
+- `SierraCoreObject`: Base class for all Sierra components.
+- `SierraDevelopmentEnvironment`: Environment configuration class for Sierra development.
+- `SierraInvokerBuilder`: Builder for Sierra invoker scripts.
+- `SierraLoader`: Base class for loading Sierra components.
+- `SierraSideloader`: Base class for side-loading Sierra components.
+- `UniversalLogger`: Logger class for logging Sierra events.
+- `StreamEmitter`: V2 streaming event emitter with context manager support.
+- `stream_context`: Convenience context manager for V2 streaming sessions.
+
+# V2 Streaming
+-----------
+
+For V2 invokers that stream results in real-time, use the ``StreamEmitter``:
+
+    >>> from sierra.stream import StreamEmitter
+    >>> with StreamEmitter() as stream:
+    ...     stream.progress("Scanning targets...")
+    ...     stream.result(id="node_1", content="### Target Found")
+    ...     stream.end(summary="Scan complete.")
+
+# Integration Notes
+-----------------
+
+This package is designed to be used as a foundation for building complex Sierra applications, providing a robust and flexible framework for managing invoker scripts across different nodes.
+"""
+
+import json
+import os
+import pathlib
+import typing
+
+from sierra._about import (
+    FEATURES,
+    RELEASE_NOTES,
+    VERSION_INFO,
+    VERSION_MAJOR,
+    VERSION_MINOR,
+    VERSION_PATCH,
+    __author__,
+    __author_email__,
+    __copyright__,
+    __description__,
+    __license__,
+    __title__,
+    __url__,
+    __version__,
+)
+from sierra.abc import (
+    SierraABC,
+    SierraConfig,
+    SierraInvokerParam,
+    SierraInvokerScript,
+)
+from sierra.client import SierraDevelopmentClient
+from sierra.core import (
+    SierraCompiler,
+    SierraCoreObject,
+    SierraDevelopmentEnvironment,
+    SierraInvokerBuilder,
+    SierraSideloader,
+)
+from sierra.internal import (
+    BaseSierraError,
+    CacheManager,
+    CompressionType,
+    SierraCacheError,
+    SierraClientLoadError,
+    SierraExecutionError,
+    SierraHTTPError,
+    SierraPathError,
+    SierraPathNotFoundError,
+    UniversalLogger,
+)
+from sierra.invoker import InvokerScript
+from sierra.options import Param, SierraOption
+from sierra.results import Chart, Network, Table, Timeline, Tree
+from sierra.stream import StreamEmitter, stream_context
+from sierra.validators import (
+    InvokerValidationResult,
+    sanitize_description,
+    validate_invoker_name,
+    validate_node_id,
+    validate_param_type,
+    validate_protocol,
+    validate_yaml_safe,
+)
+
+
+def create_tree_result(
+    results: list[str | dict[str, list[str]]],
+) -> str:
+    """
+    Create a tree result containing a list of results.
+
+    Parameters
+    ----------
+    results : list[Union[str, dict[str, list[str]]]]
+        List of results, where each result is either a string or a dictionary with a single key-value pair.
+        The key in the dictionary must be "children" and the value is a list of strings.
+
+    Returns
+    -------
+    str
+        A JSON-formatted string containing the tree result.
+    """
+    result: dict[str, typing.Any] = {
+        "type": "Tree",
+        "results": results,
+    }
+    return json.dumps(result, indent=4)
+
+
+def create_network_result(
+    origins: list[str],
+    nodes: list[dict[str, str]],
+    edges: list[dict[str, str]],
+) -> str:
+    """
+    Create a network result containing a list of nodes and edges.
+
+    Parameters
+    ----------
+    origins : list[str]
+        List of origin node IDs.
+    nodes : list[dict[str, str]]
+        List of node definitions, where each node is a dictionary with a single key-value pair.
+        The key in the dictionary must be "id" and the value is a string representing the node ID.
+    edges : list[dict[str, str]]
+        List of edge definitions, where each edge is a dictionary with two key-value pairs.
+        The keys in the dictionary must be "from" and "to", and the values are strings representing the node IDs.
+
+    Returns
+    -------
+    str
+        A JSON-formatted string containing the network result.
+    """
+    result: dict[str, typing.Any] = {
+        "type": "Network",
+        "origins": origins,
+        "nodes": nodes,
+        "edges": edges,
+    }
+    return json.dumps(result, indent=4)
+
+
+def create_error_result(message: str) -> str:
+    """Create an error JSON result."""
+    return json.dumps({"type": "Error", "message": message}, indent=4)
+
+
+def respond(result: typing.Any) -> None:
+    """
+    Print the result to stdout.
+
+    Handles both string and object results. If the result has a ``__str__``
+    method (e.g., ``Tree``, ``Network``, ``Table``), it is automatically
+    stringified.
+
+    Parameters
+    ----------
+    result : Any
+        The result to print. Can be a JSON string, a result builder object,
+        or any printable value.
+    """
+    print(result)
+
+
+# ---------------------------------------------------------------------------
+# Cross-platform Image parameter class
+# ---------------------------------------------------------------------------
+
+if os.name == "nt":
+
+    class Image(pathlib.WindowsPath):
+        """Represents an image parameter path in SIERRA (Windows)."""
+
+        pass
+else:
+
+    class Image(pathlib.PosixPath):
+        """Represents an image parameter path in SIERRA (Unix/macOS)."""
+
+        pass
+
+# ---------------------------------------------------------------------------
+# V2 Event Emission Helpers (module-level convenience functions)
+# ---------------------------------------------------------------------------
+
+
+def emit(event_type: str, **kwargs: typing.Any) -> None:
+    """
+    Emit a Protocol V2 streaming event to stdout.
+
+    Parameters
+    ----------
+    event_type : str
+        One of ``"progress"``, ``"result"``, ``"end"``, ``"error"``.
+    **kwargs
+        Additional event fields. ``None`` values are stripped.
+    """
+    event: dict[str, typing.Any] = {"version": 2, "type": event_type}
+    event.update(kwargs)
+    filtered = {k: v for k, v in event.items() if v is not None}
+    print(json.dumps(filtered), flush=True)
+
+
+def emit_progress(message: str) -> None:
+    """Emit a Protocol V2 progress update."""
+    emit("progress", message=message)
+
+
+def emit_result(content: str, id: str | None = None, parent: str | None = None) -> None:
+    """Emit a Protocol V2 incremental graph node."""
+    emit("result", id=id, content=content, parent=parent)
+
+
+def emit_end(summary: str | None = None) -> None:
+    """Emit a Protocol V2 end event."""
+    emit("end", summary=summary)
+
+
+def emit_error(message: str) -> None:
+    """Emit a Protocol V2 error event."""
+    emit("error", message=message)
+
+
+# ---------------------------------------------------------------------------
+# Convenience error class
+# ---------------------------------------------------------------------------
+
+
+class SierraError(Exception):
+    """
+    Convenience exception that auto-formats as a SIERRA error result.
+
+    When raised inside an invoker entry point, the builder's exception
+    handler will catch it and emit either a V1 error JSON or a V2
+    stream error event, depending on the protocol.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable error description.
+
+    Examples
+    --------
+    >>> raise sierra.SierraError("API key expired")
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+    def to_json(self) -> str:
+        """Serialize to a V1 error result JSON string."""
+        return create_error_result(self.message)
+
+    def to_v2_json(self) -> str:
+        """Serialize to a V2 stream error event JSON string."""
+        event = {"version": 2, "type": "error", "message": self.message}
+        return json.dumps(event)
+
+
+__all__ = [
+    # Core invoker
+    "InvokerScript",
+    "Param",
+    "SierraOption",
+    # Result builders
+    "Tree",
+    "Network",
+    "Table",
+    "Timeline",
+    "Chart",
+    # Client & infrastructure
+    "SierraDevelopmentClient",
+    "SierraError",
+    # Result helpers
+    "create_error_result",
+    "create_tree_result",
+    "create_network_result",
+    "respond",
+    # Image type
+    "Image",
+    # V2 streaming
+    "emit",
+    "emit_progress",
+    "emit_result",
+    "emit_end",
+    "emit_error",
+    "StreamEmitter",
+    "stream_context",
+    # Validators
+    "InvokerValidationResult",
+    "validate_node_id",
+    "validate_yaml_safe",
+    "validate_param_type",
+    "validate_protocol",
+    "validate_invoker_name",
+    "sanitize_description",
+]

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/sierra/_about.py

@@ -2,7 +2,7 @@
 Sierra Dev version and metadata.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"
 __title__ = "Sierra Dev"
 __description__ = "Modern framework for building and managing investigation invoker scripts for the Sierra platform"
 __url__ = "https://github.com/xsyncio/sierra-dev"
@@ -13,7 +13,7 @@ __copyright__ = "Copyright 2024 Xsyncio"
 
 # Version info
 VERSION_MAJOR = 2
-VERSION_MINOR = 0
+VERSION_MINOR = 2
 VERSION_PATCH = 0
 VERSION_INFO = (VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH)
 

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/sierra/abc/__init__.py

@@ -21,9 +21,7 @@ Sierra Dev framework.
 """
 
 from sierra.abc.base import SierraABC
-from sierra.abc.sierra import SierraConfig
-from sierra.abc.sierra import SierraInvokerParam
-from sierra.abc.sierra import SierraInvokerScript
+from sierra.abc.sierra import SierraConfig, SierraInvokerParam, SierraInvokerScript
 
 __all__ = [
     "SierraABC",

{sierra_dev-2.0.0 → sierra_dev-2.2.0}/sierra/abc/sierra.py

@@ -1,3 +1,12 @@
+"""
+Sierra ABC Schema Models.
+=========================
+
+Typed dictionary models defining the structural contracts for invoker
+scripts, parameters, and top-level configurations. These are used
+throughout the compiler and builder pipelines.
+"""
+
 import typing
 
 import sierra.abc.base as sierra_abc_base
@@ -10,19 +19,26 @@ class SierraInvokerParam(sierra_abc_base.SierraABC):
     Attributes
     ----------
     Name : str
-        The parameter's name.
-    Description : str | None
+        The parameter's name (must be a valid Python identifier).
+    Description : str or None
         Human-readable description of the parameter.
-    Type : str
-        The data type of the parameter (e.g., 'STRING', 'FILE').
-    Options : list[str] | None
-        List of flags, such as 'PRIMARY' or 'MANDATORY'.
+    Type : Any
+        The data type of the parameter (e.g., ``str``, ``int``, ``pathlib.Path``,
+        ``Image``).
+    Options : list[str] or None
+        List of constraint flags. Supported values:
+        - ``"MANDATORY"`` — execution is blocked if the value is empty.
+        - ``"PRIMARY"`` — SIERRA auto-populates from the active node value.
     """
 
     Name: str
-    Type: str
+    Type: typing.Any
     Description: str | None
-    Options: typing.Literal["MANDATORY"] | None
+    Options: list[str] | None
+    MinValue: int | float | None
+    MaxValue: int | float | None
+    Choices: list[typing.Any] | None
+    Pattern: str | None
 
 
 class SierraInvokerScript(sierra_abc_base.SierraABC):
@@ -33,16 +49,19 @@ class SierraInvokerScript(sierra_abc_base.SierraABC):
     ----------
     Name : str
         Unique name of the script.
-    Description : str | None
+    Description : str or None
         Brief description of the script.
-    Params : list[SierraInvokerParam]
+    Protocol : str or None
+        The execution protocol (``"V1"`` for batch, ``"V2"`` for streaming).
+    Params : list[SierraInvokerParam] or None
         List of parameters for the script.
-    Command : str
+    Command : str or None
         Shell or Python command template, with placeholders for parameters.
     """
 
     Name: str
     Description: str | None
+    Protocol: typing.Literal["V1", "V2"] | None
     Params: list[SierraInvokerParam] | None
     Command: str | None
 
@@ -53,7 +72,7 @@ class SierraConfig(sierra_abc_base.SierraABC):
 
     Attributes
     ----------
-    PATHS : list[str] | None
+    PATHS : list[str] or None
         Optional list of directories to search for scripts.
     SCRIPTS : list[SierraInvokerScript]
         Definitions of all invoker scripts.