maf-sandbox-shell 0.1.0__tar.gz

maf_sandbox_shell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOKOLAI BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maf_sandbox_shell-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: maf-sandbox-shell
+Version: 0.1.0
+Summary: Offline Bash, POSIX shell and PowerShell validation in disposable sandboxes.
+Keywords: shell,bash,powershell,sandbox,agent-framework
+Author: SOKOLAI BV
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: maf-sandbox>=0.51.0,<0.52
+Requires-Dist: agent-framework-core>=1.22.0,<1.23
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-sandbox-shell
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-shell)](https://pypi.org/project/maf-sandbox-shell/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-shell)](https://pypi.org/project/maf-sandbox-shell/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-shell/LICENSE)
+
+> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafSandboxShellExperimentalWarning`.
+
+Validate Bash, POSIX sh, dash and PowerShell scripts with fixed offline analyzers in disposable sandboxes. The host selects the flavor, image and policy; the model supplies an explicit file manifest. Inline lint suppressions are honored and reported.
+
+This package is experimental and has not been released. See the [shell kind guide](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/shell.md) for the accepted design and qualification status.
+
+```python
+from maf_sandbox_shell import ShellFlavor, make_shell_tools
+
+tools = make_shell_tools(
+    router, file_store, agent_id, context,
+    flavor=ShellFlavor.BASH,
+    image="your-qualified-shell-image",
+)
+```
+
+The Bash flavor accepts `.sh`, `.bash`, `.dash` and extensionless files with a supported shebang. PowerShell accepts `.ps1` and `.psm1`; dependencies must be installed in the host image's approved inventory. Both tools require closed egress, POSIX, `EXEC`, `FILES_IN`, call isolation and disposal. Validation never writes the host file store or deploys infrastructure.
+
+Completed checks return `clean` or `findings`. Every unsuppressed severity counts by default; the host can set a threshold and excluded rules through `ShellPolicy`. Unfinished analysis returns no verdict. Exact diagnostics and suppression details remain untrusted workload output; trusted summaries use package-owned text and `files[N]` references.

maf_sandbox_shell-0.1.0/README.md

@@ -0,0 +1,23 @@
+# maf-sandbox-shell
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-shell)](https://pypi.org/project/maf-sandbox-shell/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-shell)](https://pypi.org/project/maf-sandbox-shell/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-shell/LICENSE)
+
+> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafSandboxShellExperimentalWarning`.
+
+Validate Bash, POSIX sh, dash and PowerShell scripts with fixed offline analyzers in disposable sandboxes. The host selects the flavor, image and policy; the model supplies an explicit file manifest. Inline lint suppressions are honored and reported.
+
+This package is experimental and has not been released. See the [shell kind guide](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/shell.md) for the accepted design and qualification status.
+
+```python
+from maf_sandbox_shell import ShellFlavor, make_shell_tools
+
+tools = make_shell_tools(
+    router, file_store, agent_id, context,
+    flavor=ShellFlavor.BASH,
+    image="your-qualified-shell-image",
+)
+```
+
+The Bash flavor accepts `.sh`, `.bash`, `.dash` and extensionless files with a supported shebang. PowerShell accepts `.ps1` and `.psm1`; dependencies must be installed in the host image's approved inventory. Both tools require closed egress, POSIX, `EXEC`, `FILES_IN`, call isolation and disposal. Validation never writes the host file store or deploys infrastructure.
+
+Completed checks return `clean` or `findings`. Every unsuppressed severity counts by default; the host can set a threshold and excluded rules through `ShellPolicy`. Unfinished analysis returns no verdict. Exact diagnostics and suppression details remain untrusted workload output; trusted summaries use package-owned text and `files[N]` references.

maf_sandbox_shell-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "maf-sandbox-shell"
+version = "0.1.0"
+description = "Offline Bash, POSIX shell and PowerShell validation in disposable sandboxes."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "shell",
+    "bash",
+    "powershell",
+    "sandbox",
+    "agent-framework",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "maf-sandbox>=0.51.0,<0.52",
+    "agent-framework-core>=1.22.0,<1.23",
+]
+
+[[project.authors]]
+name = "SOKOLAI BV"
+email = "info@sokolai.com"
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.sources.maf-sandbox]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_shell"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+    "E501",
+    "W505",
+    "TD",
+    "FIX",
+    "ERA001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+    "E501",
+    "W505",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_shell-0.1.0/pyproject.toml.orig

@@ -0,0 +1,57 @@
+[project]
+name = "maf-sandbox-shell"
+version = "0.1.0"
+description = "Offline Bash, POSIX shell and PowerShell validation in disposable sandboxes."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["shell", "bash", "powershell", "sandbox", "agent-framework"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+dependencies = ["maf-sandbox>=0.51.0,<0.52", "agent-framework-core>=1.22.0,<1.23"]
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.sources]
+maf-sandbox = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_shell"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104", "E501", "W505", "TD", "FIX", "ERA001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D101", "D103", "E501", "W505"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_shell-0.1.0/src/maf_sandbox_shell/__init__.py

@@ -0,0 +1,44 @@
+"""Offline shell script validation for Microsoft Agent Framework."""
+
+import warnings as _warnings
+
+from ._spec import (
+    SHELL_TOOL_NAMES,
+    ShellDialect,
+    ShellFlavor,
+    ShellPolicy,
+    ShellSeverity,
+    shell_sandbox_spec,
+)
+from ._tool import make_shell_tools
+
+__all__ = [
+    "MafSandboxShellExperimentalWarning",
+    "SHELL_TOOL_NAMES",
+    "ShellDialect",
+    "ShellFlavor",
+    "ShellPolicy",
+    "ShellSeverity",
+    "make_shell_tools",
+    "shell_sandbox_spec",
+]
+
+
+class MafSandboxShellExperimentalWarning(UserWarning):
+    """Warning category for the experimental shell workload package."""
+
+
+def _warn_experimental() -> None:
+    try:
+        _warnings.warn(
+            "maf_sandbox_shell is experimental and may change or be removed in future "
+            "versions without notice.",
+            category=MafSandboxShellExperimentalWarning,
+            stacklevel=2,
+        )
+    except MafSandboxShellExperimentalWarning:
+        # An informational warning must not block imports under -Werror.
+        pass
+
+
+_warn_experimental()

maf_sandbox_shell-0.1.0/src/maf_sandbox_shell/_paths.py

@@ -0,0 +1,79 @@
+"""Resolve explicit file manifests without exposing names in refusal messages."""
+
+import posixpath
+import re
+
+from maf_sandbox import ListedFile
+
+from ._spec import ShellDialect, ShellFlavor
+
+_RESERVED = {".shellcheckrc", "shellcheckrc", "psscriptanalyzersettings.psd1"}
+
+
+def normalize(name: object) -> str:
+    """Accept bounded store-relative paths, including leading-hyphen basenames."""
+    if (
+        not isinstance(name, str)
+        or not name
+        or len(name) > 512
+        or not re.fullmatch(r"[A-Za-z0-9._/-]+", name)
+        or name.startswith("/")
+        or name.endswith("/")
+        or ".." in name.split("/")
+        or any(part.lower() in _RESERVED for part in name.split("/"))
+    ):
+        raise ValueError("The manifest contains an unsupported or reserved path.")
+    path = posixpath.normpath(name)
+    if path == ".":
+        raise ValueError("Every manifest entry must name a file.")
+    return path
+
+
+def resolve_manifest(
+    files: list[str], listing: list[ListedFile], flavor: ShellFlavor
+) -> list[tuple[str, ListedFile]]:
+    """Keep listing objects for provenance and refuse ambiguous normalized names."""
+    paths = [normalize(name) for name in files]
+    if len(set(paths)) != len(paths):
+        raise ValueError("The manifest contains duplicate destinations.")
+    indexed: dict[str, ListedFile] = {}
+    for item in listing:
+        try:
+            path = normalize(item.name)
+        except ValueError:
+            continue
+        if path in indexed:
+            raise ValueError("The file listing contains ambiguous normalized paths.")
+        indexed[path] = item
+    for path in paths:
+        suffix = posixpath.splitext(path)[1].lower()
+        allowed = {".ps1", ".psm1"} if flavor == ShellFlavor.PWSH else {".sh", ".bash", ".dash", ""}
+        if suffix not in allowed:
+            raise ValueError("The manifest contains a file unsupported by this shell flavor.")
+        if path not in indexed:
+            raise ValueError("A manifest file is absent from this tool's file listing.")
+    return [(path, indexed[path]) for path in paths]
+
+
+def dialect_for(path: str, text: str, default: ShellDialect) -> ShellDialect:
+    """Select a fixed grammar without executing or forwarding the shebang."""
+    suffix = posixpath.splitext(path)[1].lower()
+    named = {".bash": ShellDialect.BASH, ".dash": ShellDialect.DASH}.get(suffix)
+    if text.startswith("#!"):
+        words = text.splitlines()[0][2:].strip().split()
+        if len(words) == 2 and words[0] == "/usr/bin/env":
+            executable = words[1]
+        elif len(words) == 1 and words[0].startswith("/"):
+            executable = posixpath.basename(words[0])
+        else:
+            raise ValueError("The shebang is not a supported fixed shell declaration.")
+        try:
+            dialect = ShellDialect(executable)
+        except ValueError:
+            raise ValueError("The shebang names an unsupported shell dialect.") from None
+        if named is not None and named != dialect:
+            raise ValueError("The file extension and shebang declare conflicting dialects.")
+        return dialect
+    if not suffix:
+        raise ValueError("An extensionless shell file requires a supported shebang.")
+    return named or default

maf_sandbox_shell-0.1.0/src/maf_sandbox_shell/_report.py

@@ -0,0 +1,232 @@
+"""Validate complete analyzer envelopes and separate finite summaries from guest prose."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any, cast
+
+from ._spec import SEVERITIES, ShellFlavor, ShellPolicy, ShellSeverity
+
+MAX_REPORT_BYTES = 1024 * 1024
+EMPTY_INVENTORY_SHA256 = hashlib.sha256(b"{}\n").hexdigest()
+IDENTITY = {
+    "launcher": "maf-shell-v1",
+    "bash": "5.2.15-2+b13",
+    "dash": "0.5.12-2",
+    "shellcheck": "0.11.0",
+    "powershell": "7.6.7",
+    "psscriptanalyzer": "1.25.0",
+}
+_CATALOG = {
+    "SC1090": "A dynamically selected source could not be followed.",
+    "SC1091": "A referenced source could not be read.",
+    "SC2034": "A variable appears unused.",
+    "SC2046": "Quote command substitution to prevent word splitting.",
+    "SC2086": "Quote variable expansion to prevent splitting and globbing.",
+    "SC2154": "A variable is referenced without an assignment.",
+    "SC2162": "Use read -r to preserve backslashes.",
+    "SC2164": "Handle failure when changing directories.",
+    "PSAvoidUsingCmdletAliases": "Use a command's full name instead of an alias.",
+    "PSAvoidUsingWriteHost": "Choose an output stream appropriate to the caller.",
+    "PSAvoidUsingInvokeExpression": "Avoid evaluating strings as PowerShell code.",
+    "PSAvoidUsingPlainTextForPassword": "Use a credential type for password parameters.",
+    "PSUseDeclaredVarsMoreThanAssignments": "A variable appears unused.",
+    "PSUseApprovedVerbs": "Use an approved verb in a function name.",
+    "PSParseError": "PowerShell could not parse the source.",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    """Only a completed analysis can carry a verdict; details always remain untrusted."""
+
+    completed: bool
+    verdict: str | None
+    summary: tuple[str, ...]
+    detail: str
+
+
+def _object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _nonfinite(value: str) -> Any:
+    raise ValueError("nonfinite JSON value")
+
+
+def _mapping(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("expected object")
+    return cast(dict[str, Any], value)
+
+
+def _list(value: Any) -> list[Any]:
+    if not isinstance(value, list):
+        raise ValueError("expected array")
+    return cast(list[Any], value)
+
+
+def _position(value: dict[str, Any]) -> None:
+    if any(
+        type(value.get(key)) is not int or not 0 <= value[key] <= 2**31
+        for key in ("line", "column")
+    ):
+        raise ValueError("invalid source location")
+
+
+def _diagnostic(value: Any, paths: list[str]) -> dict[str, Any]:
+    item = _mapping(value)
+    _position(item)
+    if (
+        item.get("file") not in paths
+        or item.get("severity") not in SEVERITIES
+        or not isinstance(item.get("rule"), str)
+        or not item["rule"]
+        or not isinstance(item.get("message"), str)
+    ):
+        raise ValueError("invalid diagnostic")
+    return item
+
+
+def _suppression(value: Any, flavor: ShellFlavor) -> None:
+    item = _mapping(value)
+    _position(item)
+    if flavor == ShellFlavor.PWSH:
+        if not isinstance(item.get("text"), str) or not item["text"]:
+            raise ValueError("invalid suppression declaration")
+        return
+    ranges = _list(item.get("rules"))
+    if not ranges:
+        raise ValueError("empty suppression declaration")
+    for value in ranges:
+        span = _mapping(value)
+        if any(
+            type(span.get(key)) is not int or span[key] < 0 for key in ("first", "end_exclusive")
+        ):
+            raise ValueError("invalid suppression range")
+    if item.get("scope") is not None:
+        scope = _mapping(item["scope"])
+        _position(_mapping(scope.get("start")))
+        _position(_mapping(scope.get("end")))
+
+
+def report_outcome(
+    raw: bytes,
+    flavor: ShellFlavor,
+    paths: list[str],
+    policy: ShellPolicy,
+    inventory_sha256: str = EMPTY_INVENTORY_SHA256,
+    *,
+    hidden: bool = False,
+) -> Outcome:
+    """Recompute verdicts from diagnostics, honoring inline suppressions and host policy."""
+    if len(raw) > MAX_REPORT_BYTES:
+        raise ValueError("report exceeds bound")
+    envelope = _mapping(
+        json.loads(raw.decode("utf-8"), object_pairs_hook=_object, parse_constant=_nonfinite)
+    )
+    if (
+        type(envelope.get("protocol")) is not int
+        or envelope["protocol"] != 1
+        or envelope.get("identity") != IDENTITY
+        or envelope.get("flavor") != flavor
+        or "error" not in envelope
+    ):
+        raise ValueError("unsupported launcher identity")
+    if envelope["error"] is not None:
+        return Outcome(
+            False, None, ("Validation incomplete: the bounded analyzer did not finish.",), ""
+        )
+    if envelope.get("dependency_inventory_sha256") != inventory_sha256:
+        raise ValueError("unexpected host dependency inventory")
+    reports = [_mapping(item) for item in _list(envelope.get("files"))]
+    if [item.get("path") for item in reports] != paths:
+        raise ValueError("report does not cover the complete manifest")
+    completed = True
+    findings = False
+    summaries: set[str] = set()
+    details: list[dict[str, Any]] = []
+    for report in reports:
+        if (
+            type(report.get("parsed")) is not bool
+            or type(report.get("policy_conflict")) is not bool
+        ):
+            raise ValueError("missing analyzer completion")
+        syntax = _mapping(report.get("syntax"))
+        if (
+            type(syntax.get("exit_code")) is not int
+            or not isinstance(syntax.get("stdout"), str)
+            or not isinstance(syntax.get("stderr"), str)
+        ):
+            raise ValueError("invalid syntax phase")
+        completed &= report["parsed"] and not report["policy_conflict"] and syntax["exit_code"] == 0
+        diagnostics = [_diagnostic(item, paths) for item in _list(report.get("diagnostics"))]
+        suppressed = [
+            _diagnostic(item, paths) for item in _list(report.get("suppressed_diagnostics"))
+        ]
+        declarations = _list(report.get("suppressions"))
+        for declaration in declarations:
+            _suppression(declaration, flavor)
+        if declarations or suppressed:
+            summaries.add("Inline suppressions are present; see the untrusted audit report.")
+        excluded = [item for item in diagnostics if item["rule"] in policy.excluded_rules]
+        effective = [item for item in diagnostics if item["rule"] not in policy.excluded_rules]
+        findings |= any(
+            SEVERITIES.index(ShellSeverity(item["severity"]))
+            <= SEVERITIES.index(policy.minimum_severity)
+            for item in effective
+        )
+        for item in effective:
+            if item["rule"] in _CATALOG:
+                index = paths.index(item["file"])
+                summaries.add(
+                    f"files[{index}]: {item['severity']} {item['rule']}. {_CATALOG[item['rule']]}"
+                )
+            else:
+                summaries.add("Additional analyzer findings are available in the untrusted report.")
+        details.append(
+            {
+                **report,
+                "counts": {
+                    severity: sum(item["severity"] == severity for item in effective)
+                    for severity in SEVERITIES
+                },
+                "suppressed_counts": dict(Counter(item["severity"] for item in suppressed)),
+                "suppression_declarations": len(declarations),
+                "suppressed_findings": len(suppressed),
+                "host_excluded_findings": len(excluded),
+            }
+        )
+    if not completed:
+        summaries.add(
+            "Validation incomplete: syntax, lint or suppression auditing could not complete."
+        )
+    elif not findings:
+        summaries.add("No unsuppressed diagnostic meets the configured threshold.")
+    if policy.excluded_rules:
+        summaries.add("Host rule exclusions are active.")
+    return Outcome(
+        completed,
+        ("findings" if findings else "clean") if completed else None,
+        tuple(sorted(summaries)),
+        ""
+        if hidden
+        else json.dumps(
+            {
+                "files": details,
+                "policy": {
+                    "minimum_severity": policy.minimum_severity,
+                    "excluded_rules": policy.excluded_rules,
+                },
+            },
+            ensure_ascii=True,
+        ),
+    )

maf_sandbox_shell-0.1.0/src/maf_sandbox_shell/_spec.py

@@ -0,0 +1,93 @@
+"""Host-selected analyzers and the boundary required for static shell validation."""
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+from maf_sandbox import (
+    Capability,
+    Cleanup,
+    Egress,
+    Isolation,
+    IsolationScope,
+    OsFamily,
+    SandboxSpec,
+)
+
+
+class ShellFlavor(StrEnum):
+    """The analyzer family enabled by the host."""
+
+    BASH = "bash"
+    PWSH = "pwsh"
+
+
+class ShellDialect(StrEnum):
+    """The fixed POSIX-family grammars supported by the Bash flavor."""
+
+    BASH = "bash"
+    SH = "sh"
+    DASH = "dash"
+
+
+class ShellSeverity(StrEnum):
+    """Diagnostic thresholds, from the most restrictive to the most inclusive."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    STYLE = "style"
+
+
+SHELL_TOOL_NAMES: frozenset[str] = frozenset({"bash_validate", "pwsh_validate"})
+SEVERITIES = tuple(ShellSeverity)
+
+
+@dataclass(frozen=True, slots=True)
+class ShellPolicy:
+    """Immutable host policy; inline suppressions remain honored and reported.
+
+    ``default_dialect`` applies only to shebangless .sh files. PowerShell dependencies are
+    supplied by the selected image's inventory, never by tool arguments.
+    """
+
+    minimum_severity: ShellSeverity = ShellSeverity.STYLE
+    excluded_rules: tuple[str, ...] = ()
+    default_dialect: ShellDialect = ShellDialect.BASH
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "minimum_severity", ShellSeverity(self.minimum_severity))
+        object.__setattr__(self, "default_dialect", ShellDialect(self.default_dialect))
+        if (
+            type(self.excluded_rules) is not tuple
+            or len(self.excluded_rules) > 256
+            or any(
+                type(rule) is not str
+                or not re.fullmatch(r"SC[0-9]{4,6}|PS[A-Za-z][A-Za-z0-9]{1,100}", rule)
+                for rule in self.excluded_rules
+            )
+            or len(set(self.excluded_rules)) != len(self.excluded_rules)
+        ):
+            raise ValueError("excluded_rules must be a bounded tuple of distinct rule IDs")
+
+
+def shell_sandbox_spec(
+    image: str | None = None,
+    image_id: str | None = None,
+    *,
+    flavor: ShellFlavor,
+) -> SandboxSpec:
+    """Require a fresh closed-network POSIX sandbox with disposal after every call."""
+    return SandboxSpec(
+        kind=ShellFlavor(flavor).value,
+        image=image,
+        image_id=image_id,
+        work_dir=None,
+        egress=Egress.CLOSED,
+        requires=frozenset({Capability.EXEC, Capability.FILES_IN}),
+        requires_os_family=OsFamily.POSIX,
+        min_isolation=Isolation.CONTAINER,
+        isolation_scope=IsolationScope.CALL,
+        min_cleanup=Cleanup.DISPOSE,
+        confined_to_guest_call_path=False,
+    )

maf_sandbox_shell-0.1.0/src/maf_sandbox_shell/_tool.py

@@ -0,0 +1,206 @@
+"""Attach a host-selected analyzer through the shared sandbox session lifecycle."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import math
+import re
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from maf_sandbox import CallerContext, SandboxRouter, SourceIntegrity, error_detail
+from maf_sandbox.maf import (
+    SandboxResult,
+    SandboxToolSession,
+    positions_holding_hidden_content,
+    sandboxed_tool,
+)
+
+from ._paths import dialect_for, resolve_manifest
+from ._report import EMPTY_INVENTORY_SHA256, report_outcome
+from ._spec import ShellFlavor, ShellPolicy, shell_sandbox_spec
+
+if TYPE_CHECKING:
+    from agent_framework import AgentFileStore
+    from maf_sandbox import FileStoreProvenance
+
+logger = logging.getLogger(__name__)
+VERDICTS = ("clean", "findings")
+STANDING_GUIDANCE = (
+    "Static validation does not establish runtime or deployment success. Raw diagnostics, "
+    "locations, counts and suppression declarations are untrusted. Use completion and the verdict "
+    "to determine the result. Inline suppressions are honored; clean can include suppressed "
+    "findings. Trusted summaries use fixed rule descriptions and files[N] references only. "
+    "This tool does not execute scripts, install dependencies, rewrite files or update the store."
+)
+
+
+def make_shell_tools(
+    router: SandboxRouter | None,
+    file_store: AgentFileStore,
+    agent_id: str,
+    context: CallerContext,
+    *,
+    flavor: ShellFlavor,
+    policy: ShellPolicy = ShellPolicy(),
+    image: str | None = None,
+    image_id: str | None = None,
+    exec_timeout_seconds: float = 120,
+    dependency_inventory_sha256: str = EMPTY_INVENTORY_SHA256,
+    file_store_provenance: FileStoreProvenance | None = None,
+) -> list[Any]:
+    """Enable one flavor; the host fixes policy, image, dependency inventory and shared deadline."""
+    flavor = ShellFlavor(flavor)
+    if type(policy) is not ShellPolicy:
+        raise TypeError("policy must be ShellPolicy")
+    if (
+        isinstance(exec_timeout_seconds, bool)
+        or not math.isfinite(exec_timeout_seconds)
+        or not 0 < exec_timeout_seconds <= 600
+    ):
+        raise ValueError("exec_timeout_seconds must be finite and in (0, 600]")
+    if not re.fullmatch(r"[a-f0-9]{64}", dependency_inventory_sha256):
+        raise ValueError("dependency_inventory_sha256 must be a SHA256 digest")
+    return sandboxed_tool(
+        lambda session: _build_tool(
+            session, file_store, flavor, policy, exec_timeout_seconds, dependency_inventory_sha256
+        ),
+        router=router,
+        context=context,
+        agent_id=agent_id,
+        spec=shell_sandbox_spec(image, image_id, flavor=flavor),
+        name=f"{flavor}_validate",
+        source_integrity=SourceIntegrity.UNTRUSTED,
+        result_contract=True,
+        verdicts=VERDICTS,
+        standing_guidance=(STANDING_GUIDANCE,),
+        file_store_provenance=file_store_provenance,
+        admission_timeout=max(30, exec_timeout_seconds),
+        logger=logger,
+    )
+
+
+def _incomplete(message: str, detail: str | None = None) -> SandboxResult:
+    return SandboxResult(
+        completed=False, trusted_output=(message,), output=(detail,) if detail else ()
+    )
+
+
+def _build_tool(
+    session: SandboxToolSession,
+    store: AgentFileStore,
+    flavor: ShellFlavor,
+    policy: ShellPolicy,
+    timeout: float,
+    inventory_sha256: str,
+) -> Callable[..., Awaitable[SandboxResult]]:
+    async def validate(files: list[str]) -> SandboxResult:
+        """Parse and lint the explicitly listed shell scripts without executing their commands.
+
+        Supply store-relative paths. Bash flavor accepts .sh, .bash, .dash and extensionless
+        scripts with a supported shebang. PowerShell accepts .ps1 and .psm1. Include sourced
+        shell files in this list. PowerShell dependencies must be preinstalled by the host;
+        submitted modules are analysis inputs. Inline suppressions are honored and reported.
+        """
+        key = session.key()
+        if isinstance(key, str):
+            return _incomplete(key)
+        hidden = positions_holding_hidden_content(files, argument="files")
+        limits = session.spec.files_in
+        if not files or len(files) > min(64, limits.max_files):
+            return _incomplete(
+                "Validation incomplete: the manifest is empty or exceeds the file limit."
+            )
+        listing = await session.list_files(store)
+        if isinstance(listing, str):
+            return _incomplete(
+                "Validation incomplete: the file store could not be listed.", listing
+            )
+        try:
+            selected = resolve_manifest(files, listing, flavor)
+        except ValueError as exc:
+            return _incomplete(f"Validation incomplete: {exc}")
+        sources: list[dict[str, str]] = []
+        total = 0
+        for index, (path, listed) in enumerate(selected):
+            item = await session.read_file(
+                store, listed, at=f"files[{index}]", hidden=index in hidden, named=f"files[{index}]"
+            )
+            if isinstance(item, str):
+                return _incomplete(item)
+            if item is None or item.text is None or "\x00" in item.text:
+                return _incomplete("Validation incomplete: every manifest file must contain text.")
+            try:
+                size = len(item.text.encode("utf-8"))
+                dialect = (
+                    dialect_for(path, item.text, policy.default_dialect)
+                    if flavor == ShellFlavor.BASH
+                    else "pwsh"
+                )
+            except (ValueError, UnicodeError):
+                return _incomplete(
+                    "Validation incomplete: invalid text or conflicting shell declarations."
+                )
+            total += size
+            if size > limits.max_bytes_per_file or total > limits.max_total_bytes:
+                return _incomplete(
+                    "Validation incomplete: the manifest exceeds the transfer byte limits."
+                )
+            sources.append({"path": path, "text": item.text, "dialect": dialect})
+        bundle = json.dumps({"flavor": flavor, "files": sources}, ensure_ascii=True)
+        if len(bundle.encode("utf-8")) > min(limits.max_bytes_per_file, 16 * 1024 * 1024):
+            return _incomplete(
+                "Validation incomplete: the source bundle exceeds the transfer limit."
+            )
+        sandbox = await session.acquire(key)
+        if isinstance(sandbox, str):
+            return _incomplete("Validation incomplete: the sandbox could not be acquired.", sandbox)
+        guest_call_path = session.guest_call_path()
+        try:
+            await sandbox.write_file("request.json", bundle, working_directory=guest_call_path)
+            execution = asyncio.create_task(
+                sandbox.exec(
+                    ["/usr/local/bin/python3", "-I", "/opt/maf-shell/runner.py", str(timeout)],
+                    working_directory=guest_call_path,
+                    timeout=timeout + 5,
+                )
+            )
+            try:
+                result = await asyncio.shield(execution)
+            except asyncio.CancelledError:
+                while not execution.done():
+                    try:
+                        await asyncio.shield(execution)
+                    except (asyncio.CancelledError, Exception):
+                        # Keep the sandbox alive until the shielded execution finishes.
+                        pass
+                if not execution.cancelled():
+                    execution.exception()
+                raise
+            if result.exit_code != 0 or result.producer_owns_stderr or result.stderr_bytes:
+                return _incomplete(
+                    "Validation incomplete: the launcher did not return a complete report."
+                )
+            outcome = report_outcome(
+                result.stdout_bytes,
+                flavor,
+                [path for path, _ in selected],
+                policy,
+                inventory_sha256,
+                hidden=bool(hidden),
+            )
+            return SandboxResult(
+                completed=outcome.completed,
+                verdict=outcome.verdict,
+                trusted_output=outcome.summary,
+                output=(outcome.detail,) if outcome.detail else (),
+            )
+        except Exception as exc:
+            logger.warning("shell validation failed: %s", error_detail(exc))
+            return _incomplete(
+                "Validation incomplete: staging, execution or report verification failed."
+            )
+
+    return validate