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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,3 @@
1
- Copyright (c) 2026 David Obi
2
1
 
3
2
  pipewatch-cli is licensed under the Creative Commons Attribution 4.0
4
3
  International License. To view a copy of this license, see below or
@@ -0,0 +1,228 @@
1
+ Metadata-Version: 2.4
2
+ Name: pipewatch-cli
3
+ Version: 0.4.0
4
+ Summary: Integrity monitoring and static analysis for CI/CD pipelines
5
+ License-Expression: CC-BY-4.0
6
+ Requires-Python: >=3.12
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: pyyaml>=6.0
10
+ Dynamic: license-file
11
+
12
+ # pipewatch
13
+
14
+ **Integrity monitoring and static analysis for software supply chains.**
15
+
16
+ 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.
17
+
18
+ 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.
19
+
20
+ What It Detects
21
+ Check What it catches
22
+ Baseline diff Pipeline files modified, added, or deleted since a known-good commit
23
+ Step fingerprinting Individual steps injected, removed, or silently modified between commits
24
+ 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
25
+ 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
26
+ Permission misconfiguration Missing permissions: blocks, write-all scopes, secrets: inherit
27
+ Mutable action pins uses: references not locked to a full commit SHA — tags like v3 can be silently overwritten by a supply-chain attacker
28
+ Invalid pinned SHAs Pinned SHAs that do not exist in the upstream action repo (typos, deleted commits, fork SHAs)
29
+ Unsafe workflow_run chains Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path
30
+ Self-hosted runners Non-ephemeral runners that persist state between runs and are not managed by GitHub
31
+ Runner environment drift Env var and tool version changes between CI runs that could indicate a compromised or modified runner
32
+
33
+ Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and always include a location, description, and evidence field.
34
+
35
+ Installation
36
+
37
+ Requires Python 3.12+. pyyaml is the only external dependency.
38
+
39
+ Via pip (recommended):
40
+
41
+ bash
42
+ pip install pipewatch-cli
43
+
44
+ Directly from GitHub (no clone required):
45
+
46
+ bash
47
+ pip install git+https://github.com/TheVoidThatConsumes/pipewatch.git
48
+
49
+ 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:
50
+
51
+ bash
52
+ pip install pyyaml
53
+
54
+ Then run it as py pipewatch.py <command> instead of pipewatch <command>.
55
+
56
+ Quick Start
57
+ bash
58
+ # Record the current HEAD as known-good
59
+ pipewatch baseline
60
+
61
+ # Scan for changes and misconfigurations
62
+ pipewatch scan
63
+
64
+ # Full audit in one pass (scan + pin-audit + static)
65
+ pipewatch audit --verify-shas
66
+ Commands
67
+ baseline
68
+
69
+ 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.
70
+
71
+ bash
72
+ pipewatch baseline [--repo PATH] [--commit SHA]
73
+ scan
74
+
75
+ 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.
76
+
77
+ bash
78
+ pipewatch scan [--repo PATH] [--baseline SHA] [--verbose] [--json]
79
+
80
+ Covers GitHub Actions, GitLab CI, and Jenkinsfile stages.
81
+
82
+ static
83
+
84
+ Static analysis with no baseline required. Audits all GitHub Actions workflow files in .github/workflows/ for structural misconfigurations.
85
+
86
+ bash
87
+ pipewatch static [--repo PATH] [--verbose] [--json]
88
+
89
+ Checks: pull_request_target misuse · script injection · missing/overpermissioned permissions: blocks · secrets: inherit · self-hosted runners · unsafe workflow_run trigger chains.
90
+
91
+ pin-audit
92
+
93
+ 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.
94
+
95
+ bash
96
+ pipewatch pin-audit [--repo PATH] [--verify-shas] [--token TOKEN] [--verbose] [--json]
97
+
98
+ 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.
99
+
100
+ snapshot
101
+
102
+ Captures the runner environment — environment variables and tool versions — to a JSON file for later comparison.
103
+
104
+ bash
105
+ pipewatch snapshot [--output FILE]
106
+
107
+ 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.
108
+
109
+ 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.
110
+
111
+ Add the snapshot file to .gitignore to prevent it from being accidentally committed:
112
+
113
+ .pipewatch_env_snapshot.json
114
+ env-diff
115
+
116
+ 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.
117
+
118
+ bash
119
+ pipewatch env-diff BASELINE_SNAPSHOT [--current-snapshot FILE] [--repo PATH] [--verbose] [--json]
120
+ audit
121
+
122
+ Full audit in one pass: scan + pin-audit + static. Exits non-zero if any findings exist.
123
+
124
+ bash
125
+ pipewatch audit [--repo PATH] [--baseline SHA] [--verify-shas] [--token TOKEN] [--verbose] [--json]
126
+ init-runner
127
+
128
+ Prints a ready-to-paste GitHub Actions step block that adds runner environment monitoring to any existing job.
129
+
130
+ bash
131
+ pipewatch init-runner [--snapshot-path PATH]
132
+ Finding IDs
133
+ Prefix Category Default Severity
134
+ PW-DIFF-NNN Pipeline file added / modified / deleted HIGH / MEDIUM
135
+ PW-STEP-NNN Step fingerprint changed / injected / removed HIGH / MEDIUM
136
+ PW-PRT-NNN pull_request_target misuse HIGH
137
+ PW-INJ-NNN Script injection risk HIGH
138
+ PW-PERM-NNN Permission misconfiguration HIGH / MEDIUM
139
+ PW-CHAIN-NNN Unsafe workflow_run chain HIGH
140
+ PW-PIN-NNN Unpinned action reference MEDIUM
141
+ PW-SHA-NNN Pinned SHA not found in upstream repo HIGH
142
+ PW-RUNNER-NNN Self-hosted runner INFO
143
+ PW-ENV-NNN Runner environment drift MEDIUM / LOW
144
+ JSON Output
145
+
146
+ All commands accept --json:
147
+
148
+ json
149
+ {
150
+ "tool": "pipewatch",
151
+ "version": "0.2.0",
152
+ "timestamp": "2025-01-01T00:00:00+00:00",
153
+ "repo": "/path/to/repo",
154
+ "baseline_commit": "abc123...",
155
+ "findings": [
156
+ {
157
+ "id": "PW-INJ-001",
158
+ "severity": "HIGH",
159
+ "category": "script_injection",
160
+ "title": "Script injection risk: .github/workflows/ci.yml::build::step[2]",
161
+ "description": "A run: block interpolates a user-controlled context value...",
162
+ "location": ".github/workflows/ci.yml::build::step[2]",
163
+ "evidence": "dangerous expressions found: ['github.event.pull_request.title']"
164
+ }
165
+ ],
166
+ "summary": { "total": 1, "CRITICAL": 0, "HIGH": 1, "MEDIUM": 0, "LOW": 0, "INFO": 0 }
167
+ }
168
+
169
+ Gate on exit code, or filter with jq:
170
+
171
+ bash
172
+ # fail the build on any HIGH or CRITICAL finding
173
+ pipewatch audit --json | jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0'
174
+
175
+ # list all finding titles
176
+ pipewatch audit --json | jq -r '.findings[].title'
177
+ Tamper-Evident Baselines
178
+
179
+ Set PIPEWATCH_HMAC_KEY before running baseline. The baseline is stored as a signed JSON object:
180
+
181
+ json
182
+ {
183
+ "commit": "abc123...",
184
+ "timestamp": "2025-01-01T00:00:00+00:00",
185
+ "hmac": "<sha256-hmac-of-commit-and-timestamp>"
186
+ }
187
+
188
+ The HMAC is computed over both the commit SHA and the timestamp, bound together. This protects against two distinct attacks:
189
+
190
+ Tampering — an attacker who modifies the commit field to point to an older known-good commit cannot produce a valid HMAC without the key.
191
+ 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.
192
+
193
+ On scan or audit, the HMAC is verified before the baseline commit is trusted. Any verification failure causes an immediate exit with an error.
194
+
195
+ 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.
196
+
197
+ Store the key in a CI secret (PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}).
198
+
199
+ Pipeline Integration
200
+ yaml
201
+ - name: pipewatch audit
202
+ env:
203
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
204
+ PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}
205
+ run: |
206
+ pipewatch audit --verify-shas --json | tee pw-report.json
207
+ jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0' pw-report.json
208
+
209
+ Use init-runner to add runner environment monitoring alongside the audit step.
210
+
211
+ Design Decisions
212
+
213
+ 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.
214
+
215
+ 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.
216
+
217
+ Conservative SHA verification — --verify-shas treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
218
+
219
+ Stdlib-first — pyyaml is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
220
+
221
+ Platform Support
222
+ Platform Coverage
223
+ GitHub Actions (.github/workflows/*.yml) Full — file diff, step fingerprinting, static analysis, pin audit
224
+ GitLab CI (.gitlab-ci.yml) File diff + before_script / script / after_script fingerprinting
225
+ Jenkins (Jenkinsfile) File diff + best-effort stage / sh / bat fingerprinting (regex-based — not a Groovy parser)
226
+ License
227
+
228
+ Licensed under CC BY 4.0. See LICENSE.
@@ -0,0 +1,217 @@
1
+ # pipewatch
2
+
3
+ **Integrity monitoring and static analysis for software supply chains.**
4
+
5
+ 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.
6
+
7
+ 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.
8
+
9
+ What It Detects
10
+ Check What it catches
11
+ Baseline diff Pipeline files modified, added, or deleted since a known-good commit
12
+ Step fingerprinting Individual steps injected, removed, or silently modified between commits
13
+ 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
14
+ 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
15
+ Permission misconfiguration Missing permissions: blocks, write-all scopes, secrets: inherit
16
+ Mutable action pins uses: references not locked to a full commit SHA — tags like v3 can be silently overwritten by a supply-chain attacker
17
+ Invalid pinned SHAs Pinned SHAs that do not exist in the upstream action repo (typos, deleted commits, fork SHAs)
18
+ Unsafe workflow_run chains Write-permissioned workflows triggered indirectly by external pull requests or issues, creating a privilege escalation path
19
+ Self-hosted runners Non-ephemeral runners that persist state between runs and are not managed by GitHub
20
+ Runner environment drift Env var and tool version changes between CI runs that could indicate a compromised or modified runner
21
+
22
+ Findings are severity-ranked (CRITICAL → HIGH → MEDIUM → LOW → INFO) and always include a location, description, and evidence field.
23
+
24
+ Installation
25
+
26
+ Requires Python 3.12+. pyyaml is the only external dependency.
27
+
28
+ Via pip (recommended):
29
+
30
+ bash
31
+ pip install pipewatch-cli
32
+
33
+ Directly from GitHub (no clone required):
34
+
35
+ bash
36
+ pip install git+https://github.com/TheVoidThatConsumes/pipewatch.git
37
+
38
+ 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:
39
+
40
+ bash
41
+ pip install pyyaml
42
+
43
+ Then run it as py pipewatch.py <command> instead of pipewatch <command>.
44
+
45
+ Quick Start
46
+ bash
47
+ # Record the current HEAD as known-good
48
+ pipewatch baseline
49
+
50
+ # Scan for changes and misconfigurations
51
+ pipewatch scan
52
+
53
+ # Full audit in one pass (scan + pin-audit + static)
54
+ pipewatch audit --verify-shas
55
+ Commands
56
+ baseline
57
+
58
+ 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.
59
+
60
+ bash
61
+ pipewatch baseline [--repo PATH] [--commit SHA]
62
+ scan
63
+
64
+ 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.
65
+
66
+ bash
67
+ pipewatch scan [--repo PATH] [--baseline SHA] [--verbose] [--json]
68
+
69
+ Covers GitHub Actions, GitLab CI, and Jenkinsfile stages.
70
+
71
+ static
72
+
73
+ Static analysis with no baseline required. Audits all GitHub Actions workflow files in .github/workflows/ for structural misconfigurations.
74
+
75
+ bash
76
+ pipewatch static [--repo PATH] [--verbose] [--json]
77
+
78
+ Checks: pull_request_target misuse · script injection · missing/overpermissioned permissions: blocks · secrets: inherit · self-hosted runners · unsafe workflow_run trigger chains.
79
+
80
+ pin-audit
81
+
82
+ 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.
83
+
84
+ bash
85
+ pipewatch pin-audit [--repo PATH] [--verify-shas] [--token TOKEN] [--verbose] [--json]
86
+
87
+ 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.
88
+
89
+ snapshot
90
+
91
+ Captures the runner environment — environment variables and tool versions — to a JSON file for later comparison.
92
+
93
+ bash
94
+ pipewatch snapshot [--output FILE]
95
+
96
+ 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.
97
+
98
+ 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.
99
+
100
+ Add the snapshot file to .gitignore to prevent it from being accidentally committed:
101
+
102
+ .pipewatch_env_snapshot.json
103
+ env-diff
104
+
105
+ 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.
106
+
107
+ bash
108
+ pipewatch env-diff BASELINE_SNAPSHOT [--current-snapshot FILE] [--repo PATH] [--verbose] [--json]
109
+ audit
110
+
111
+ Full audit in one pass: scan + pin-audit + static. Exits non-zero if any findings exist.
112
+
113
+ bash
114
+ pipewatch audit [--repo PATH] [--baseline SHA] [--verify-shas] [--token TOKEN] [--verbose] [--json]
115
+ init-runner
116
+
117
+ Prints a ready-to-paste GitHub Actions step block that adds runner environment monitoring to any existing job.
118
+
119
+ bash
120
+ pipewatch init-runner [--snapshot-path PATH]
121
+ Finding IDs
122
+ Prefix Category Default Severity
123
+ PW-DIFF-NNN Pipeline file added / modified / deleted HIGH / MEDIUM
124
+ PW-STEP-NNN Step fingerprint changed / injected / removed HIGH / MEDIUM
125
+ PW-PRT-NNN pull_request_target misuse HIGH
126
+ PW-INJ-NNN Script injection risk HIGH
127
+ PW-PERM-NNN Permission misconfiguration HIGH / MEDIUM
128
+ PW-CHAIN-NNN Unsafe workflow_run chain HIGH
129
+ PW-PIN-NNN Unpinned action reference MEDIUM
130
+ PW-SHA-NNN Pinned SHA not found in upstream repo HIGH
131
+ PW-RUNNER-NNN Self-hosted runner INFO
132
+ PW-ENV-NNN Runner environment drift MEDIUM / LOW
133
+ JSON Output
134
+
135
+ All commands accept --json:
136
+
137
+ json
138
+ {
139
+ "tool": "pipewatch",
140
+ "version": "0.2.0",
141
+ "timestamp": "2025-01-01T00:00:00+00:00",
142
+ "repo": "/path/to/repo",
143
+ "baseline_commit": "abc123...",
144
+ "findings": [
145
+ {
146
+ "id": "PW-INJ-001",
147
+ "severity": "HIGH",
148
+ "category": "script_injection",
149
+ "title": "Script injection risk: .github/workflows/ci.yml::build::step[2]",
150
+ "description": "A run: block interpolates a user-controlled context value...",
151
+ "location": ".github/workflows/ci.yml::build::step[2]",
152
+ "evidence": "dangerous expressions found: ['github.event.pull_request.title']"
153
+ }
154
+ ],
155
+ "summary": { "total": 1, "CRITICAL": 0, "HIGH": 1, "MEDIUM": 0, "LOW": 0, "INFO": 0 }
156
+ }
157
+
158
+ Gate on exit code, or filter with jq:
159
+
160
+ bash
161
+ # fail the build on any HIGH or CRITICAL finding
162
+ pipewatch audit --json | jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0'
163
+
164
+ # list all finding titles
165
+ pipewatch audit --json | jq -r '.findings[].title'
166
+ Tamper-Evident Baselines
167
+
168
+ Set PIPEWATCH_HMAC_KEY before running baseline. The baseline is stored as a signed JSON object:
169
+
170
+ json
171
+ {
172
+ "commit": "abc123...",
173
+ "timestamp": "2025-01-01T00:00:00+00:00",
174
+ "hmac": "<sha256-hmac-of-commit-and-timestamp>"
175
+ }
176
+
177
+ The HMAC is computed over both the commit SHA and the timestamp, bound together. This protects against two distinct attacks:
178
+
179
+ Tampering — an attacker who modifies the commit field to point to an older known-good commit cannot produce a valid HMAC without the key.
180
+ 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.
181
+
182
+ On scan or audit, the HMAC is verified before the baseline commit is trusted. Any verification failure causes an immediate exit with an error.
183
+
184
+ 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.
185
+
186
+ Store the key in a CI secret (PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}).
187
+
188
+ Pipeline Integration
189
+ yaml
190
+ - name: pipewatch audit
191
+ env:
192
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
193
+ PIPEWATCH_HMAC_KEY: ${{ secrets.PIPEWATCH_HMAC_KEY }}
194
+ run: |
195
+ pipewatch audit --verify-shas --json | tee pw-report.json
196
+ jq -e '.summary.HIGH == 0 and .summary.CRITICAL == 0' pw-report.json
197
+
198
+ Use init-runner to add runner environment monitoring alongside the audit step.
199
+
200
+ Design Decisions
201
+
202
+ 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.
203
+
204
+ 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.
205
+
206
+ Conservative SHA verification — --verify-shas treats network failures as non-findings. A flaky connection or GitHub API outage should not produce spurious HIGH alerts.
207
+
208
+ Stdlib-first — pyyaml is the only dependency. The tool audits supply-chain risk; its own footprint is minimal by design.
209
+
210
+ Platform Support
211
+ Platform Coverage
212
+ GitHub Actions (.github/workflows/*.yml) Full — file diff, step fingerprinting, static analysis, pin audit
213
+ GitLab CI (.gitlab-ci.yml) File diff + before_script / script / after_script fingerprinting
214
+ Jenkins (Jenkinsfile) File diff + best-effort stage / sh / bat fingerprinting (regex-based — not a Groovy parser)
215
+ License
216
+
217
+ Licensed under CC BY 4.0. See LICENSE.