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

{opsscript_gate-0.4.0 → opsscript_gate-0.5.0}/.github/workflows/test.yml

@@ -8,7 +8,11 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.12']
+    runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout Code
         uses: actions/checkout@v7
@@ -16,7 +20,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: '3.12'
+          python-version: ${{ matrix.python }}
 
       - name: Install Dependencies
         run: |
@@ -50,3 +54,12 @@ jobs:
       - name: Run Docker Integration Tests
         run: |
           pytest -v -m integration
+
+      - name: Exercise the local composite Action
+        uses: ./
+        with:
+          script-path: tests/fixtures/pass_basic.sh
+          preset: minimal
+          network: none
+          output: action-report.json
+          format: json

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

@@ -1,10 +1,47 @@
 # Changelog
 
+## [0.5.0] - 2026-09-24
+
+### Added
+- `init`: non-overwriting project configuration and GitHub workflow generation.
+- Shared, strictly validated `.opsscript-gate.json` settings; explicit CLI/Action inputs win.
+- Docker-free `--dry-run` plans in text or JSON, including execution counts.
+- `minimal` and `ubuntu` distribution presets, repeatable exclusion globs and configurable discovery limit.
+- `--output` report artifacts, including failure reports; source/config overwrite protection.
+- Action inputs for configuration, presets, exclusions, preview and saved reports.
+- Chinese quickstart, configuration guide and Ubuntu/Alpine troubleshooting guide.
+
+### Fixed
+- Discovery now fails on overflow instead of silently testing only the first 20 scripts.
+- Discovery skips symlinks and non-files and rejects shebang prefix collisions.
+- CLI rejects non-positive limits and unsupported network modes before execution.
+- Default Action inputs no longer override a user's project configuration.
+
+### Migration
+- Repositories with more than 20 discovered scripts must exclude unwanted scripts or raise `max_scripts`.
+- Auto-discovery no longer follows file symlinks; explicit script paths remain supported.
+- Default settings without a configuration file remain compatible with v0.4.1 and earlier.
+- Generated workflows use the v0.5.0 release tag.
+
 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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -26,7 +26,9 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-# OpsScript Gate
+# OpsScript Gate — shell script compatibility testing
+
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
 > **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
 
@@ -41,8 +43,32 @@ Description-Content-Type: text/markdown
 
 **OpsScript Gate** is a drop-in runtime compatibility gate for Linux shell scripts. It executes your scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
 
+It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
+
 ---
 
+## New in v0.5.0
+
+Preview exactly what will run, keep local and CI settings together, and exclude test
+fixtures before executing scripts. These controls are included in v0.5.0. Projects on
+v0.4.1 and earlier do not include them.
+
+```bash
+opsscript-gate init
+opsscript-gate run --dry-run
+opsscript-gate run --format json --output reports/compatibility.json
+```
+
+`init` creates `.opsscript-gate.json` and a GitHub Actions workflow without replacing
+existing files. Review its exclusions (`tests/*`, `examples/*`) and offline network
+default before running. No Docker is required for `init` or `--dry-run`.
+
+Useful for standalone installers, container entrypoints and release scripts that
+must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently;
+repository files, sibling scripts and project dependencies are **not** mounted.
+See [configuration and migration](docs/configuration.md) and
+[why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
+
 ## ⚡ 30-Second Quickstart
 
 ### In GitHub Actions (Zero Config)
@@ -58,15 +84,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.5.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
 
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.5.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -88,6 +114,35 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
+### Try a Real Failure in 30 Seconds
+
+Create `install.sh`:
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+Then run:
+
+```bash
+opsscript-gate run ./install.sh
+```
+
+A typical result across the default matrix looks like this:
+
+```text
+Debian 12        PASS
+Ubuntu 22.04     PASS
+Ubuntu 24.04     PASS
+Alpine 3.20      FAIL
+
+apt-get: not found
+```
+
+The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+
 ---
 
 ## 🎯 Reviewer-First Experience: What It Produces
@@ -190,7 +245,10 @@ sh: line 4: apt-get: not found
 
 ## 🔒 Security Boundaries & Hardened Isolation
 
-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 is a runtime compatibility testing tool, **not a security sandbox for hostile or fully untrusted code**. Containers still share the host kernel, so target scripts should be treated accordingly.
+
+<details>
+<summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
 OpsScript Gate applies conservative, restricted container defaults when running scripts:
 
@@ -208,14 +266,37 @@ OpsScript Gate applies conservative, restricted container defaults when running
 4. **Anti-Hang Deadlock Defense**:
    - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
    - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
-   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail instead of hanging CI runners.
 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 a rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and a 500-line tail limit (`MAX_LOG_TAIL_LINES`) to reduce memory-exhaustion risk from runaway output.
+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 protect Step Summary output contexts.
+8. **Command Injection Defense**:
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for workflow-command fields and message bodies.
+9. **Bounded Streaming CRLF & Shebang Defense**:
+   - Stream-normalizes CRLF in 64 KiB chunks 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.
+
+For the complete supported-version policy and vulnerability reporting guidance, see [SECURITY.md](SECURITY.md).
+
+</details>
+
+### When NOT to use OpsScript Gate
+
+OpsScript Gate is intentionally focused on Linux shell runtime compatibility. It is not designed for:
+
+- executing hostile or fully untrusted third-party scripts
+- kernel-level or privileged behavior testing
+- replacing full integration or end-to-end test suites
+- validating macOS or Windows behavior
+- proving that a script is secure
+
+Use it when you want to know whether a shell script actually runs across the supported Linux distributions.
 
 ---
 
@@ -269,7 +350,23 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 
 ---
 
-## 🐶 Dogfooding
+### v0.5.0 project controls
+
+| Option | Purpose |
+| :--- | :--- |
+| `init` | Generate configuration and a GitHub workflow without overwriting files |
+| `--dry-run` | Preview selected scripts, images and total executions without Docker |
+| `--config PATH` | Load a specific JSON configuration file |
+| `--preset minimal` | Debian + Alpine (two container runs per script) |
+| `--preset ubuntu` | Ubuntu 22.04 + 24.04 |
+| `--exclude 'tests/*'` | Exclude a repository-relative glob; repeatable |
+| `--max-scripts 50` | Raise the default discovery limit of 20; overflow is an error |
+| `--output report.json` | Save the selected output format, including failed test reports |
+
+Explicit CLI options override project settings. Explicit script paths bypass discovery
+and its exclusions. See [complete configuration semantics](docs/configuration.md).
+
+## 🌍 Real-World Usage
 
 OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
 
@@ -296,6 +393,14 @@ pytest -v
 
 ---
 
+## 💛 If OpsScript Gate Helps
+
+If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+
+Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+
+---
+
 ## 📄 License
 
 OpsScript Gate is licensed under the [MIT License](LICENSE).

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

@@ -1,4 +1,6 @@
-# OpsScript Gate
+# OpsScript Gate — shell script compatibility testing
+
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
 > **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
 
@@ -13,8 +15,32 @@
 
 **OpsScript Gate** is a drop-in runtime compatibility gate for Linux shell scripts. It executes your scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
 
+It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
+
 ---
 
+## New in v0.5.0
+
+Preview exactly what will run, keep local and CI settings together, and exclude test
+fixtures before executing scripts. These controls are included in v0.5.0. Projects on
+v0.4.1 and earlier do not include them.
+
+```bash
+opsscript-gate init
+opsscript-gate run --dry-run
+opsscript-gate run --format json --output reports/compatibility.json
+```
+
+`init` creates `.opsscript-gate.json` and a GitHub Actions workflow without replacing
+existing files. Review its exclusions (`tests/*`, `examples/*`) and offline network
+default before running. No Docker is required for `init` or `--dry-run`.
+
+Useful for standalone installers, container entrypoints and release scripts that
+must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently;
+repository files, sibling scripts and project dependencies are **not** mounted.
+See [configuration and migration](docs/configuration.md) and
+[why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
+
 ## ⚡ 30-Second Quickstart
 
 ### In GitHub Actions (Zero Config)
@@ -30,15 +56,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.5.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
 
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.0
+      - uses: Mresyzz/opsscript-gate@v0.5.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -60,6 +86,35 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
+### Try a Real Failure in 30 Seconds
+
+Create `install.sh`:
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+Then run:
+
+```bash
+opsscript-gate run ./install.sh
+```
+
+A typical result across the default matrix looks like this:
+
+```text
+Debian 12        PASS
+Ubuntu 22.04     PASS
+Ubuntu 24.04     PASS
+Alpine 3.20      FAIL
+
+apt-get: not found
+```
+
+The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+
 ---
 
 ## 🎯 Reviewer-First Experience: What It Produces
@@ -162,7 +217,10 @@ sh: line 4: apt-get: not found
 
 ## 🔒 Security Boundaries & Hardened Isolation
 
-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 is a runtime compatibility testing tool, **not a security sandbox for hostile or fully untrusted code**. Containers still share the host kernel, so target scripts should be treated accordingly.
+
+<details>
+<summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
 OpsScript Gate applies conservative, restricted container defaults when running scripts:
 
@@ -180,14 +238,37 @@ OpsScript Gate applies conservative, restricted container defaults when running
 4. **Anti-Hang Deadlock Defense**:
    - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
    - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
-   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail instead of hanging CI runners.
 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 a rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and a 500-line tail limit (`MAX_LOG_TAIL_LINES`) to reduce memory-exhaustion risk from runaway output.
+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 protect Step Summary output contexts.
+8. **Command Injection Defense**:
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for workflow-command fields and message bodies.
+9. **Bounded Streaming CRLF & Shebang Defense**:
+   - Stream-normalizes CRLF in 64 KiB chunks 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.
+
+For the complete supported-version policy and vulnerability reporting guidance, see [SECURITY.md](SECURITY.md).
+
+</details>
+
+### When NOT to use OpsScript Gate
+
+OpsScript Gate is intentionally focused on Linux shell runtime compatibility. It is not designed for:
+
+- executing hostile or fully untrusted third-party scripts
+- kernel-level or privileged behavior testing
+- replacing full integration or end-to-end test suites
+- validating macOS or Windows behavior
+- proving that a script is secure
+
+Use it when you want to know whether a shell script actually runs across the supported Linux distributions.
 
 ---
 
@@ -241,7 +322,23 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 
 ---
 
-## 🐶 Dogfooding
+### v0.5.0 project controls
+
+| Option | Purpose |
+| :--- | :--- |
+| `init` | Generate configuration and a GitHub workflow without overwriting files |
+| `--dry-run` | Preview selected scripts, images and total executions without Docker |
+| `--config PATH` | Load a specific JSON configuration file |
+| `--preset minimal` | Debian + Alpine (two container runs per script) |
+| `--preset ubuntu` | Ubuntu 22.04 + 24.04 |
+| `--exclude 'tests/*'` | Exclude a repository-relative glob; repeatable |
+| `--max-scripts 50` | Raise the default discovery limit of 20; overflow is an error |
+| `--output report.json` | Save the selected output format, including failed test reports |
+
+Explicit CLI options override project settings. Explicit script paths bypass discovery
+and its exclusions. See [complete configuration semantics](docs/configuration.md).
+
+## 🌍 Real-World Usage
 
 OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
 
@@ -268,6 +365,14 @@ pytest -v
 
 ---
 
+## 💛 If OpsScript Gate Helps
+
+If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+
+Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+
+---
+
 ## 📄 License
 
 OpsScript Gate is licensed under the [MIT License](LICENSE).

opsscript_gate-0.5.0/README.zh-CN.md

@@ -0,0 +1,67 @@
+# OpsScript Gate：Shell 脚本跨发行版运行检查
+
+[English](README.md) · [配置说明](docs/configuration.md) · [常见问题](docs/troubleshooting.md)
+
+在 Debian、Ubuntu、Alpine 容器里实际运行 Shell 脚本，提前发现缺失命令、
+Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
+
+适合独立安装脚本、容器入口脚本和发布脚本。每次只挂载目标脚本，
+不挂载整个仓库；依赖其他仓库文件的脚本需要现有项目测试配合。
+
+## 试用本次 v0.5.0 更新
+
+v0.5.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+
+```bash
+pip install -e .
+opsscript-gate run examples/basic/clean_setup.sh --dry-run
+```
+
+在你希望接入检查的仓库根目录执行：
+
+```bash
+opsscript-gate init
+opsscript-gate run --dry-run
+opsscript-gate run --format json --output reports/compatibility.json
+```
+
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.5.0`。
+预览不需要 Docker；真实运行需要 Python 3.10+
+和可访问的 Linux Docker 引擎。
+
+生成的配置默认排除 `tests/*`、`examples/*`，使用 Debian + Alpine，尊重
+脚本 shebang，并关闭网络。请根据实际脚本审核配置；需要下载文件时启用
+`--network bridge`。保留现有无配置行为：四个发行版、POSIX shell、bridge 网络。
+
+## 本轮改进
+
+- 运行前展示脚本、镜像和总容器执行次数。
+- 本地与 GitHub Actions 共用 `.opsscript-gate.json`。
+- 排除规则、发行版预设、扫描数量限制。
+- 超过扫描上限明确报错，避免只测前 20 个却误以为全部通过。
+- 报告保存为 JSON、Markdown 或文本，失败时同样保留结果。
+- 自动发现跳过符号链接，并严格校验配置与执行参数。
+
+返回码 `0` 表示全部通过，`1` 表示检查失败或发生错误。`--dry-run` 成功只表示
+执行计划生成成功。容器不是不可信代码的安全沙箱。
+
+## 示例：为什么 Alpine 上会失败
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+这个脚本可以符合 POSIX 语法，但 Alpine 使用 `apk`，实际执行会暴露命令缺失。
+查看 [Ubuntu／Alpine 排错说明](docs/troubleshooting.md) 获取常见原因与修复方向。
+
+## 测试
+
+```bash
+pip install -e '.[test]'
+pytest -q -m 'not integration'
+pytest -q -m integration
+```
+
+第二组需要 Docker。跳过容器测试不能算作完整集成验证。

{opsscript_gate-0.4.0 → opsscript_gate-0.5.0}/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.