opsscript-gate 0.6.3__tar.gz → 0.8.0__tar.gz

opsscript_gate-0.6.3/.github/workflow-templates/properties.json → opsscript_gate-0.8.0/.github/workflow-templates/opsscript-gate.properties.json

@@ -2,5 +2,6 @@
   "name": "OpsScript Gate shell compatibility",
   "description": "Run shell scripts in Debian, Ubuntu and Alpine containers on changes to shell files.",
   "iconName": "octicon-shield-check",
-  "categories": ["Continuous integration", "Testing"]
+  "categories": ["Continuous integration", "Testing"],
+  "filePatterns": [".*\\.sh$", ".*\\.bash$"]
 }

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/.github/workflow-templates/opsscript-gate.yml

@@ -25,7 +25,7 @@ jobs:
           persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.6.3
+        uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           shell: auto
           network: none

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/CHANGELOG.md

@@ -1,9 +1,17 @@
 # Changelog
 
-## [0.6.3] - 2026-10-01
+## [0.8.0] - 2026-10-02
+
+### Added
+- Added opt-in `packages` setup for installing validated package names with
+  `apt-get` or `apk` before each container run; package setup requires bridge
+  networking and leaves existing offline runs unchanged.
+
+## [0.7.0] - 2026-10-01
 
 ### Added
 - Added `opsscript-gate doctor` to diagnose Python and Docker prerequisites before a local run.
+- Added SARIF 2.1.0 output for location-aware GitHub Code Scanning integration.
 
 ### Changed
 - Expanded package and Marketplace keywords for shell installers, ShellCheck users, portability, and BusyBox.

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/CITATION.cff

@@ -5,8 +5,8 @@ type: software
 authors:
   - family-names: Mresyzz
     given-names: Mresy
-version: 0.6.3
-date-released: 2026-10-01
+version: 0.8.0
+date-released: 2026-10-02
 repository-code: https://github.com/Mresyzz/opsscript-gate
 url: https://github.com/Mresyzz/opsscript-gate
 license: MIT

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.6.3
+Version: 0.8.0
 Summary: Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge
 Project-URL: Homepage, https://mresyzz.github.io/InstallReady/
 Project-URL: Demo, https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate
@@ -48,15 +48,15 @@ Description-Content-Type: text/markdown
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 If your repository contains an installer, bootstrap script, or shell entrypoint, the fastest path is to
-copy the [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml). It only runs when
-shell files change, uses offline containers by default, and uploads a report that can be attached to a PR.
-No account, API key, or service signup is required.
+open the [InstallReady scanner](https://mresyzz.github.io/InstallReady/), enter `owner/repository`, and
+choose **Add workflow on GitHub**. It generates a reviewable workflow without an account, API key, or
+service signup. You can also copy the maintained [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml).
 
 Try the browser scanner: [InstallReady](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate) checks this repository without executing code or requiring a login.
 
 ---
 
-## Current release: v0.6.3
+## Current release: v0.8.0
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, and changed-script selection for pull requests. The project controls
@@ -77,7 +77,10 @@ Use `opsscript-gate doctor` to check Python and Docker before a real 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
+If an installer needs a small, explicit set of tools such as `curl`, pass
+`packages` in the config or Action input; the runner installs them with the
+image's native package manager before testing. Package setup is opt-in and
+requires bridge networking. See [configuration and migration](docs/configuration.md) and
 [why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
 
 ## Quickstart
@@ -86,8 +89,9 @@ See [configuration and migration](docs/configuration.md) and
 
 Add this workflow to `.github/workflows/shell-compat.yml`:
 
-You can also select **OpsScript Gate shell compatibility** from GitHub's workflow templates, or copy the
-maintained [starter workflow](.github/workflow-templates/opsscript-gate.yml).
+The repository includes a maintained [workflow template](.github/workflow-templates/opsscript-gate.yml).
+For a one-click setup in another public repository, use the InstallReady scanner above; it opens GitHub's
+workflow editor with the generated file ready to review.
 
 You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
 and change the `script-path`, or use the minimal workflow below.
@@ -101,7 +105,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+        with:
+          persist-credentials: false
+      - uses: Mresyzz/opsscript-gate@v0.8.0
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -112,7 +118,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -142,8 +148,9 @@ unrelated scripts:
 ```yaml
       - uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -220,6 +227,28 @@ The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 </details>
 ```
 
+### SARIF for Code Scanning
+
+Use `sarif` when the result should appear in GitHub Code Scanning or another
+SARIF-compatible viewer. Upload it explicitly with the official upload action:
+
+```yaml
+- uses: Mresyzz/opsscript-gate@v0.8.0
+  with:
+    script-path: scripts/install.sh
+    format: sarif
+    output: reports/opsscript-gate.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: reports/opsscript-gate.sarif
+```
+
+Each runtime failure becomes a location-aware result with the distribution,
+exit code, command, and diagnostic line. A passing matrix produces a valid SARIF
+file with no findings.
+
 ---
 
 ## Example: runtime behavior that static analysis misses
@@ -376,7 +405,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
 | `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images |
 | `--timeout` | Integer | `60` | Hard timeout per container in seconds |
-| `--format` | Choice | `table` | Output format: `table`, `markdown`, or `json` |
+| `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
@@ -413,14 +442,6 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## Downstream example
-
-[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
-
-See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
-
----
-
 ## 🧪 Development & Testing
 
 ```bash

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/README.md

@@ -18,15 +18,15 @@
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 If your repository contains an installer, bootstrap script, or shell entrypoint, the fastest path is to
-copy the [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml). It only runs when
-shell files change, uses offline containers by default, and uploads a report that can be attached to a PR.
-No account, API key, or service signup is required.
+open the [InstallReady scanner](https://mresyzz.github.io/InstallReady/), enter `owner/repository`, and
+choose **Add workflow on GitHub**. It generates a reviewable workflow without an account, API key, or
+service signup. You can also copy the maintained [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml).
 
 Try the browser scanner: [InstallReady](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate) checks this repository without executing code or requiring a login.
 
 ---
 
-## Current release: v0.6.3
+## Current release: v0.8.0
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, and changed-script selection for pull requests. The project controls
@@ -47,7 +47,10 @@ Use `opsscript-gate doctor` to check Python and Docker before a real 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
+If an installer needs a small, explicit set of tools such as `curl`, pass
+`packages` in the config or Action input; the runner installs them with the
+image's native package manager before testing. Package setup is opt-in and
+requires bridge networking. See [configuration and migration](docs/configuration.md) and
 [why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
 
 ## Quickstart
@@ -56,8 +59,9 @@ See [configuration and migration](docs/configuration.md) and
 
 Add this workflow to `.github/workflows/shell-compat.yml`:
 
-You can also select **OpsScript Gate shell compatibility** from GitHub's workflow templates, or copy the
-maintained [starter workflow](.github/workflow-templates/opsscript-gate.yml).
+The repository includes a maintained [workflow template](.github/workflow-templates/opsscript-gate.yml).
+For a one-click setup in another public repository, use the InstallReady scanner above; it opens GitHub's
+workflow editor with the generated file ready to review.
 
 You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
 and change the `script-path`, or use the minimal workflow below.
@@ -71,7 +75,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+        with:
+          persist-credentials: false
+      - uses: Mresyzz/opsscript-gate@v0.8.0
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -82,7 +88,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -112,8 +118,9 @@ unrelated scripts:
 ```yaml
       - uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -190,6 +197,28 @@ The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 </details>
 ```
 
+### SARIF for Code Scanning
+
+Use `sarif` when the result should appear in GitHub Code Scanning or another
+SARIF-compatible viewer. Upload it explicitly with the official upload action:
+
+```yaml
+- uses: Mresyzz/opsscript-gate@v0.8.0
+  with:
+    script-path: scripts/install.sh
+    format: sarif
+    output: reports/opsscript-gate.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: reports/opsscript-gate.sarif
+```
+
+Each runtime failure becomes a location-aware result with the distribution,
+exit code, command, and diagnostic line. A passing matrix produces a valid SARIF
+file with no findings.
+
 ---
 
 ## Example: runtime behavior that static analysis misses
@@ -346,7 +375,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
 | `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images |
 | `--timeout` | Integer | `60` | Hard timeout per container in seconds |
-| `--format` | Choice | `table` | Output format: `table`, `markdown`, or `json` |
+| `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
@@ -383,14 +412,6 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## Downstream example
-
-[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
-
-See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
-
----
-
 ## 🧪 Development & Testing
 
 ```bash

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/README.zh-CN.md

@@ -10,9 +10,9 @@ Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
 
 也可以直接打开 [InstallReady 在线扫描器](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate)，无需登录即可检查公开仓库。
 
-## 当前版本 v0.6.3
+## 当前版本 v0.8.0
 
-v0.6.3 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+v0.8.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
 
 ```bash
 pip install -e .
@@ -28,14 +28,21 @@ opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
 
-`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.6.3`。
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.8.0`。
 预览不需要 Docker；真实运行需要 Python 3.10+
 和可访问的 Linux Docker 引擎。
 `opsscript-gate doctor` 可以在真实运行前检查 Python 和 Docker。
 
+需要接入 GitHub Code Scanning 时，将 `--format sarif --output reports/opsscript-gate.sarif`
+传给运行命令，再用 `github/codeql-action/upload-sarif@v3` 上传报告。每个失败发行版
+都会保留脚本路径、诊断行号、命令和退出码；全部通过时仍会生成合法的空 SARIF 报告。
+
 生成的配置默认排除 `tests/*`、`examples/*`，使用 Debian + Alpine，尊重
 脚本 shebang，并关闭网络。请根据实际脚本审核配置；需要下载文件时启用
-`--network bridge`。保留现有无配置行为：四个发行版、POSIX shell、bridge 网络。
+`--network bridge`。安装器如果需要 `curl`、证书或其他明确工具，可以配置
+`packages`；运行器会用镜像自带的 `apt-get` 或 `apk` 安装它们。包安装是可选的，
+只接受包名，不接受 Shell 命令，并且必须使用 `bridge` 网络。保留现有无配置行为：
+四个发行版、POSIX shell、bridge 网络。
 
 ## 本轮改进
 
@@ -58,7 +65,7 @@ Docker daemon 和可选的项目配置。
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: Mresyzz/opsscript-gate@v0.6.3
+- uses: Mresyzz/opsscript-gate@v0.8.0
   with:
     changed-since: ${{ github.event.pull_request.base.sha }}
     preset: minimal

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/SECURITY.md

@@ -6,8 +6,8 @@ Only the latest release of **OpsScript Gate** receives security updates and bug
 
 | Version | Supported          |
 | :---    | :---:              |
-| 0.4.x   | :white_check_mark: |
-| < 0.4.0 | :x:                |
+| 0.8.x   | :white_check_mark: |
+| < 0.8.0 | :x:                |
 
 ---
 

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/action.yml

@@ -23,7 +23,7 @@ inputs:
     required: false
     default: ''
   format:
-    description: 'Output report format: table, markdown, or json'
+    description: 'Output report format: table, markdown, json, or sarif'
     required: false
     default: ''
   shell:
@@ -42,6 +42,10 @@ inputs:
     description: "Container network mode: 'bridge' or 'none' (default: bridge)"
     required: false
     default: ''
+  packages:
+    description: 'Optional comma- or newline-separated packages to install before running (requires network=bridge)'
+    required: false
+    default: ''
 
   config:
     description: 'Path to project JSON configuration'
@@ -97,6 +101,7 @@ runs:
         INPUT_MEM_LIMIT: ${{ inputs.mem-limit }}
         INPUT_PIDS_LIMIT: ${{ inputs.pids-limit }}
         INPUT_NETWORK: ${{ inputs.network }}
+        INPUT_PACKAGES: ${{ inputs.packages }}
         INPUT_CONFIG: ${{ inputs.config }}
         INPUT_PRESET: ${{ inputs.preset }}
         INPUT_EXCLUDE: ${{ inputs.exclude }}
@@ -116,6 +121,7 @@ runs:
         [ -z "$INPUT_MEM_LIMIT" ] || ARGS+=(--mem-limit "$INPUT_MEM_LIMIT")
         [ -z "$INPUT_PIDS_LIMIT" ] || ARGS+=(--pids-limit "$INPUT_PIDS_LIMIT")
         [ -z "$INPUT_NETWORK" ] || ARGS+=(--network "$INPUT_NETWORK")
+        [ -z "$INPUT_PACKAGES" ] || ARGS+=(--packages "$INPUT_PACKAGES")
         [ -z "$INPUT_MATRIX" ] || ARGS+=(--matrix "$INPUT_MATRIX")
         [ -z "$INPUT_JOBS" ] || ARGS+=(--jobs "$INPUT_JOBS")
         [ -z "$INPUT_CONFIG" ] || ARGS+=(--config "$INPUT_CONFIG")

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/docs/configuration.md

@@ -12,7 +12,7 @@ opsscript-gate run --dry-run
 ```
 
 `init` refuses to overwrite either `.opsscript-gate.json` or
-`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.6.3 tag.
+`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.8.0 tag.
 
 `doctor` checks Python and Docker connectivity without executing repository scripts.
 Use `opsscript-gate doctor --format json` when collecting a support report.
@@ -34,6 +34,7 @@ directory, not the config file's parent.
   "preset": "minimal",
   "shell": "auto",
   "network": "none",
+  "packages": [],
   "timeout": 30,
   "jobs": 2,
   "mem_limit": "256m",
@@ -46,7 +47,11 @@ directory, not the config file's parent.
 These are all supported keys, plus `matrix`, a comma-separated image string used
 instead of `preset`. Unknown keys and incorrect value types are errors. Numeric
 limits must be positive integers. `shell` accepts `posix`, `auto`, `shebang`;
-`network` accepts `none`, `bridge`.
+`network` accepts `none`, `bridge`. `packages` is an optional list of package
+names to install inside each test container before the target script runs. The
+runner uses `apt-get` for Debian/Ubuntu images and `apk` for Alpine images. It
+accepts package names only, never shell commands, and requires `network: bridge`.
+The default is an empty list, so existing networking settings and execution remain unchanged.
 
 | Preset | Images |
 | --- | --- |
@@ -99,7 +104,7 @@ For pull requests, set `changed-since` to the base commit and fetch full Git his
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: Mresyzz/opsscript-gate@v0.6.3
+- uses: Mresyzz/opsscript-gate@v0.8.0
   with:
     changed-since: ${{ github.event.pull_request.base.sha }}
     preset: minimal
@@ -109,11 +114,15 @@ The Action passes when no changed shell scripts are selected. This keeps unrelat
 documentation or application changes from starting container jobs.
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.6.3
+- uses: Mresyzz/opsscript-gate@v0.8.0
   with:
     config: .opsscript-gate.json
     format: json
     output: reports/compatibility.json
+    network: bridge
+    packages: |
+      curl
+      ca-certificates
     exclude: |
       tests/*
       examples/*

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/docs/gpt-oss.md

@@ -33,7 +33,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/examples/github-actions/README.md

@@ -2,4 +2,4 @@
 
 This example shows a GitHub Actions workflow for checking a shell script on pull requests.
 
-Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate. The example uses the current v0.6.3 Action release.
+Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate. The example uses the current v0.8.0 Action release.

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/examples/github-actions/workflow.yml

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.6.3
+        uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           script-path: 'scripts/deploy.sh'
           shell: auto

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/pyproject.toml

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

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/src/opsscript_gate/__init__.py

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

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/src/opsscript_gate/cli.py

@@ -9,14 +9,16 @@ from pathlib import Path
 
 from opsscript_gate import __version__
 from opsscript_gate.discovery import discover_changed_scripts, discover_scripts
-from opsscript_gate.config import DEFAULTS, PRESETS, init_project, load_config
+from opsscript_gate.config import DEFAULTS, PRESETS, init_project, load_config, validate_packages
 from opsscript_gate.models import MultiScriptReport, RunReport
 from opsscript_gate.reporter import (
     emit_github_annotations,
     format_github_summary,
     format_json,
+    format_multi_sarif,
     format_multi_github_summary,
     format_multi_terminal_table,
+    format_sarif,
     format_terminal_table,
     write_github_step_summary,
 )
@@ -91,9 +93,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     run_parser.add_argument(
         "--format",
-        choices=["table", "markdown", "json"],
+        choices=["table", "markdown", "json", "sarif"],
         default="table",
-        help="Output report format: 'table' (default ASCII), 'markdown', or 'json'",
+        help="Output report format: 'table' (default ASCII), 'markdown', 'json', or 'sarif'",
     )
     run_parser.add_argument(
         "--shell",
@@ -119,6 +121,12 @@ def build_parser() -> argparse.ArgumentParser:
         default="bridge",
         help="Network mode for containers: 'bridge' or 'none' (default: bridge)",
     )
+    run_parser.add_argument(
+        "--packages",
+        action="append",
+        default=None,
+        help="Optional comma-separated packages to install in each container before running (repeatable; requires network=bridge)",
+    )
     run_parser.add_argument(
         "--changed-since",
         help="Only test shell scripts changed between this Git revision and HEAD",
@@ -141,6 +149,19 @@ def parse_matrix_argument(matrix_raw: str | None) -> list[str]:
     return images if images else DEFAULT_MATRIX
 
 
+def parse_packages_argument(packages_raw: list[str] | None) -> list[str]:
+    """Parse repeated comma/newline-separated package arguments."""
+    if not packages_raw:
+        return []
+    packages: list[str] = []
+    for raw in packages_raw:
+        for package in raw.replace("\r", "\n").replace(",", "\n").split("\n"):
+            name = package.strip()
+            if name:
+                packages.append(name)
+    return validate_packages(packages)
+
+
 def main(argv: list[str] | None = None) -> int:
     """Main CLI entrypoint."""
     parser = build_parser()
@@ -213,6 +234,9 @@ def main(argv: list[str] | None = None) -> int:
                     raise ValueError(f"{key.replace('_', '-')} must be positive")
             if args.network not in ("bridge", "none"):
                 raise ValueError("network must be bridge or none")
+            args.packages = parse_packages_argument(args.packages)
+            if args.packages and args.network == "none":
+                raise ValueError("packages require network=bridge")
             if args.matrix is not None and not any(x.strip() for x in args.matrix.split(",")):
                 raise ValueError("matrix must contain at least one image")
         except ValueError as err:
@@ -261,13 +285,14 @@ def main(argv: list[str] | None = None) -> int:
         if args.dry_run:
             plan = {"dry_run": True, "scripts": target_scripts, "matrix": matrix,
                     "executions": len(target_scripts) * len(matrix), "shell": args.shell,
-                    "network": args.network, "timeout": args.timeout}
+                    "network": args.network, "packages": args.packages, "timeout": args.timeout}
             if changed_selection:
                 plan["changed_since"] = args.changed_since
             output = json.dumps(plan, indent=2) if args.format == "json" else (
                 "Execution preview (no scripts executed)\n"
                 + "\n".join(f"  {path}" for path in target_scripts)
                 + f"\nImages: {', '.join(matrix)}\nContainer executions: {plan['executions']}"
+                + (f"\nPackages: {', '.join(args.packages)}" if args.packages else "")
                 + f"\nShell: {args.shell} | Network: {args.network} | Timeout: {args.timeout}s"
             )
             return 0 if publish_output(output, args.output) else 1
@@ -290,6 +315,7 @@ def main(argv: list[str] | None = None) -> int:
                     mem_limit=args.mem_limit,
                     pids_limit=args.pids_limit,
                     network=args.network,
+                    packages=args.packages,
                 )
             except DockerDaemonError as err:
                 sys.stderr.write(f"Docker Error: {err}\n")
@@ -301,6 +327,8 @@ def main(argv: list[str] | None = None) -> int:
             # Format report output
             if args.format == "json":
                 output = format_json(report)
+            elif args.format == "sarif":
+                output = format_sarif(report, script_path=script_path)
             elif args.format == "markdown":
                 output = format_github_summary(report, script_path=script_path)
             else:
@@ -332,6 +360,7 @@ def main(argv: list[str] | None = None) -> int:
                     mem_limit=args.mem_limit,
                     pids_limit=args.pids_limit,
                     network=args.network,
+                    packages=args.packages,
                 )
             except DockerDaemonError as err:
                 sys.stderr.write(f"Docker Error: {err}\n")
@@ -353,6 +382,8 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.format == "json":
             output = format_json(multi_report)
+        elif args.format == "sarif":
+            output = format_multi_sarif(multi_report)
         elif args.format == "markdown":
             output = format_multi_github_summary(multi_report)
         else:

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/src/opsscript_gate/config.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 
 CONFIG_NAME = ".opsscript-gate.json"
@@ -12,9 +13,26 @@ PRESETS = {
 DEFAULTS = {
     "matrix": None, "preset": None, "jobs": None, "timeout": 60,
     "shell": "posix", "mem_limit": "256m", "pids_limit": 128,
-    "network": "bridge", "exclude": [], "max_scripts": 20,
+    "network": "bridge", "packages": [], "exclude": [], "max_scripts": 20,
 }
 
+PACKAGE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9+._:-]*$")
+
+
+def validate_packages(value: object) -> list[str]:
+    """Validate and normalize package names used for optional container setup."""
+    if not isinstance(value, list) or not all(isinstance(p, str) for p in value):
+        raise ValueError("packages must be a list of package names")
+    packages: list[str] = []
+    for package in value:
+        name = package.strip()
+        if not name or not PACKAGE_NAME_RE.fullmatch(name):
+            raise ValueError(
+                "packages must contain nonempty package names using only letters, numbers, '+', '.', '_', ':', or '-'")
+        if name not in packages:
+            packages.append(name)
+    return packages
+
 
 def load_config(filename: str | None) -> dict:
     path = Path(filename or CONFIG_NAME)
@@ -36,6 +54,8 @@ def load_config(filename: str | None) -> dict:
         elif key == "exclude":
             if not isinstance(value, list) or not all(isinstance(p, str) and p for p in value):
                 raise ValueError("exclude must be a list of nonempty glob strings")
+        elif key == "packages":
+            validate_packages(value)
         elif not isinstance(value, str) or not value.strip():
             raise ValueError(f"{key} must be a nonempty string")
     for key, choices in {"shell": ("posix", "auto", "shebang"),
@@ -63,7 +83,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.6.3
+      - uses: Mresyzz/opsscript-gate@v0.8.0
         with:
           config: .opsscript-gate.json
 """,

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/src/opsscript_gate/reporter.py

@@ -3,6 +3,7 @@ import json
 import os
 import re
 import sys
+from opsscript_gate import __version__
 from opsscript_gate.models import DistroStatus, MultiScriptReport, RunReport, SingleResult
 
 # Structure-altering Markdown characters in regular prose:
@@ -463,6 +464,125 @@ def format_json(report: RunReport | MultiScriptReport) -> str:
     return json.dumps(report.to_dict(), indent=2, ensure_ascii=False)
 
 
+_SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+_SARIF_RULES = {
+    DistroStatus.FAIL: ("OSG001", "Runtime compatibility failure"),
+    DistroStatus.TIMED_OUT: ("OSG002", "Runtime compatibility check timed out"),
+    DistroStatus.ERROR: ("OSG003", "Runtime compatibility check error"),
+}
+
+
+def _sarif_path(script_path: str) -> str:
+    """Return a repository-relative SARIF artifact path."""
+    clean = (script_path or "script.sh").replace("\\", "/")
+    while clean.startswith("./"):
+        clean = clean[2:]
+    return clean or "script.sh"
+
+
+def _sarif_message(result: SingleResult) -> str:
+    parts = [f"[{result.distro}] {result.status.value}"]
+    if result.diagnostic:
+        parts.append(result.diagnostic.message)
+        if result.diagnostic.hint:
+            parts.append(result.diagnostic.hint)
+    elif result.error_message:
+        parts.append(result.error_message)
+    elif result.exit_code is not None:
+        parts.append(f"Execution exited with code {result.exit_code}.")
+    return " — ".join(parts)
+
+
+def _sarif_result(result: SingleResult, script_path: str) -> dict[str, object] | None:
+    if result.status == DistroStatus.PASS:
+        return None
+
+    rule_id, rule_name = _SARIF_RULES[result.status]
+    physical_location: dict[str, object] = {
+        "artifactLocation": {
+            "uri": _sarif_path(script_path),
+        },
+    }
+    if result.diagnostic and result.diagnostic.line and result.diagnostic.line > 0:
+        physical_location["region"] = {"startLine": result.diagnostic.line}
+
+    properties: dict[str, object] = {
+        "distribution": result.distro,
+        "status": result.status.value,
+        "durationSeconds": round(result.duration, 3),
+    }
+    if result.exit_code is not None:
+        properties["exitCode"] = result.exit_code
+    if result.diagnostic and result.diagnostic.command:
+        properties["command"] = result.diagnostic.command
+
+    return {
+        "ruleId": rule_id,
+        "level": "error",
+        "message": {"text": _sarif_message(result)},
+        "locations": [{"physicalLocation": physical_location}],
+        "properties": properties,
+        "help": {
+            "text": rule_name,
+            "uri": "https://github.com/Mresyzz/opsscript-gate#ci-output",
+        },
+    }
+
+
+def _sarif_run(results: list[dict[str, object]]) -> dict[str, object]:
+    return {
+        "tool": {
+            "driver": {
+                "name": "OpsScript Gate",
+                "version": __version__,
+                "informationUri": "https://github.com/Mresyzz/opsscript-gate",
+                "rules": [
+                    {
+                        "id": rule_id,
+                        "name": rule_name,
+                        "shortDescription": {"text": rule_name},
+                        "helpUri": "https://github.com/Mresyzz/opsscript-gate#ci-output",
+                    }
+                    for rule_id, rule_name in _SARIF_RULES.values()
+                ],
+            },
+        },
+        "results": results,
+    }
+
+
+def format_sarif(report: RunReport, script_path: str = "") -> str:
+    """Format runtime failures as SARIF 2.1.0 for GitHub Code Scanning."""
+    results = [
+        item
+        for result in report.results
+        if (item := _sarif_result(result, script_path)) is not None
+    ]
+    payload = {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [_sarif_run(results)],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def format_multi_sarif(report: MultiScriptReport) -> str:
+    """Format multi-script runtime failures as one SARIF 2.1.0 run."""
+    results: list[dict[str, object]] = []
+    for script_path, script_report in report.reports.items():
+        results.extend(
+            item
+            for result in script_report.results
+            if (item := _sarif_result(result, script_path)) is not None
+        )
+    payload = {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [_sarif_run(results)],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
 def write_github_step_summary(
     report_or_content: RunReport | MultiScriptReport | str,
     script_path: str = "",

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/src/opsscript_gate/runner.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import re
+import shlex
 import tempfile
 import time
 from typing import Any, Sequence
@@ -12,6 +13,7 @@ from docker.errors import DockerException, ImageNotFound
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from enum import Enum
+from opsscript_gate.config import PACKAGE_NAME_RE
 from opsscript_gate.models import DistroStatus, FailureDiagnostic, RunReport, ShellMode, SingleResult
 from opsscript_gate.remediation import generate_remediation_hint
 
@@ -574,6 +576,32 @@ def _resolve_shell_command(
     return None, f"Unsupported shell mode: {mode}"
 
 
+def _wrap_with_package_setup(command: Sequence[str], packages: Sequence[str]) -> list[str]:
+    """Preinstall explicit packages with the image's native package manager."""
+    if not packages:
+        return list(command)
+
+    if any(not isinstance(package, str) or not PACKAGE_NAME_RE.fullmatch(package) for package in packages):
+        raise ValueError("Invalid package name")
+
+    package_args = " ".join(shlex.quote(package) for package in packages)
+    install = (
+        "if command -v apt-get >/dev/null 2>&1; then "
+        "mkdir -p /tmp/opsscript-apt-archives/partial && "
+        "apt-get -o APT::Sandbox::User=root "
+        "-o Dir::Cache::archives=/tmp/opsscript-apt-archives/ update && "
+        f"apt-get -o APT::Sandbox::User=root "
+        "-o Dir::Cache::archives=/tmp/opsscript-apt-archives/ "
+        f"install -y --no-install-recommends {package_args} && "
+        "rm -rf /tmp/opsscript-apt-archives /var/lib/apt/lists/*; "
+        "elif command -v apk >/dev/null 2>&1; then "
+        f"apk add --no-cache {package_args}; "
+        "else echo 'No supported package manager found (apt-get or apk)' >&2; exit 125; fi"
+    )
+    target_command = " ".join(shlex.quote(part) for part in command)
+    return ["/bin/sh", "-c", f"{install} && exec {target_command}"]
+
+
 def run_on_distro(
     client: docker.DockerClient,
     script_path: str,
@@ -585,12 +613,24 @@ def run_on_distro(
     mem_limit: str = "256m",
     pids_limit: int = 128,
     network: str = "bridge",
+    packages: Sequence[str] | None = None,
     prepared_script_path: str | None = None,
 ) -> SingleResult:
     """
     Run a target script inside an unprivileged, non-interactive container.
     Supports posix, shebang, and auto execution modes with strict resource limits.
     """
+    package_list = list(packages or [])
+    if package_list and network == "none":
+        return SingleResult(
+            distro=distro,
+            status=DistroStatus.ERROR,
+            exit_code=None,
+            duration=0.0,
+            output_snippet="",
+            error_message="Package setup requires network mode 'bridge'",
+        )
+
     try:
         mode = ShellMode(shell_mode)
     except ValueError:
@@ -647,6 +687,7 @@ def run_on_distro(
             )
 
     safe_mount_src = normalize_host_path_for_docker(mount_src)
+    container_command = _wrap_with_package_setup(command, package_list)
 
     # Security: Strict unprivileged options and read-only mount
     volumes = {
@@ -667,7 +708,7 @@ def run_on_distro(
         try:
             container = client.containers.create(
                 image=distro,
-                command=command,
+                command=container_command,
                 volumes=volumes,
                 environment=environment,
                 stdin_open=False,
@@ -684,7 +725,7 @@ def run_on_distro(
             client.images.pull(distro)
             container = client.containers.create(
                 image=distro,
-                command=command,
+                command=container_command,
                 volumes=volumes,
                 environment=environment,
                 stdin_open=False,
@@ -799,6 +840,7 @@ def run_matrix(
     mem_limit: str = "256m",
     pids_limit: int = 128,
     network: str = "bridge",
+    packages: Sequence[str] | None = None,
 ) -> RunReport:
     """
     Run the compatibility check across all specified Linux distributions,
@@ -817,6 +859,9 @@ def run_matrix(
             parsed_shebang = inspect_shebang(abs_script)
 
     distro_list = list(matrix) if matrix else DEFAULT_MATRIX
+    package_list = list(packages or [])
+    if package_list and network == "none":
+        raise ValueError("Package setup requires network mode 'bridge'")
     docker_client = client or get_docker_client()
 
     effective_jobs = jobs if (jobs is not None and jobs > 0) else min(2, len(distro_list))
@@ -859,6 +904,7 @@ def run_matrix(
             mem_limit=mem_limit,
             pids_limit=pids_limit,
             network=network,
+            packages=package_list,
             prepared_script_path=prepared_script,
         )
         return index, res

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/tests/test_action_contract.py

@@ -7,13 +7,14 @@ ROOT = Path(__file__).parents[1]
 def test_action_metadata_is_valid_and_inputs_are_wired():
     text = (ROOT / "action.yml").read_text(encoding="utf-8")
     assert "using: 'composite'" in text
-    for name in ("config", "preset", "exclude", "max-scripts", "dry-run", "output", "changed-since"):
+    for name in ("config", "preset", "exclude", "max-scripts", "dry-run", "output", "changed-since", "packages"):
         assert f"  {name}:" in text
     run_text = text
     for flag in ("--timeout", "--format", "--shell", "--mem-limit", "--pids-limit",
-                 "--network", "--matrix", "--jobs", "--config", "--preset",
+                 "--network", "--packages", "--matrix", "--jobs", "--config", "--preset",
                  "--max-scripts", "--output", "--exclude"):
         assert flag in run_text
+    assert "json, or sarif" in text
     assert "--changed-since" in run_text
 
 

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/tests/test_onboarding.py

@@ -69,7 +69,8 @@ def test_init_existing_workflow_leaves_config_absent(project):
 
 @pytest.mark.parametrize("config", [[], {"typo": 1}, {"timeout": True},
     {"jobs": 0}, {"exclude": "tests/*"}, {"shell": "fish"}, {"network": "host"},
-    {"preset": "unknown"}, {"matrix": "alpine", "preset": "minimal"}])
+    {"preset": "unknown"}, {"matrix": "alpine", "preset": "minimal"},
+    {"packages": "curl"}, {"packages": ["curl; touch pwned"]}])
 def test_invalid_config(project, config):
     Path(CONFIG_NAME).write_text(json.dumps(config))
     with patch("opsscript_gate.cli.run_matrix") as run:
@@ -88,6 +89,21 @@ def test_config_cli_precedence_and_saved_plan(project, capsys):
     assert plan["timeout"] == 9
 
 
+def test_packages_are_forwarded_and_visible_in_dry_run(project, capsys):
+    assert main([
+        "run", "install.sh", "--dry-run", "--format", "json",
+        "--packages", "curl,ca-certificates", "--packages", "tar",
+    ]) == 0
+    plan = json.loads(capsys.readouterr().out)
+    assert plan["packages"] == ["curl", "ca-certificates", "tar"]
+
+
+def test_packages_reject_offline_network(project):
+    with patch("opsscript_gate.cli.run_matrix") as run:
+        assert main(["run", "install.sh", "--packages", "curl", "--network", "none"]) == 1
+        run.assert_not_called()
+
+
 def test_preset_overrides_config_matrix(project, capsys):
     Path(CONFIG_NAME).write_text('{"matrix": "custom:1"}')
     assert main(["run", "--dry-run", "--preset", "ubuntu", "--format", "json"]) == 0

{opsscript_gate-0.6.3 → opsscript_gate-0.8.0}/tests/test_runner.py

@@ -8,7 +8,7 @@ from unittest import mock
 import pytest
 from docker.errors import DockerException
 
-from opsscript_gate.cli import build_parser, main, parse_matrix_argument
+from opsscript_gate.cli import build_parser, main, parse_matrix_argument, parse_packages_argument
 from opsscript_gate.discovery import discover_scripts, is_shell_script
 from opsscript_gate.models import DistroStatus, FailureDiagnostic, MultiScriptReport, RunReport, ShellMode, SingleResult
 from opsscript_gate.remediation import generate_remediation_hint, REMEDIATION_RULES
@@ -19,8 +19,10 @@ from opsscript_gate.reporter import (
     format_github_annotations,
     format_github_summary,
     format_json,
+    format_multi_sarif,
     format_multi_github_summary,
     format_multi_terminal_table,
+    format_sarif,
     format_terminal_table,
     write_github_step_summary,
 )
@@ -41,6 +43,7 @@ from opsscript_gate.runner import (
     run_matrix,
     run_on_distro,
     sanitize_diagnostic_text,
+    _wrap_with_package_setup,
 )
 
 
@@ -195,6 +198,50 @@ def test_run_on_distro_pass_mock(tmp_path):
     mock_container.remove.assert_called_once_with(force=True)
 
 
+def test_run_on_distro_package_setup_wraps_command(tmp_path):
+    script_file = tmp_path / "test.sh"
+    script_file.write_text("#!/bin/sh\necho OK\n", encoding="utf-8")
+
+    mock_client = mock.MagicMock()
+    mock_container = mock.MagicMock()
+    mock_container.status = "exited"
+    mock_container.attrs = {"State": {"ExitCode": 0}}
+    mock_container.logs.return_value = b"OK\n"
+    mock_client.containers.create.return_value = mock_container
+
+    result = run_on_distro(
+        mock_client,
+        str(script_file),
+        "alpine:3.20",
+        packages=["curl", "ca-certificates"],
+        network="bridge",
+    )
+
+    assert result.status == DistroStatus.PASS
+    command = mock_client.containers.create.call_args.kwargs["command"]
+    assert command[:2] == ["/bin/sh", "-c"]
+    assert "Dir::Cache::archives=/tmp/opsscript-apt-archives/" in command[2]
+    assert "apk add --no-cache curl ca-certificates" in command[2]
+    assert "exec /bin/sh -c" in command[2]
+
+
+def test_package_setup_requires_network(tmp_path):
+    script_file = tmp_path / "test.sh"
+    script_file.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+    result = run_on_distro(
+        mock.MagicMock(), str(script_file), "alpine:3.20", packages=["curl"], network="none"
+    )
+    assert result.status == DistroStatus.ERROR
+    assert "requires network" in (result.error_message or "")
+
+
+def test_package_setup_quotes_and_validates_names():
+    wrapped = _wrap_with_package_setup(["/bin/sh", "-c", "echo ok"], ["ca-certificates"])
+    assert "ca-certificates" in wrapped[2]
+    with pytest.raises(ValueError):
+        _wrap_with_package_setup(["/bin/sh"], ["curl;touch /tmp/pwned"])
+
+
 def test_run_on_distro_fail_mock(tmp_path):
     script_file = tmp_path / "test_fail.sh"
     script_file.write_text("#!/bin/sh\napt-get: not found\nexit 127\n", encoding="utf-8")
@@ -300,6 +347,54 @@ def test_reporter_json():
     assert data["results"][0]["status"] == "PASS"
 
 
+def test_reporter_sarif_contains_failure_location_and_metadata():
+    result = SingleResult(
+        "alpine:3.20",
+        DistroStatus.FAIL,
+        127,
+        0.42,
+        diagnostic=FailureDiagnostic(
+            kind="missing_command",
+            message="apt-get: command not found",
+            command="apt-get",
+            line=4,
+            distro="alpine:3.20",
+            hint="Use apk instead of apt-get.",
+        ),
+    )
+    report = RunReport([SingleResult("debian:12-slim", DistroStatus.PASS, 0, 0.2), result])
+
+    payload = json.loads(format_sarif(report, script_path="./scripts/install.sh"))
+    assert payload["$schema"].endswith("sarif-2.1.0.json")
+    assert payload["version"] == "2.1.0"
+    finding = payload["runs"][0]["results"][0]
+    assert finding["ruleId"] == "OSG001"
+    assert finding["level"] == "error"
+    assert finding["locations"][0]["physicalLocation"]["artifactLocation"]["uri"] == "scripts/install.sh"
+    assert finding["locations"][0]["physicalLocation"]["region"]["startLine"] == 4
+    assert finding["properties"]["distribution"] == "alpine:3.20"
+    assert finding["properties"]["command"] == "apt-get"
+
+
+def test_reporter_multi_sarif_keeps_script_paths():
+    report = MultiScriptReport(
+        reports={
+            "install.sh": RunReport([SingleResult("alpine:3.20", DistroStatus.FAIL, 1, 0.1)]),
+            "scripts/setup.sh": RunReport([SingleResult("debian:12-slim", DistroStatus.TIMED_OUT, None, 5.0)]),
+        },
+        total_duration=5.1,
+    )
+
+    payload = json.loads(format_multi_sarif(report))
+    results = payload["runs"][0]["results"]
+    assert len(results) == 2
+    paths = {
+        result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
+        for result in results
+    }
+    assert paths == {"install.sh", "scripts/setup.sh"}
+
+
 def test_write_github_step_summary(tmp_path):
     summary_file = tmp_path / "step_summary.md"
     r1 = SingleResult("debian:12-slim", DistroStatus.PASS, 0, 1.0)
@@ -322,6 +417,14 @@ def test_parse_matrix_argument():
     assert parse_matrix_argument("debian:12-slim, alpine:3.20") == ["debian:12-slim", "alpine:3.20"]
 
 
+def test_parse_packages_argument():
+    assert parse_packages_argument(["curl, ca-certificates", "tar"]) == [
+        "curl", "ca-certificates", "tar"
+    ]
+    with pytest.raises(ValueError, match="package"):
+        parse_packages_argument(["curl && touch pwned"])
+
+
 def test_cli_help(capsys):
     parser = build_parser()
     with pytest.raises(SystemExit):
@@ -871,6 +974,27 @@ def test_integration_pass_basic():
     assert report.results[0].status == DistroStatus.PASS
 
 
+@pytest.mark.integration
+@pytest.mark.skipif(not is_docker_daemon_available(), reason="Docker daemon is not running or accessible")
+@pytest.mark.parametrize("image", DEFAULT_MATRIX)
+def test_integration_package_setup(tmp_path, image):
+    script = tmp_path / "needs-curl.sh"
+    script.write_text(
+        "#!/usr/bin/env bash\nset -e\ncurl --version >/dev/null\ntar --version >/dev/null\n"
+        "test -s /etc/ssl/certs/ca-certificates.crt\n", encoding="utf-8"
+    )
+    report = run_matrix(
+        str(script),
+        matrix=[image],
+        packages=["bash", "curl", "ca-certificates", "tar"],
+        shell_mode="auto",
+        network="bridge",
+        timeout=120,
+    )
+    assert report.all_passed is True, report.to_dict()
+    assert report.results[0].status == DistroStatus.PASS
+
+
 @pytest.mark.integration
 @pytest.mark.skipif(not is_docker_daemon_available(), reason="Docker daemon is not running or accessible")
 def test_integration_fail_deps_alpine():