opsscript-gate 0.4.0__tar.gz → 0.4.1__tar.gz

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-09-19
+
+### Fixed & Hardened
+- **Bounded container log capture**: Stream-captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), bounding retained container log data to reduce memory-exhaustion risk from runaway output.
+- **Workflow command neutralization**: Neutralizes untrusted container logs starting with `::` into `[container] ::` to prevent malicious scripts from forging GitHub Actions workflow commands in Runner consoles, while keeping OpsScript Gate's own annotations intact.
+- **Terminal ANSI and control character sanitization**: Strips ANSI escape sequences (CSI, OSC, 2-byte escapes), removes dangerous C0 control characters and DEL, and normalizes CRLF and standalone carriage returns (`\r`) to defeat terminal line overwrite and status spoofing, while preserving printable Unicode.
+- **Context-sensitive Markdown and HTML injection defense**: Implemented dedicated escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent table cell tearing, HTML container breakout (`</details>`), premature code fence closure, and structural Markdown injection from runtime-derived values.
+- **Bounded streaming script preparation**: Stream-normalizes CRLF in bounded 64 KiB chunks (`SCRIPT_READ_CHUNK_SIZE`), properly handling boundary-split CRLF while preserving lone CR bytes without whole-file memory allocation. Bounded shebang parsing to 4096 bytes (`MAX_SHEBANG_BYTES`).
+- **Parallel matrix script preparation deduplication**: Pre-normalizes scripts once before parallel matrix execution, sharing the prepared file read-only across worker threads and centralizing cleanup to eliminate file locking and race conditions on Windows.
+- **Shebang evaluation refactoring**: Deduplicated shebang resolution across `shebang` and `auto` modes via `_resolve_shell_command`.
+- **Regression test coverage**: Added extensive adversarial and edge-case tests covering oversized streams, boundary splits, workflow spoofing, Markdown injections, and error branches.
+
+---
+
 ## [0.4.0] - 2026-09-19
 
 ### Added

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.4.0
+Version: 0.4.1
 Summary: Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures
 Project-URL: Homepage, https://github.com/Mresyzz/opsscript-gate
 Project-URL: Repository, https://github.com/Mresyzz/opsscript-gate
@@ -58,7 +58,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.4.1
 ```
 
 > **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
@@ -66,7 +66,7 @@ jobs:
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.4.1
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -212,10 +212,17 @@ OpsScript Gate applies conservative, restricted container defaults when running
 5. **Hard Timeout & Container Cleanup**:
    - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
    - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
-6. **Command Injection Defense**:
-   - Workflow commands (`::error`) apply strict percent-encoding for all properties and message bodies, preventing unclassified container logs from injecting GitHub Actions workflow commands.
-7. **Windows CRLF Defense**:
-   - Automatically detects and normalizes carriage returns (`\r\n` -> `\n`) before container execution, preventing false `\r: command not found` errors.
+6. **Bounded Output & Memory Protection**:
+   - Captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), which bounds retained container log data to reduce memory-exhaustion risk.
+7. **Untrusted Log Neutralization & Terminal Defense**:
+   - Neutralizes line-leading workflow commands (`[container] ::`) to prevent forged GitHub Actions annotations in CI runners.
+   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line overwrite spoofing.
+   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent Step Summary layout disruptions.
+8. **Command Injection Defense**:
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+9. **Bounded Streaming CRLF & Shebang Defense**:
+   - Stream-normalizes carriage returns in 64 KiB chunks, preserving lone CR bytes and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
+   - Pre-normalizes scripts once before parallel matrix runs, sharing a read-only prepared path across worker threads.
 
 ---
 

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/README.md

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.4.1
 ```
 
 > **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
@@ -38,7 +38,7 @@ jobs:
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.4.1
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -184,10 +184,17 @@ OpsScript Gate applies conservative, restricted container defaults when running
 5. **Hard Timeout & Container Cleanup**:
    - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
    - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
-6. **Command Injection Defense**:
-   - Workflow commands (`::error`) apply strict percent-encoding for all properties and message bodies, preventing unclassified container logs from injecting GitHub Actions workflow commands.
-7. **Windows CRLF Defense**:
-   - Automatically detects and normalizes carriage returns (`\r\n` -> `\n`) before container execution, preventing false `\r: command not found` errors.
+6. **Bounded Output & Memory Protection**:
+   - Captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), which bounds retained container log data to reduce memory-exhaustion risk.
+7. **Untrusted Log Neutralization & Terminal Defense**:
+   - Neutralizes line-leading workflow commands (`[container] ::`) to prevent forged GitHub Actions annotations in CI runners.
+   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line overwrite spoofing.
+   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent Step Summary layout disruptions.
+8. **Command Injection Defense**:
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+9. **Bounded Streaming CRLF & Shebang Defense**:
+   - Stream-normalizes carriage returns in 64 KiB chunks, preserving lone CR bytes and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
+   - Pre-normalizes scripts once before parallel matrix runs, sharing a read-only prepared path across worker threads.
 
 ---
 

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/SECURITY.md

@@ -7,8 +7,7 @@ Only the latest release of **OpsScript Gate** receives security updates and bug
 | Version | Supported          |
 | :---    | :---:              |
 | 0.4.x   | :white_check_mark: |
-| 0.3.x   | :white_check_mark: |
-| < 0.3.0 | :x:                |
+| < 0.4.0 | :x:                |
 
 ---
 
@@ -32,9 +31,12 @@ Reports will be reviewed as maintainer availability allows.
 
 OpsScript Gate is not a security sandbox for untrusted code. Containers may run as the image's default user, and Docker containers still share the host kernel.
 
-OpsScript Gate applies conservative container defaults when running scripts:
+OpsScript Gate applies conservative container defaults and hardened I/O boundaries when running scripts:
 - **Restricted Container Defaults**: Containers run with `privileged=False`, `cap_drop=["ALL"]`, and `security_opt=["no-new-privileges:true"]`.
 - **Resource Limits & Isolation**: Enforces memory caps (`--mem-limit`, default 256m), process table caps (`--pids-limit`, default 128), and optional network isolation (`--network none`).
 - **Read-Only Mounting**: Target scripts are mounted read-only (`:ro`). OpsScript Gate does not mount additional host filesystem paths into test containers.
 - **Resource Protection & Hard Timeout**: Containers are subject to hard timeouts (default 60s) with `SIGKILL` termination. Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
-- **Workflow Command Injection Defense**: All GitHub Actions workflow commands (`::error`) apply strict percent-encoding for properties (`%`, `\r`, `\n`, `:`, `,`) and data (`%`, `\r`, `\n`), completely preventing command injection from unclassified container output.
+- **Bounded Output & Rolling Buffer**: Container output capture is strictly bounded by tail lines (500) and byte caps (256 KiB) via an immediate rolling byte buffer, bounding retained container log data to reduce memory-exhaustion risk.
+- **Untrusted Log Neutralization**: Container logs neutralize line-leading workflow commands (`[container] ::`), strip terminal ANSI/CSI/OSC sequences and dangerous C0 control characters, and apply context-sensitive Markdown/HTML escaping to protect Step Summaries.
+- **Workflow Command Encoding**: OpsScript Gate's own GitHub Actions annotations (`::error`) apply strict percent-encoding for properties (`%`, `\r`, `\n`, `:`, `,`) and data (`%`, `\r`, `\n`), protecting GitHub Actions workflow-command fields against injection.
+- **Bounded Streaming I/O**: Script preparation and line ending normalization operate in bounded 64 KiB chunks, and shebang line inspection is bounded to 4096 bytes.

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opsscript-gate"
-version = "0.4.0"
+version = "0.4.1"
 description = "Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures"
 readme = "README.md"
 license = { text = "MIT" }

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/src/opsscript_gate/__init__.py

@@ -1,4 +1,4 @@
 """OpsScript Gate: Lightweight cross-distro compatibility pre-check for Linux ops scripts."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 __all__ = ["__version__"]

{opsscript_gate-0.4.0 → opsscript_gate-0.4.1}/src/opsscript_gate/reporter.py

@@ -1,10 +1,110 @@
-from __future__ import annotations
-
+import html
 import json
 import os
+import re
 import sys
 from opsscript_gate.models import DistroStatus, MultiScriptReport, RunReport, SingleResult
 
+# Structure-altering Markdown characters in regular prose:
+# \ ` * _ [ ] ( ) # + - ! > ~ |
+_MARKDOWN_SPECIAL_RE = re.compile(r"([\\`*_{}\[\]()#+\-.!>~|])")
+
+
+def escape_inline_code(text: str) -> str:
+    """
+    Escape text for safe inclusion inside Markdown inline code spans (`...`).
+    Replaces backticks with single quotes and strips newlines to prevent code-span breakouts.
+    """
+    if not text:
+        return ""
+    cleaned = text.replace("\r\n", " ").replace("\r", " ").replace("\n", " ")
+    return cleaned.replace("`", "'")
+
+
+def escape_markdown_text(text: str) -> str:
+    """
+    Escape structure-altering characters in normal Markdown text.
+    Prevents headings, blockquotes, raw HTML, links, and formatting injection
+    while preserving standard technical terms like 'non-zero' or 'x86_64'.
+    """
+    if not text:
+        return ""
+    # Neutralize HTML tags and entities
+    text = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    # Escape brackets, parentheses, pipes, backticks, and backslashes to prevent links/code spans
+    text = text.replace("\\", "\\\\")
+    text = text.replace("`", "\\`").replace("[", "\\[").replace("]", "\\]")
+    text = text.replace("(", "\\(").replace(")", "\\)").replace("|", "\\|")
+
+    # Neutralize line-leading markdown structures (headings, blockquotes, list markers)
+    def _neutralize_line_start(m: re.Match) -> str:
+        lead, ch = m.group(1), m.group(2)
+        if ch in ("#", ">", "-", "+", "*"):
+            return f"{lead}\\{ch}"
+        return m.group(0)
+
+    return re.sub(r"^(\s*)([#>+\-*])", _neutralize_line_start, text, flags=re.MULTILINE)
+
+
+def escape_markdown_table_cell(text: str) -> str:
+    """
+    Escape content for safe inclusion in Markdown table cells.
+    Replaces newlines with spaces, escapes pipe characters,
+    and neutralizes HTML details/summary container tags to prevent breaking summary layout.
+    """
+    if not text:
+        return ""
+    cleaned = text.replace("\r\n", " ").replace("\r", " ").replace("\n", " ")
+    # Neutralize details/summary tags that could break surrounding HTML layout
+    cleaned = (
+        cleaned.replace("</details>", "<\\/details>")
+        .replace("<details>", "<\\details>")
+        .replace("</summary>", "<\\/summary>")
+        .replace("<summary>", "<\\summary>")
+    )
+    return cleaned.replace("|", "\\|")
+
+
+def escape_html_text(text: str) -> str:
+    """
+    Escape text for safe inclusion in HTML tags and attributes (e.g. <summary>).
+    """
+    if not text:
+        return ""
+    return html.escape(text, quote=True)
+
+
+def format_safe_code_fence(content: str, language: str = "text") -> list[str]:
+    """
+    Safely enclose content in a markdown code block.
+    Dynamically adjusts backtick count to prevent premature closing,
+    and neutralizes closing HTML tags (e.g. </details>) that could break surrounding containers.
+    """
+    if not content:
+        return [f"```{language}", "```"]
+
+    # Neutralize closing tags if present inside snippet so HTML details/summary container isn't closed
+    safe_content = (
+        content.replace("</details>", "<\\/details>")
+        .replace("</summary>", "<\\/summary>")
+        .replace("<details>", "<\\details>")
+        .replace("<summary>", "<\\summary>")
+    )
+
+    # Calculate max consecutive backticks in content
+    max_backticks = 3
+    current_run = 0
+    for ch in safe_content:
+        if ch == "`":
+            current_run += 1
+            if current_run >= max_backticks:
+                max_backticks = current_run + 1
+        else:
+            current_run = 0
+
+    fence = "`" * max_backticks
+    return [f"{fence}{language}", safe_content, fence]
+
 
 def escape_github_property(value: str) -> str:
     """
@@ -203,6 +303,7 @@ def format_markdown_compatibility_card(report: RunReport, script_path: str = "")
     """
     Format an elegant GitHub-flavored Markdown Compatibility Card.
     Suitable for Step Summary and easily copyable into PR / Issue comments.
+    Applies context-sensitive escaping for Markdown/HTML output contexts.
     """
     passed_count = sum(1 for r in report.results if r.status == DistroStatus.PASS)
     total_count = len(report.results)
@@ -217,7 +318,8 @@ def format_markdown_compatibility_card(report: RunReport, script_path: str = "")
         "",
     ]
     if script_path:
-        lines.append(f"**Target Script**: `{script_path}`  ")
+        safe_script_path = escape_inline_code(script_path)
+        lines.append(f"**Target Script**: `{safe_script_path}`  ")
     lines.append(f"**Status**: {badge}  ")
     lines.append(f"**Total Duration**: `{report.total_duration:.2f}s`")
     lines.append("")
@@ -236,24 +338,28 @@ def format_markdown_compatibility_card(report: RunReport, script_path: str = "")
         else:
             status_icon = "⚠️ ERROR"
 
+        distro_cell = escape_markdown_table_cell(f"`{escape_inline_code(r.distro)}`")
         exit_code_str = f"`{r.exit_code}`" if r.exit_code is not None else "`N/A`"
         duration_str = f"`{r.duration:.2f}s`"
 
-        diag_cell = "OK"
-        if r.diagnostic:
+        if r.status == DistroStatus.PASS:
+            raw_diag = "OK"
+        elif r.diagnostic:
             line_str = f" (line {r.diagnostic.line})" if r.diagnostic.line else ""
-            clean_cmd = f"`{r.diagnostic.command}`" if r.diagnostic.command else "command"
-            diag_cell = f"⚠️ Missing command: {clean_cmd}{line_str}"
+            clean_cmd = f"`{escape_inline_code(r.diagnostic.command)}`" if r.diagnostic.command else "command"
+            raw_diag = f"⚠️ Missing command: {clean_cmd}{line_str}"
             if r.diagnostic.hint:
-                diag_cell += f"<br>💡 *{r.diagnostic.hint}*"
+                raw_diag += f"<br>💡 *{r.diagnostic.hint}*"
         elif r.error_message:
-            diag_cell = r.error_message
+            raw_diag = r.error_message
         elif r.status != DistroStatus.PASS:
-            diag_cell = f"Non-zero exit code: {r.exit_code}"
+            raw_diag = f"Non-zero exit code: {r.exit_code}"
+        else:
+            raw_diag = "-"
 
-        diag_cell_escaped = diag_cell.replace("|", "\\|")
+        diag_cell = escape_markdown_table_cell(raw_diag)
         lines.append(
-            f"| `{r.distro}` | {status_icon} | {exit_code_str} | {duration_str} | {diag_cell_escaped} |"
+            f"| {distro_cell} | {status_icon} | {exit_code_str} | {duration_str} | {diag_cell} |"
         )
 
     lines.append("")
@@ -262,23 +368,33 @@ def format_markdown_compatibility_card(report: RunReport, script_path: str = "")
     lines.append("<details>")
     lines.append("<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>")
     lines.append("")
-    lines.append("```markdown")
-    lines.append(f"### 🛡️ OpsScript Gate: {passed_count}/{total_count} Passed (`{script_path or 'target'}`)")
-    lines.append("| Distribution | Status | Time | Details |")
-    lines.append("| :--- | :---: | :---: | :--- |")
+    safe_copy_target = escape_inline_code(script_path or "target")
+    copy_lines = [
+        f"### 🛡️ OpsScript Gate: {passed_count}/{total_count} Passed (`{safe_copy_target}`)",
+        "| Distribution | Status | Time | Details |",
+        "| :--- | :---: | :---: | :--- |",
+    ]
     for r in report.results:
         icon = "✅" if r.status == DistroStatus.PASS else "❌"
-        detail = "OK"
-        if r.diagnostic:
-            detail = f"Missing `{r.diagnostic.command}`"
+        distro_cell = escape_markdown_table_cell(f"`{escape_inline_code(r.distro)}`")
+        if r.status == DistroStatus.PASS:
+            raw_detail = "OK"
+        elif r.diagnostic:
+            safe_cmd = escape_inline_code(r.diagnostic.command or "")
+            raw_detail = f"Missing `{safe_cmd}`"
             if r.diagnostic.line:
-                detail += f" (L{r.diagnostic.line})"
+                raw_detail += f" (L{r.diagnostic.line})"
             if r.diagnostic.hint:
-                detail += f" — *{r.diagnostic.hint}*"
+                raw_detail += f" — *{r.diagnostic.hint}*"
         elif r.error_message:
-            detail = r.error_message
-        lines.append(f"| `{r.distro}` | {icon} {r.status.value} | `{r.duration:.2f}s` | {detail} |")
-    lines.append("```")
+            raw_detail = r.error_message
+        else:
+            raw_detail = "-"
+        detail_cell = escape_markdown_table_cell(raw_detail)
+        copy_lines.append(f"| {distro_cell} | {icon} {r.status.value} | `{r.duration:.2f}s` | {detail_cell} |")
+
+    copy_content = "\n".join(copy_lines)
+    lines.extend(format_safe_code_fence(copy_content, language="markdown"))
     lines.append("</details>")
     lines.append("")
 
@@ -287,23 +403,26 @@ def format_markdown_compatibility_card(report: RunReport, script_path: str = "")
     if failures:
         lines.append("### 🔍 Failure Diagnostic Logs")
         for r in failures:
-            lines.append(f"<details><summary><b>[{r.status.value}] {r.distro}</b></summary>")
+            safe_status = escape_html_text(r.status.value)
+            safe_distro = escape_html_text(r.distro)
+            lines.append(f"<details><summary><b>[{safe_status}] {safe_distro}</b></summary>")
             lines.append("")
             if r.diagnostic:
-                clean_kind = r.diagnostic.kind.replace("`", "'")
-                clean_msg = r.diagnostic.message.replace("`", "'")
+                clean_kind = escape_inline_code(r.diagnostic.kind)
+                clean_msg = escape_inline_code(r.diagnostic.message)
                 line_info = f" (line {r.diagnostic.line})" if r.diagnostic.line else ""
                 lines.append(f"> **Diagnostic:** `{clean_kind}` — `{clean_msg}`{line_info}")
                 if r.diagnostic.hint:
-                    lines.append(f"> 💡 **Recommendation:** {r.diagnostic.hint}")
+                    safe_hint = escape_markdown_text(r.diagnostic.hint)
+                    lines.append(f"> 💡 **Recommendation:** {safe_hint}")
                 lines.append("")
             if r.error_message:
-                lines.append(f"> **Error:** {r.error_message}")
+                safe_err = escape_markdown_text(r.error_message)
+                lines.append(f"> **Error:** {safe_err}")
                 lines.append("")
             if r.output_snippet:
-                lines.append("```text")
-                lines.append(r.output_snippet)
-                lines.append("```")
+                fence_lines = format_safe_code_fence(r.output_snippet, language="text")
+                lines.extend(fence_lines)
             else:
                 lines.append("*No output captured.*")
             lines.append("</details>")