pipewatch-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 David Obi
+
 
 pipewatch-cli is licensed under the Creative Commons Attribution 4.0
 International License. To view a copy of this license, see below or
@@ -401,3 +401,5 @@ the avoidance of doubt, this paragraph does not form part of the
 public licenses.
 
 Creative Commons may be contacted at creativecommons.org.
+
+Copyright (c) 2026 David Obi

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipewatch-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Integrity monitoring and static analysis for CI/CD pipelines
 License-Expression: CC-BY-4.0
 Requires-Python: >=3.12
@@ -13,9 +13,9 @@ Dynamic: license-file
 
 **Integrity monitoring and static analysis for software supply chains.**
 
-CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure — and the attack surface is almost always left unmonitored.
+CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure -- and the attack surface is almost always left unmonitored.
 
-`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON — suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
+`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON -- suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
 
 ---
 
@@ -25,16 +25,16 @@ CI/CD pipelines are high-value targets: they run with elevated permissions, pull
 |---|---|
 | **Baseline diff** | Pipeline files modified, added, or deleted since a known-good commit |
 | **Step fingerprinting** | Individual steps injected, removed, or silently modified between commits |
-| **`pull_request_target` misuse** | Workflows that check out and execute PR head code with base-branch write permissions — the pattern behind numerous CI poisoning attacks |
-| **Script injection** | `run:` blocks and `env:` blocks that route user-controlled context values (`github.event.pull_request.title`, `github.event.comment.body`, etc.) into shell commands — both direct interpolation and the indirect `env: VAR: ${{ ctx }}` → `$VAR` pattern are detected |
-| **Permission misconfiguration** | Missing `permissions:` blocks, `write-all` scopes, `secrets: inherit` |
-| **Mutable action pins** | `uses:` references not locked to a full commit SHA — tags like `v3` can be silently overwritten by a supply-chain attacker |
+| **pull_request_target misuse** | Workflows that check out and execute PR head code with base-branch write permissions -- the pattern behind numerous CI poisoning attacks |
+| **Script injection** | run: blocks and env: blocks that route user-controlled context values into shell commands -- both direct interpolation and the indirect env: VAR -> $VAR pattern are detected |
+| **Permission misconfiguration** | Missing permissions: blocks, write-all scopes, secrets: inherit |
+| **Mutable action pins** | uses: references not locked to a full commit SHA -- tags like v3 can be silently overwritten by a supply-chain attacker |
 | **Invalid pinned SHAs** | Pinned SHAs that do not exist in the upstream action repo (typos, deleted commits, fork SHAs) |
-| **Unsafe `workflow_run` chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
+| **Unsafe workflow_run chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
 | **Self-hosted runners** | Non-ephemeral runners that persist state between runs and are not managed by GitHub |
 | **Runner environment drift** | Env var and tool version changes between CI runs that could indicate a compromised or modified runner |
 
-Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and always include a location, description, and evidence field.
+Findings are severity-ranked (CRITICAL -> HIGH -> MEDIUM -> LOW -> INFO) and always include a location, description, and evidence field.
 
 ---
 
@@ -43,26 +43,30 @@ Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and
 Requires Python 3.12+. `pyyaml` is the only external dependency.
 
 **Via pip (recommended):**
-```bash
-pip install pipewatch
+
+```
+pip install pipewatch-cli
 ```
 
 **Directly from GitHub (no clone required):**
-```bash
+
+```
 pip install git+https://github.com/TheVoidThatConsumes/pipewatch.git
 ```
 
-**Copy into your project** — if you prefer to keep pipewatch self-contained inside a repo you're monitoring, download `pipewatch.py` and drop it anywhere in that repo. Install `pyyaml` manually:
-```bash
+**Copy into your project** -- download `pipewatch.py` and drop it anywhere in the repo you want to monitor. Install `pyyaml` manually:
+
+```
 pip install pyyaml
 ```
+
 Then run it as `py pipewatch.py <command>` instead of `pipewatch <command>`.
 
 ---
 
 ## Quick Start
 
-```bash
+```
 # Record the current HEAD as known-good
 pipewatch baseline
 
@@ -78,18 +82,20 @@ pipewatch audit --verify-shas
 ## Commands
 
 ### `baseline`
-Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline — if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
 
-```bash
+Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline -- if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
+
+```
 pipewatch baseline [--repo PATH] [--commit SHA]
 ```
 
 ---
 
 ### `scan`
-Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering — a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
 
-```bash
+Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering -- a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
+
+```
 pipewatch scan [--repo PATH] [--baseline SHA] [--verbose] [--json]
 ```
 
@@ -98,37 +104,40 @@ Covers GitHub Actions, GitLab CI, and Jenkinsfile stages.
 ---
 
 ### `static`
+
 Static analysis with no baseline required. Audits all GitHub Actions workflow files in `.github/workflows/` for structural misconfigurations.
 
-```bash
+```
 pipewatch static [--repo PATH] [--verbose] [--json]
 ```
 
-Checks: `pull_request_target` misuse · script injection · missing/overpermissioned `permissions:` blocks · `secrets: inherit` · self-hosted runners · unsafe `workflow_run` trigger chains.
+Checks: `pull_request_target` misuse, script injection, missing or overpermissioned `permissions:` blocks, `secrets: inherit`, self-hosted runners, unsafe `workflow_run` trigger chains.
 
 ---
 
 ### `pin-audit`
+
 Flags `uses:` references not pinned to a full 40- or 64-character commit SHA. With `--verify-shas`, makes live GitHub API calls to confirm each pinned SHA actually exists in its upstream repository.
 
-```bash
+```
 pipewatch pin-audit [--repo PATH] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
-Rate limit: 60 requests/hr unauthenticated, 5 000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated — the same `owner/repo@sha` is only verified once regardless of how many steps reference it. Findings are **not** deduplicated: if the same invalid SHA appears across multiple workflow files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible in the report.
+Rate limit: 60 requests/hr unauthenticated, 5000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated -- the same `owner/repo@sha` is only verified once. Findings are **not** deduplicated: if the same invalid SHA appears across multiple files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible.
 
 ---
 
 ### `snapshot`
-Captures the runner environment — environment variables and tool versions — to a JSON file for later comparison.
 
-```bash
+Captures the runner environment -- environment variables and tool versions -- to a JSON file for later comparison.
+
+```
 pipewatch snapshot [--output FILE]
 ```
 
 Tracked tools: `python3`, `python`, `node`, `npm`, `pip`, `pip3`, `git`, `curl`, `wget`, `docker`, `kubectl`, `terraform`, `aws`, `gcloud`, `az`. Volatile per-run variables (`GITHUB_RUN_ID`, `RUNNER_TEMP`, etc.) are excluded to prevent noise on every comparison.
 
-**Credential exclusion** — environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache. Note that a legitimately non-sensitive variable with one of these terms in its name will also be excluded; rename it if you need `env-diff` to track it.
+**Credential exclusion** -- environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache.
 
 Add the snapshot file to `.gitignore` to prevent it from being accidentally committed:
 
@@ -139,27 +148,30 @@ Add the snapshot file to `.gitignore` to prevent it from being accidentally comm
 ---
 
 ### `env-diff`
-Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions — useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
 
-```bash
+Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions -- useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
+
+```
 pipewatch env-diff BASELINE_SNAPSHOT [--current-snapshot FILE] [--repo PATH] [--verbose] [--json]
 ```
 
 ---
 
 ### `audit`
+
 Full audit in one pass: `scan` + `pin-audit` + `static`. Exits non-zero if any findings exist.
 
-```bash
+```
 pipewatch audit [--repo PATH] [--baseline SHA] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
 ---
 
 ### `init-runner`
+
 Prints a ready-to-paste GitHub Actions step block that adds runner environment monitoring to any existing job.
 
-```bash
+```
 pipewatch init-runner [--snapshot-path PATH]
 ```
 
@@ -171,10 +183,10 @@ pipewatch init-runner [--snapshot-path PATH]
 |---|---|---|
 | `PW-DIFF-NNN` | Pipeline file added / modified / deleted | HIGH / MEDIUM |
 | `PW-STEP-NNN` | Step fingerprint changed / injected / removed | HIGH / MEDIUM |
-| `PW-PRT-NNN` | `pull_request_target` misuse | HIGH |
+| `PW-PRT-NNN` | pull_request_target misuse | HIGH |
 | `PW-INJ-NNN` | Script injection risk | HIGH |
 | `PW-PERM-NNN` | Permission misconfiguration | HIGH / MEDIUM |
-| `PW-CHAIN-NNN` | Unsafe `workflow_run` chain | HIGH |
+| `PW-CHAIN-NNN` | Unsafe workflow_run chain | HIGH |
 | `PW-PIN-NNN` | Unpinned action reference | MEDIUM |
 | `PW-SHA-NNN` | Pinned SHA not found in upstream repo | HIGH |
 | `PW-RUNNER-NNN` | Self-hosted runner | INFO |
@@ -186,7 +198,7 @@ pipewatch init-runner [--snapshot-path PATH]
 
 All commands accept `--json`:
 
-```json
+```
 {
   "tool": "pipewatch",
   "version": "0.2.0",
@@ -210,7 +222,7 @@ All commands accept `--json`:
 
 Gate on exit code, or filter with `jq`:
 
-```bash
+```
 # fail the build on any HIGH or CRITICAL finding
 pipewatch audit --json | jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0'
 
@@ -224,7 +236,7 @@ pipewatch audit --json | jq -r '.findings[].title'
 
 Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a signed JSON object:
 
-```json
+```
 {
   "commit": "abc123...",
   "timestamp": "2025-01-01T00:00:00+00:00",
@@ -234,24 +246,24 @@ Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a
 
 The HMAC is computed over both the commit SHA **and** the timestamp, bound together. This protects against two distinct attacks:
 
-- **Tampering** — an attacker who modifies the `commit` field to point to an older known-good commit cannot produce a valid HMAC without the key.
-- **Replay** — an attacker who reverts the baseline file to a previously-valid signed snapshot (to suppress findings introduced after that point) is also blocked, because the timestamp is part of the signed payload and the stored timestamp would no longer match the signature of any rewritten content.
+- **Tampering** -- an attacker who modifies the `commit` field cannot produce a valid HMAC without the key.
+- **Replay** -- an attacker who reverts the baseline file to a previously-valid signed snapshot is also blocked, because the timestamp is part of the signed payload.
 
 On `scan` or `audit`, the HMAC is verified before the baseline commit is trusted. Any verification failure causes an immediate exit with an error.
 
-**Format-downgrade protection** — if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format (a raw commit SHA rather than signed JSON), the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
+**Format-downgrade protection** -- if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format, the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
 
-Store the key in a CI secret (`PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}`).
+Store the key in a CI secret.
 
 ---
 
 ## Pipeline Integration
 
-```yaml
+```
 - name: pipewatch audit
   env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}
+    GITHUB_TOKEN: (your GITHUB_TOKEN secret)
+    PIPEWATCH_HMAC_KEY: (your PIPEWATCH_HMAC_KEY secret)
   run: |
     pipewatch audit --verify-shas --json | tee pw-report.json
     jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0' pw-report.json
@@ -263,13 +275,13 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 ## Design Decisions
 
-**HMAC-signed baselines** — tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC — not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
+**HMAC-signed baselines** -- tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC -- not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
 
-**Volatile variable exclusion** — `snapshot` strips run-specific GitHub variables so that `env-diff` doesn't generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials (containing `token`, `secret`, `key`, `password`, etc.) are also excluded so secrets are never written to the snapshot file or the Actions cache.
+**Volatile variable exclusion** -- `snapshot` strips run-specific GitHub variables so that `env-diff` does not generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials are also excluded so secrets are never written to the snapshot file or the Actions cache.
 
-**Conservative SHA verification** — `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
+**Conservative SHA verification** -- `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
 
-**Stdlib-first** — `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
+**Stdlib-first** -- `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
 
 ---
 
@@ -277,12 +289,12 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 | Platform | Coverage |
 |---|---|
-| GitHub Actions (`.github/workflows/*.yml`) | Full — file diff, step fingerprinting, static analysis, pin audit |
-| GitLab CI (`.gitlab-ci.yml`) | File diff + `before_script` / `script` / `after_script` fingerprinting |
-| Jenkins (`Jenkinsfile`) | File diff + best-effort stage / `sh` / `bat` fingerprinting (regex-based — not a Groovy parser) |
+| GitHub Actions (.github/workflows/*.yml) | Full -- file diff, step fingerprinting, static analysis, pin audit. Step evidence includes uses, run first line, or step name. |
+| GitLab CI (.gitlab-ci.yml) | File diff + before_script / script / after_script fingerprinting. Step evidence shows the first command in the changed block. |
+| Jenkins (Jenkinsfile) | File diff + best-effort stage / sh / bat fingerprinting (regex-based, not a Groovy parser). Step evidence shows the first sh/bat command where extractable; falls back to stage name. |
 
 ---
 
 ## License
 
-GPLv2. See [LICENSE](LICENSE).
+Copyright (c) 2026 David Obi. Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). See [LICENSE](LICENSE).

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/README.md

@@ -2,9 +2,9 @@
 
 **Integrity monitoring and static analysis for software supply chains.**
 
-CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure — and the attack surface is almost always left unmonitored.
+CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure -- and the attack surface is almost always left unmonitored.
 
-`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON — suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
+`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON -- suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
 
 ---
 
@@ -14,16 +14,16 @@ CI/CD pipelines are high-value targets: they run with elevated permissions, pull
 |---|---|
 | **Baseline diff** | Pipeline files modified, added, or deleted since a known-good commit |
 | **Step fingerprinting** | Individual steps injected, removed, or silently modified between commits |
-| **`pull_request_target` misuse** | Workflows that check out and execute PR head code with base-branch write permissions — the pattern behind numerous CI poisoning attacks |
-| **Script injection** | `run:` blocks and `env:` blocks that route user-controlled context values (`github.event.pull_request.title`, `github.event.comment.body`, etc.) into shell commands — both direct interpolation and the indirect `env: VAR: ${{ ctx }}` → `$VAR` pattern are detected |
-| **Permission misconfiguration** | Missing `permissions:` blocks, `write-all` scopes, `secrets: inherit` |
-| **Mutable action pins** | `uses:` references not locked to a full commit SHA — tags like `v3` can be silently overwritten by a supply-chain attacker |
+| **pull_request_target misuse** | Workflows that check out and execute PR head code with base-branch write permissions -- the pattern behind numerous CI poisoning attacks |
+| **Script injection** | run: blocks and env: blocks that route user-controlled context values into shell commands -- both direct interpolation and the indirect env: VAR -> $VAR pattern are detected |
+| **Permission misconfiguration** | Missing permissions: blocks, write-all scopes, secrets: inherit |
+| **Mutable action pins** | uses: references not locked to a full commit SHA -- tags like v3 can be silently overwritten by a supply-chain attacker |
 | **Invalid pinned SHAs** | Pinned SHAs that do not exist in the upstream action repo (typos, deleted commits, fork SHAs) |
-| **Unsafe `workflow_run` chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
+| **Unsafe workflow_run chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
 | **Self-hosted runners** | Non-ephemeral runners that persist state between runs and are not managed by GitHub |
 | **Runner environment drift** | Env var and tool version changes between CI runs that could indicate a compromised or modified runner |
 
-Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and always include a location, description, and evidence field.
+Findings are severity-ranked (CRITICAL -> HIGH -> MEDIUM -> LOW -> INFO) and always include a location, description, and evidence field.
 
 ---
 
@@ -32,26 +32,30 @@ Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and
 Requires Python 3.12+. `pyyaml` is the only external dependency.
 
 **Via pip (recommended):**
-```bash
-pip install pipewatch
+
+```
+pip install pipewatch-cli
 ```
 
 **Directly from GitHub (no clone required):**
-```bash
+
+```
 pip install git+https://github.com/TheVoidThatConsumes/pipewatch.git
 ```
 
-**Copy into your project** — if you prefer to keep pipewatch self-contained inside a repo you're monitoring, download `pipewatch.py` and drop it anywhere in that repo. Install `pyyaml` manually:
-```bash
+**Copy into your project** -- download `pipewatch.py` and drop it anywhere in the repo you want to monitor. Install `pyyaml` manually:
+
+```
 pip install pyyaml
 ```
+
 Then run it as `py pipewatch.py <command>` instead of `pipewatch <command>`.
 
 ---
 
 ## Quick Start
 
-```bash
+```
 # Record the current HEAD as known-good
 pipewatch baseline
 
@@ -67,18 +71,20 @@ pipewatch audit --verify-shas
 ## Commands
 
 ### `baseline`
-Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline — if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
 
-```bash
+Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline -- if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
+
+```
 pipewatch baseline [--repo PATH] [--commit SHA]
 ```
 
 ---
 
 ### `scan`
-Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering — a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
 
-```bash
+Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering -- a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
+
+```
 pipewatch scan [--repo PATH] [--baseline SHA] [--verbose] [--json]
 ```
 
@@ -87,37 +93,40 @@ Covers GitHub Actions, GitLab CI, and Jenkinsfile stages.
 ---
 
 ### `static`
+
 Static analysis with no baseline required. Audits all GitHub Actions workflow files in `.github/workflows/` for structural misconfigurations.
 
-```bash
+```
 pipewatch static [--repo PATH] [--verbose] [--json]
 ```
 
-Checks: `pull_request_target` misuse · script injection · missing/overpermissioned `permissions:` blocks · `secrets: inherit` · self-hosted runners · unsafe `workflow_run` trigger chains.
+Checks: `pull_request_target` misuse, script injection, missing or overpermissioned `permissions:` blocks, `secrets: inherit`, self-hosted runners, unsafe `workflow_run` trigger chains.
 
 ---
 
 ### `pin-audit`
+
 Flags `uses:` references not pinned to a full 40- or 64-character commit SHA. With `--verify-shas`, makes live GitHub API calls to confirm each pinned SHA actually exists in its upstream repository.
 
-```bash
+```
 pipewatch pin-audit [--repo PATH] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
-Rate limit: 60 requests/hr unauthenticated, 5 000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated — the same `owner/repo@sha` is only verified once regardless of how many steps reference it. Findings are **not** deduplicated: if the same invalid SHA appears across multiple workflow files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible in the report.
+Rate limit: 60 requests/hr unauthenticated, 5000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated -- the same `owner/repo@sha` is only verified once. Findings are **not** deduplicated: if the same invalid SHA appears across multiple files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible.
 
 ---
 
 ### `snapshot`
-Captures the runner environment — environment variables and tool versions — to a JSON file for later comparison.
 
-```bash
+Captures the runner environment -- environment variables and tool versions -- to a JSON file for later comparison.
+
+```
 pipewatch snapshot [--output FILE]
 ```
 
 Tracked tools: `python3`, `python`, `node`, `npm`, `pip`, `pip3`, `git`, `curl`, `wget`, `docker`, `kubectl`, `terraform`, `aws`, `gcloud`, `az`. Volatile per-run variables (`GITHUB_RUN_ID`, `RUNNER_TEMP`, etc.) are excluded to prevent noise on every comparison.
 
-**Credential exclusion** — environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache. Note that a legitimately non-sensitive variable with one of these terms in its name will also be excluded; rename it if you need `env-diff` to track it.
+**Credential exclusion** -- environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache.
 
 Add the snapshot file to `.gitignore` to prevent it from being accidentally committed:
 
@@ -128,27 +137,30 @@ Add the snapshot file to `.gitignore` to prevent it from being accidentally comm
 ---
 
 ### `env-diff`
-Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions — useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
 
-```bash
+Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions -- useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
+
+```
 pipewatch env-diff BASELINE_SNAPSHOT [--current-snapshot FILE] [--repo PATH] [--verbose] [--json]
 ```
 
 ---
 
 ### `audit`
+
 Full audit in one pass: `scan` + `pin-audit` + `static`. Exits non-zero if any findings exist.
 
-```bash
+```
 pipewatch audit [--repo PATH] [--baseline SHA] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
 ---
 
 ### `init-runner`
+
 Prints a ready-to-paste GitHub Actions step block that adds runner environment monitoring to any existing job.
 
-```bash
+```
 pipewatch init-runner [--snapshot-path PATH]
 ```
 
@@ -160,10 +172,10 @@ pipewatch init-runner [--snapshot-path PATH]
 |---|---|---|
 | `PW-DIFF-NNN` | Pipeline file added / modified / deleted | HIGH / MEDIUM |
 | `PW-STEP-NNN` | Step fingerprint changed / injected / removed | HIGH / MEDIUM |
-| `PW-PRT-NNN` | `pull_request_target` misuse | HIGH |
+| `PW-PRT-NNN` | pull_request_target misuse | HIGH |
 | `PW-INJ-NNN` | Script injection risk | HIGH |
 | `PW-PERM-NNN` | Permission misconfiguration | HIGH / MEDIUM |
-| `PW-CHAIN-NNN` | Unsafe `workflow_run` chain | HIGH |
+| `PW-CHAIN-NNN` | Unsafe workflow_run chain | HIGH |
 | `PW-PIN-NNN` | Unpinned action reference | MEDIUM |
 | `PW-SHA-NNN` | Pinned SHA not found in upstream repo | HIGH |
 | `PW-RUNNER-NNN` | Self-hosted runner | INFO |
@@ -175,7 +187,7 @@ pipewatch init-runner [--snapshot-path PATH]
 
 All commands accept `--json`:
 
-```json
+```
 {
   "tool": "pipewatch",
   "version": "0.2.0",
@@ -199,7 +211,7 @@ All commands accept `--json`:
 
 Gate on exit code, or filter with `jq`:
 
-```bash
+```
 # fail the build on any HIGH or CRITICAL finding
 pipewatch audit --json | jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0'
 
@@ -213,7 +225,7 @@ pipewatch audit --json | jq -r '.findings[].title'
 
 Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a signed JSON object:
 
-```json
+```
 {
   "commit": "abc123...",
   "timestamp": "2025-01-01T00:00:00+00:00",
@@ -223,24 +235,24 @@ Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a
 
 The HMAC is computed over both the commit SHA **and** the timestamp, bound together. This protects against two distinct attacks:
 
-- **Tampering** — an attacker who modifies the `commit` field to point to an older known-good commit cannot produce a valid HMAC without the key.
-- **Replay** — an attacker who reverts the baseline file to a previously-valid signed snapshot (to suppress findings introduced after that point) is also blocked, because the timestamp is part of the signed payload and the stored timestamp would no longer match the signature of any rewritten content.
+- **Tampering** -- an attacker who modifies the `commit` field cannot produce a valid HMAC without the key.
+- **Replay** -- an attacker who reverts the baseline file to a previously-valid signed snapshot is also blocked, because the timestamp is part of the signed payload.
 
 On `scan` or `audit`, the HMAC is verified before the baseline commit is trusted. Any verification failure causes an immediate exit with an error.
 
-**Format-downgrade protection** — if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format (a raw commit SHA rather than signed JSON), the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
+**Format-downgrade protection** -- if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format, the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
 
-Store the key in a CI secret (`PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}`).
+Store the key in a CI secret.
 
 ---
 
 ## Pipeline Integration
 
-```yaml
+```
 - name: pipewatch audit
   env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}
+    GITHUB_TOKEN: (your GITHUB_TOKEN secret)
+    PIPEWATCH_HMAC_KEY: (your PIPEWATCH_HMAC_KEY secret)
   run: |
     pipewatch audit --verify-shas --json | tee pw-report.json
     jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0' pw-report.json
@@ -252,13 +264,13 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 ## Design Decisions
 
-**HMAC-signed baselines** — tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC — not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
+**HMAC-signed baselines** -- tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC -- not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
 
-**Volatile variable exclusion** — `snapshot` strips run-specific GitHub variables so that `env-diff` doesn't generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials (containing `token`, `secret`, `key`, `password`, etc.) are also excluded so secrets are never written to the snapshot file or the Actions cache.
+**Volatile variable exclusion** -- `snapshot` strips run-specific GitHub variables so that `env-diff` does not generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials are also excluded so secrets are never written to the snapshot file or the Actions cache.
 
-**Conservative SHA verification** — `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
+**Conservative SHA verification** -- `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
 
-**Stdlib-first** — `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
+**Stdlib-first** -- `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
 
 ---
 
@@ -266,12 +278,12 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 | Platform | Coverage |
 |---|---|
-| GitHub Actions (`.github/workflows/*.yml`) | Full — file diff, step fingerprinting, static analysis, pin audit |
-| GitLab CI (`.gitlab-ci.yml`) | File diff + `before_script` / `script` / `after_script` fingerprinting |
-| Jenkins (`Jenkinsfile`) | File diff + best-effort stage / `sh` / `bat` fingerprinting (regex-based — not a Groovy parser) |
+| GitHub Actions (.github/workflows/*.yml) | Full -- file diff, step fingerprinting, static analysis, pin audit. Step evidence includes uses, run first line, or step name. |
+| GitLab CI (.gitlab-ci.yml) | File diff + before_script / script / after_script fingerprinting. Step evidence shows the first command in the changed block. |
+| Jenkins (Jenkinsfile) | File diff + best-effort stage / sh / bat fingerprinting (regex-based, not a Groovy parser). Step evidence shows the first sh/bat command where extractable; falls back to stage name. |
 
 ---
 
 ## License
 
-GPLv2. See [LICENSE](LICENSE).
+Copyright (c) 2026 David Obi. Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). See [LICENSE](LICENSE).

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/pipewatch.py

@@ -253,6 +253,51 @@ class StepChange:
     baseline_fp: Optional[str]
     current_fp: Optional[str]
     status: str
+    step_preview: Optional[str] = None  # human-readable hint: uses/run first line/name
+
+
+def _preview_step(step: dict) -> str:
+    """Return a one-line description of a GitHub Actions step."""
+    if not isinstance(step, dict):
+        return ""
+    if "uses" in step:
+        return f"uses={step['uses']}"
+    if "run" in step:
+        first = next((ln.strip() for ln in str(step["run"]).splitlines() if ln.strip()), "")
+        return f"run={(first[:80] + '…') if len(first) > 80 else first}"
+    if "name" in step:
+        return f"name={step['name']}"
+    return ""
+
+
+def _preview_gitlab_block(doc: dict, job: str, block_idx: int) -> str:
+    """Return first command from a GitLab before_script/script/after_script block."""
+    block_name = ("before_script", "script", "after_script")[block_idx]
+    job_def = doc.get(job, {})
+    if not isinstance(job_def, dict):
+        return ""
+    cmds = job_def.get(block_name, [])
+    if isinstance(cmds, list) and cmds:
+        first = str(cmds[0]).strip()
+        return f"{block_name}={(first[:80] + '…') if len(first) > 80 else first}"
+    return block_name
+
+
+def _preview_jenkins_stage(content: str, stage_name: str) -> str:
+    """Return first sh/bat command from a Jenkinsfile stage (best-effort, regex-based)."""
+    stages = list(_JENKINS_STAGE.finditer(content))
+    for i, m in enumerate(stages):
+        if m.group(1) != stage_name:
+            continue
+        start = m.start()
+        end = stages[i + 1].start() if i + 1 < len(stages) else len(content)
+        sh_match = _JENKINS_SH.search(content[start:end])
+        if sh_match:
+            cmd = next((g for g in sh_match.groups() if g is not None), "").strip()
+            if cmd:
+                return f"sh={(cmd[:80] + '…') if len(cmd) > 80 else cmd}"
+        return f"stage={stage_name}"
+    return ""
 
 
 def _fps_for_file(fpath: Path, rel: str, content: str) -> dict:
@@ -271,15 +316,37 @@ def diff_fingerprints(repo: Path, baseline: str) -> list[StepChange]:
         base_content = git_show(repo, baseline, rel)
         cur = _fps_for_file(fpath, rel, current_content)
         bas = _fps_for_file(fpath, rel, base_content) if base_content else {}
+
+        is_jenkins = fpath.name == "Jenkinsfile"
+        is_gitlab = fpath.name in (".gitlab-ci.yml", ".gitlab-ci.yaml")
+
+        try:
+            cur_doc = {} if is_jenkins else (yaml.safe_load(current_content) or {})
+        except yaml.YAMLError:
+            cur_doc = {}
+
+        def _get_preview(job_name: str, step_idx: int) -> str:
+            if is_jenkins:
+                return _preview_jenkins_stage(current_content, job_name)
+            if is_gitlab:
+                return _preview_gitlab_block(cur_doc, job_name, step_idx)
+            steps = (cur_doc.get("jobs") or {}).get(job_name, {}).get("steps") or []
+            step = steps[step_idx] if isinstance(steps, list) and step_idx < len(steps) else {}
+            return _preview_step(step)
+
         for key in sorted(set(cur) | set(bas)):
             c, b = cur.get(key), bas.get(key)
+            job_name, step_idx = key
+            preview = _get_preview(job_name, step_idx)
             if b is None:
-                changes.append(StepChange(rel, key[0], key[1], c[0] if c else None,
-                                          None, c[1] if c else None, "added"))
+                changes.append(StepChange(rel, job_name, step_idx, c[0] if c else None,
+                                          None, c[1] if c else None, "added", preview))
             elif c is None:
-                changes.append(StepChange(rel, key[0], key[1], b[0], b[1], None, "removed"))
+                changes.append(StepChange(rel, job_name, step_idx, b[0], b[1], None,
+                                          "removed", preview))
             elif c[1] != b[1]:
-                changes.append(StepChange(rel, key[0], key[1], c[0], b[1], c[1], "modified"))
+                changes.append(StepChange(rel, job_name, step_idx, c[0], b[1], c[1],
+                                          "modified", preview))
     return changes
 
 
@@ -857,32 +924,53 @@ def _findings_from_steps(changes: list[StepChange]) -> list[dict]:
     out = []
     for i, c in enumerate(changes, 1):
         loc = f"{c.path}::{c.job}::step[{c.step_index}]"
+        preview = f"  {c.step_preview}" if c.step_preview else ""
         if c.status == "modified":
             out.append(_finding(f"PW-STEP-{i:03d}", "HIGH", "step_fingerprint",
                 f"Step fingerprint changed: {loc}",
                 f"Step {c.step_index} in '{c.job}' changed — possible injected command or swapped action.",
-                loc, f"baseline={c.baseline_fp}  current={c.current_fp}"))
+                loc, f"baseline={c.baseline_fp}  current={c.current_fp}{preview}"))
         elif c.status == "added":
             out.append(_finding(f"PW-STEP-{i:03d}", "HIGH", "step_fingerprint",
                 f"New step injected: {loc}",
                 f"Step {c.step_index} in '{c.job}' of '{c.path}' did not exist at baseline.",
-                loc, f"fingerprint={c.current_fp}"))
+                loc, f"fingerprint={c.current_fp}{preview}"))
         else:
             out.append(_finding(f"PW-STEP-{i:03d}", "MEDIUM", "step_fingerprint",
                 f"Step removed: {loc}",
                 f"Step {c.step_index} in '{c.job}' of '{c.path}' was removed since baseline.",
-                loc, f"baseline_fp={c.baseline_fp}"))
+                loc, f"baseline_fp={c.baseline_fp}{preview}"))
     return out
 
 
 def _findings_from_pinning(pinning: list[PinningFinding]) -> list[dict]:
-    return [_finding(
-        f"PW-PIN-{i:03d}", "MEDIUM", "unpinned_dependency",
-        f"Unpinned action: {p.uses_ref}",
-        f"Step {p.step_index} in '{p.job}' of '{p.path}' uses '{p.uses_ref}', "
-        "not pinned to a commit SHA — mutable tags can be silently overwritten.",
-        f"{p.path}::{p.job}::step[{p.step_index}]", p.recommendation,
-    ) for i, p in enumerate(pinning, 1)]
+    """One finding per unique action reference, listing all affected files and step count."""
+    # Group by uses_ref so actions/checkout@v3 across 16 files → one finding.
+    grouped: dict[str, list[PinningFinding]] = {}
+    for p in pinning:
+        grouped.setdefault(p.uses_ref, []).append(p)
+
+    out = []
+    for i, (ref, instances) in enumerate(sorted(grouped.items()), 1):
+        affected_files = sorted(set(p.path for p in instances))
+        step_count = len(instances)
+        file_count = len(affected_files)
+        action = ref.split("@")[0] if "@" in ref else ref
+        tag = ref.split("@")[1] if "@" in ref else "unversioned"
+        file_list = ", ".join(affected_files[:5])
+        if file_count > 5:
+            file_list += f" … and {file_count - 5} more"
+        out.append(_finding(
+            f"PW-PIN-{i:03d}", "MEDIUM", "unpinned_dependency",
+            f"Unpinned action: {ref}",
+            f"'{ref}' is not pinned to a commit SHA — mutable tags can be silently "
+            "overwritten by a supply-chain attacker. "
+            f"Found in {step_count} step(s) across {file_count} file(s).",
+            file_list,
+            f"fix: uses: {action}@<sha>  # {tag}\n"
+            f"  https://github.com/{action}/commits",
+        ))
+    return out
 
 
 def _findings_from_env(diff: EnvDiff) -> list[dict]:

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/pipewatch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipewatch-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Integrity monitoring and static analysis for CI/CD pipelines
 License-Expression: CC-BY-4.0
 Requires-Python: >=3.12
@@ -13,9 +13,9 @@ Dynamic: license-file
 
 **Integrity monitoring and static analysis for software supply chains.**
 
-CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure — and the attack surface is almost always left unmonitored.
+CI/CD pipelines are high-value targets: they run with elevated permissions, pull from external registries, and execute arbitrary code on every commit. A single injected step, mutable action pin, or misconfigured trigger is enough to exfiltrate secrets, backdoor build artifacts, or pivot into production infrastructure -- and the attack surface is almost always left unmonitored.
 
-`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON — suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
+`pipewatch` audits GitHub Actions workflows, GitLab CI, and Jenkinsfiles for exactly these risks. It combines commit-anchored baseline diffing, per-step SHA-256 fingerprinting, static misconfiguration analysis, and runner environment tracking into a single CLI tool. All commands exit non-zero on findings and emit structured JSON -- suitable as a pipeline gate, a pre-merge check, or a periodic audit job.
 
 ---
 
@@ -25,16 +25,16 @@ CI/CD pipelines are high-value targets: they run with elevated permissions, pull
 |---|---|
 | **Baseline diff** | Pipeline files modified, added, or deleted since a known-good commit |
 | **Step fingerprinting** | Individual steps injected, removed, or silently modified between commits |
-| **`pull_request_target` misuse** | Workflows that check out and execute PR head code with base-branch write permissions — the pattern behind numerous CI poisoning attacks |
-| **Script injection** | `run:` blocks and `env:` blocks that route user-controlled context values (`github.event.pull_request.title`, `github.event.comment.body`, etc.) into shell commands — both direct interpolation and the indirect `env: VAR: ${{ ctx }}` → `$VAR` pattern are detected |
-| **Permission misconfiguration** | Missing `permissions:` blocks, `write-all` scopes, `secrets: inherit` |
-| **Mutable action pins** | `uses:` references not locked to a full commit SHA — tags like `v3` can be silently overwritten by a supply-chain attacker |
+| **pull_request_target misuse** | Workflows that check out and execute PR head code with base-branch write permissions -- the pattern behind numerous CI poisoning attacks |
+| **Script injection** | run: blocks and env: blocks that route user-controlled context values into shell commands -- both direct interpolation and the indirect env: VAR -> $VAR pattern are detected |
+| **Permission misconfiguration** | Missing permissions: blocks, write-all scopes, secrets: inherit |
+| **Mutable action pins** | uses: references not locked to a full commit SHA -- tags like v3 can be silently overwritten by a supply-chain attacker |
 | **Invalid pinned SHAs** | Pinned SHAs that do not exist in the upstream action repo (typos, deleted commits, fork SHAs) |
-| **Unsafe `workflow_run` chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
+| **Unsafe workflow_run chains** | Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path |
 | **Self-hosted runners** | Non-ephemeral runners that persist state between runs and are not managed by GitHub |
 | **Runner environment drift** | Env var and tool version changes between CI runs that could indicate a compromised or modified runner |
 
-Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and always include a location, description, and evidence field.
+Findings are severity-ranked (CRITICAL -> HIGH -> MEDIUM -> LOW -> INFO) and always include a location, description, and evidence field.
 
 ---
 
@@ -43,26 +43,30 @@ Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and
 Requires Python 3.12+. `pyyaml` is the only external dependency.
 
 **Via pip (recommended):**
-```bash
-pip install pipewatch
+
+```
+pip install pipewatch-cli
 ```
 
 **Directly from GitHub (no clone required):**
-```bash
+
+```
 pip install git+https://github.com/TheVoidThatConsumes/pipewatch.git
 ```
 
-**Copy into your project** — if you prefer to keep pipewatch self-contained inside a repo you're monitoring, download `pipewatch.py` and drop it anywhere in that repo. Install `pyyaml` manually:
-```bash
+**Copy into your project** -- download `pipewatch.py` and drop it anywhere in the repo you want to monitor. Install `pyyaml` manually:
+
+```
 pip install pyyaml
 ```
+
 Then run it as `py pipewatch.py <command>` instead of `pipewatch <command>`.
 
 ---
 
 ## Quick Start
 
-```bash
+```
 # Record the current HEAD as known-good
 pipewatch baseline
 
@@ -78,18 +82,20 @@ pipewatch audit --verify-shas
 ## Commands
 
 ### `baseline`
-Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline — if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
 
-```bash
+Records the current (or a specified) commit as the integrity reference point. Set `PIPEWATCH_HMAC_KEY` to store a signed baseline -- if the file is modified to suppress future findings, the HMAC check will fail and the tool will refuse to proceed.
+
+```
 pipewatch baseline [--repo PATH] [--commit SHA]
 ```
 
 ---
 
 ### `scan`
-Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering — a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
 
-```bash
+Diffs pipeline files and per-step fingerprints against the baseline commit. Detects both file-level changes (unified diff) and step-level tampering -- a step whose `uses`, `run`, `with`, `env`, or `shell` fields change gets flagged even if the surrounding file diff looks innocuous.
+
+```
 pipewatch scan [--repo PATH] [--baseline SHA] [--verbose] [--json]
 ```
 
@@ -98,37 +104,40 @@ Covers GitHub Actions, GitLab CI, and Jenkinsfile stages.
 ---
 
 ### `static`
+
 Static analysis with no baseline required. Audits all GitHub Actions workflow files in `.github/workflows/` for structural misconfigurations.
 
-```bash
+```
 pipewatch static [--repo PATH] [--verbose] [--json]
 ```
 
-Checks: `pull_request_target` misuse · script injection · missing/overpermissioned `permissions:` blocks · `secrets: inherit` · self-hosted runners · unsafe `workflow_run` trigger chains.
+Checks: `pull_request_target` misuse, script injection, missing or overpermissioned `permissions:` blocks, `secrets: inherit`, self-hosted runners, unsafe `workflow_run` trigger chains.
 
 ---
 
 ### `pin-audit`
+
 Flags `uses:` references not pinned to a full 40- or 64-character commit SHA. With `--verify-shas`, makes live GitHub API calls to confirm each pinned SHA actually exists in its upstream repository.
 
-```bash
+```
 pipewatch pin-audit [--repo PATH] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
-Rate limit: 60 requests/hr unauthenticated, 5 000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated — the same `owner/repo@sha` is only verified once regardless of how many steps reference it. Findings are **not** deduplicated: if the same invalid SHA appears across multiple workflow files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible in the report.
+Rate limit: 60 requests/hr unauthenticated, 5000/hr with `--token` or `GITHUB_TOKEN`. API calls are deduplicated -- the same `owner/repo@sha` is only verified once. Findings are **not** deduplicated: if the same invalid SHA appears across multiple files or jobs, each affected step produces its own finding so the full scope of a compromised action is visible.
 
 ---
 
 ### `snapshot`
-Captures the runner environment — environment variables and tool versions — to a JSON file for later comparison.
 
-```bash
+Captures the runner environment -- environment variables and tool versions -- to a JSON file for later comparison.
+
+```
 pipewatch snapshot [--output FILE]
 ```
 
 Tracked tools: `python3`, `python`, `node`, `npm`, `pip`, `pip3`, `git`, `curl`, `wget`, `docker`, `kubectl`, `terraform`, `aws`, `gcloud`, `az`. Volatile per-run variables (`GITHUB_RUN_ID`, `RUNNER_TEMP`, etc.) are excluded to prevent noise on every comparison.
 
-**Credential exclusion** — environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache. Note that a legitimately non-sensitive variable with one of these terms in its name will also be excluded; rename it if you need `env-diff` to track it.
+**Credential exclusion** -- environment variables whose names contain `token`, `secret`, `key`, `password`, `passwd`, `pwd`, `auth`, `credential`, `private`, or `api_key` (case-insensitive) are never written to the snapshot file. This prevents secrets such as `GITHUB_TOKEN` or `PIPEWATCH_HMAC_KEY` from being persisted to disk or uploaded to the Actions cache.
 
 Add the snapshot file to `.gitignore` to prevent it from being accidentally committed:
 
@@ -139,27 +148,30 @@ Add the snapshot file to `.gitignore` to prevent it from being accidentally comm
 ---
 
 ### `env-diff`
-Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions — useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
 
-```bash
+Diffs two runner environment snapshots. Detects new, removed, or changed environment variables and tool versions -- useful for identifying runner poisoning or unexpected environment mutations between runs. If `--current-snapshot` is omitted, captures the live environment.
+
+```
 pipewatch env-diff BASELINE_SNAPSHOT [--current-snapshot FILE] [--repo PATH] [--verbose] [--json]
 ```
 
 ---
 
 ### `audit`
+
 Full audit in one pass: `scan` + `pin-audit` + `static`. Exits non-zero if any findings exist.
 
-```bash
+```
 pipewatch audit [--repo PATH] [--baseline SHA] [--verify-shas] [--token TOKEN] [--verbose] [--json]
 ```
 
 ---
 
 ### `init-runner`
+
 Prints a ready-to-paste GitHub Actions step block that adds runner environment monitoring to any existing job.
 
-```bash
+```
 pipewatch init-runner [--snapshot-path PATH]
 ```
 
@@ -171,10 +183,10 @@ pipewatch init-runner [--snapshot-path PATH]
 |---|---|---|
 | `PW-DIFF-NNN` | Pipeline file added / modified / deleted | HIGH / MEDIUM |
 | `PW-STEP-NNN` | Step fingerprint changed / injected / removed | HIGH / MEDIUM |
-| `PW-PRT-NNN` | `pull_request_target` misuse | HIGH |
+| `PW-PRT-NNN` | pull_request_target misuse | HIGH |
 | `PW-INJ-NNN` | Script injection risk | HIGH |
 | `PW-PERM-NNN` | Permission misconfiguration | HIGH / MEDIUM |
-| `PW-CHAIN-NNN` | Unsafe `workflow_run` chain | HIGH |
+| `PW-CHAIN-NNN` | Unsafe workflow_run chain | HIGH |
 | `PW-PIN-NNN` | Unpinned action reference | MEDIUM |
 | `PW-SHA-NNN` | Pinned SHA not found in upstream repo | HIGH |
 | `PW-RUNNER-NNN` | Self-hosted runner | INFO |
@@ -186,7 +198,7 @@ pipewatch init-runner [--snapshot-path PATH]
 
 All commands accept `--json`:
 
-```json
+```
 {
   "tool": "pipewatch",
   "version": "0.2.0",
@@ -210,7 +222,7 @@ All commands accept `--json`:
 
 Gate on exit code, or filter with `jq`:
 
-```bash
+```
 # fail the build on any HIGH or CRITICAL finding
 pipewatch audit --json | jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0'
 
@@ -224,7 +236,7 @@ pipewatch audit --json | jq -r '.findings[].title'
 
 Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a signed JSON object:
 
-```json
+```
 {
   "commit": "abc123...",
   "timestamp": "2025-01-01T00:00:00+00:00",
@@ -234,24 +246,24 @@ Set `PIPEWATCH_HMAC_KEY` before running `baseline`. The baseline is stored as a
 
 The HMAC is computed over both the commit SHA **and** the timestamp, bound together. This protects against two distinct attacks:
 
-- **Tampering** — an attacker who modifies the `commit` field to point to an older known-good commit cannot produce a valid HMAC without the key.
-- **Replay** — an attacker who reverts the baseline file to a previously-valid signed snapshot (to suppress findings introduced after that point) is also blocked, because the timestamp is part of the signed payload and the stored timestamp would no longer match the signature of any rewritten content.
+- **Tampering** -- an attacker who modifies the `commit` field cannot produce a valid HMAC without the key.
+- **Replay** -- an attacker who reverts the baseline file to a previously-valid signed snapshot is also blocked, because the timestamp is part of the signed payload.
 
 On `scan` or `audit`, the HMAC is verified before the baseline commit is trusted. Any verification failure causes an immediate exit with an error.
 
-**Format-downgrade protection** — if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format (a raw commit SHA rather than signed JSON), the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
+**Format-downgrade protection** -- if `PIPEWATCH_HMAC_KEY` is set and the baseline file is in plain-text format, the tool refuses to proceed. An attacker cannot bypass signing by overwriting the file with an unsigned commit SHA. If you set `PIPEWATCH_HMAC_KEY` for the first time on a repo that already has an unsigned baseline, re-run `pipewatch baseline` to generate a signed one before your next scan.
 
-Store the key in a CI secret (`PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}`).
+Store the key in a CI secret.
 
 ---
 
 ## Pipeline Integration
 
-```yaml
+```
 - name: pipewatch audit
   env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}
+    GITHUB_TOKEN: (your GITHUB_TOKEN secret)
+    PIPEWATCH_HMAC_KEY: (your PIPEWATCH_HMAC_KEY secret)
   run: |
     pipewatch audit --verify-shas --json | tee pw-report.json
     jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0' pw-report.json
@@ -263,13 +275,13 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 ## Design Decisions
 
-**HMAC-signed baselines** — tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC — not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
+**HMAC-signed baselines** -- tamper-evident storage for the known-good commit reference. The HMAC covers both the commit SHA and the timestamp, so an attacker who can write to the repo but wants to suppress findings would need to forge the HMAC -- not just overwrite the file or revert it to an older signed state. Attempting to downgrade a signed baseline to unsigned plain text is also refused when `PIPEWATCH_HMAC_KEY` is set.
 
-**Volatile variable exclusion** — `snapshot` strips run-specific GitHub variables so that `env-diff` doesn't generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials (containing `token`, `secret`, `key`, `password`, etc.) are also excluded so secrets are never written to the snapshot file or the Actions cache.
+**Volatile variable exclusion** -- `snapshot` strips run-specific GitHub variables so that `env-diff` does not generate noise on every comparison. Only structurally stable variables that could indicate environment manipulation are tracked. Variables whose names suggest credentials are also excluded so secrets are never written to the snapshot file or the Actions cache.
 
-**Conservative SHA verification** — `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
+**Conservative SHA verification** -- `--verify-shas` treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
 
-**Stdlib-first** — `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
+**Stdlib-first** -- `pyyaml` is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
 
 ---
 
@@ -277,12 +289,12 @@ Use `init-runner` to add runner environment monitoring alongside the audit step.
 
 | Platform | Coverage |
 |---|---|
-| GitHub Actions (`.github/workflows/*.yml`) | Full — file diff, step fingerprinting, static analysis, pin audit |
-| GitLab CI (`.gitlab-ci.yml`) | File diff + `before_script` / `script` / `after_script` fingerprinting |
-| Jenkins (`Jenkinsfile`) | File diff + best-effort stage / `sh` / `bat` fingerprinting (regex-based — not a Groovy parser) |
+| GitHub Actions (.github/workflows/*.yml) | Full -- file diff, step fingerprinting, static analysis, pin audit. Step evidence includes uses, run first line, or step name. |
+| GitLab CI (.gitlab-ci.yml) | File diff + before_script / script / after_script fingerprinting. Step evidence shows the first command in the changed block. |
+| Jenkins (Jenkinsfile) | File diff + best-effort stage / sh / bat fingerprinting (regex-based, not a Groovy parser). Step evidence shows the first sh/bat command where extractable; falls back to stage name. |
 
 ---
 
 ## License
 
-GPLv2. See [LICENSE](LICENSE).
+Copyright (c) 2026 David Obi. Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). See [LICENSE](LICENSE).

{pipewatch_cli-0.3.0 → pipewatch_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pipewatch-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Integrity monitoring and static analysis for CI/CD pipelines"
 readme = "README.md"
 license = "CC-BY-4.0"