Skip to content

Commit 6a62b75

Browse files
jdaltonjdalton
committed
feat: add sfw shims and checksum validation
1 parent ba6de6c commit 6a62b75

5 files changed

Lines changed: 379 additions & 115 deletions

File tree

‎README.md‎

Lines changed: 117 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Socket is a security control, so the action that installs it should be pinned, t
2121

2222
Downloads and installs [Socket Firewall: Free](https://github.com/SocketDev/sfw-free) edition in your GitHub Action job, making it available to use in subsequent steps.
2323

24+
By default the action creates shims for all supported package managers. This means you do **not** need to prefix your commands with `sfw` — just run your package manager like normal and it will be automatically routed through Socket Firewall.
25+
2426
#### Most secure: pin to a commit SHA
2527

2628
```yaml
@@ -37,14 +39,17 @@ jobs:
3739
with:
3840
mode: firewall-free
3941

42+
# these commands are automatically intercepted by sfw
43+
# no need to prefix with "sfw" anymore!
44+
4045
# javascript / typescript
41-
- run: sfw npm install # or yarn, pnpm
46+
- run: npm install # or pnpm, yarn
4247

4348
# rust
44-
- run: sfw cargo fetch
49+
- run: cargo fetch
4550

4651
# python
47-
- run: sfw pip install -r requirements.txt
52+
- run: pip install -r requirements.txt
4853
```
4954
5055
#### Slightly less secure: pin to an immutable version tag
@@ -64,13 +69,27 @@ jobs:
6469
mode: firewall-free
6570

6671
# javascript / typescript
67-
- run: sfw npm install # or yarn, pnpm
72+
- run: npm install # or pnpm, yarn
6873

6974
# rust
70-
- run: sfw cargo fetch
75+
- run: cargo fetch
7176

7277
# python
73-
- run: sfw pip install -r requirements.txt
78+
- run: pip install -r requirements.txt
79+
```
80+
81+
#### Disable shims (explicit sfw prefix)
82+
83+
If you prefer to keep using the `sfw` prefix explicitly, you can turn off automatic shims:
84+
85+
```yaml
86+
- uses: SocketDev/action@v1.3.1
87+
with:
88+
mode: firewall-free
89+
shims: 'false'
90+
91+
# now you need to explicitly prefix commands with sfw
92+
- run: sfw npm install
7493
```
7594

7695
#### Dependabot config
@@ -92,23 +111,26 @@ Add a cooldown period if you want an extra buffer before newly published action
92111

93112
#### Inputs
94113

95-
| Input | Description | Required | Default |
96-
| ------------------ | ---------------------------------------------------------------- | -------- | -------------------- |
97-
| `firewall-version` | Specify the firewall version number | No | `latest` |
98-
| `job-summary` | Create a [job summary][job-summary] (`all`, `errors`, or `none`) | No | `all` |
99-
| `use-cache` | Cache the Socket binaries (force download if `false`) | No | `true` |
100-
| `github-token` | GitHub API Token used for downloading binaries | No | `${{ github.token}}` |
114+
| Input | Description | Required | Default |
115+
| --------------------- | ---------------------------------------------------------------- | -------- | -------------------- |
116+
| `firewall-version` | Specify the firewall version number | No | `latest` |
117+
| `github-token` | GitHub API Token used for downloading binaries | No | `${{ github.token}}` |
118+
| `job-summary` | Create a [job summary][job-summary] (`all`, `errors`, or `none`) | No | `all` |
119+
| `shims` | Create shims so package managers are routed through sfw | No | `true` |
120+
| `use-cache` | Cache the Socket binaries (force download if `false`) | No | `true` |
101121

102122
#### Outputs
103123

104124
| Output | Description |
105125
| ---------------------- | ------------------------------------------ |
106-
| `firewall-path-report` | Path to the generated firewall report JSON |
107126
| `firewall-path-binary` | Path to the installed binary |
127+
| `firewall-path-report` | Path to the generated firewall report JSON |
108128

109129
### Socket Firewall: Enterprise
110130

111-
Downloads and installs [Socket Firewall: Enterprise](https://github.com/SocketDev/firewall-release) edition in your GitHub Action job, making it available to use in subsequent steps as a wrapper.
131+
Downloads and installs [Socket Firewall: Enterprise](https://github.com/SocketDev/firewall-release) edition in your GitHub Action job, making it available to use in subsequent steps.
132+
133+
Like the free edition, the action creates shims by default so you can use your package manager commands normally without the `sfw` prefix.
112134

113135
#### Most secure: pin to a commit SHA
114136

@@ -127,14 +149,17 @@ jobs:
127149
mode: firewall-enterprise
128150
socket-token: ${{ secrets.SOCKET_API_KEY }}
129151
152+
# these commands are automatically intercepted by sfw
153+
# no need to prefix with "sfw" anymore!
154+
130155
# javascript / typescript
131-
- run: sfw npm install # or yarn, pnpm
156+
- run: npm install # or pnpm, yarn
132157
133158
# rust
134-
- run: sfw cargo fetch
159+
- run: cargo fetch
135160
136161
# python
137-
- run: sfw pip install -r requirements.txt
162+
- run: pip install -r requirements.txt
138163
```
139164

140165
#### Slightly less secure: pin to an immutable version tag
@@ -155,13 +180,13 @@ jobs:
155180
socket-token: ${{ secrets.SOCKET_API_KEY }}
156181
157182
# javascript / typescript
158-
- run: sfw npm install # or yarn, pnpm
183+
- run: npm install # or pnpm, yarn
159184
160185
# rust
161-
- run: sfw cargo fetch
186+
- run: cargo fetch
162187
163188
# python
164-
- run: sfw pip install -r requirements.txt
189+
- run: pip install -r requirements.txt
165190
```
166191

167192
#### Dependabot config
@@ -183,19 +208,83 @@ Add a cooldown period if you want an extra buffer before newly published action
183208

184209
#### Inputs
185210

186-
| Input | Description | Required | Default |
187-
| ------------------ | ---------------------------------------------------------------- | -------- | -------------------- |
188-
| `firewall-version` | Specify the firewall version number | No | `latest` |
189-
| `job-summary` | Create a [job summary][job-summary] (`all`, `errors`, or `none`) | No | `all` |
190-
| `use-cache` | Cache the Socket binaries (force download if `false`) | No | `true` |
191-
| `github-token` | GitHub API Token used for downloading binaries | No | `${{ github.token}}` |
192-
| `socket-token` | Socket API Token | **YES** | `-` |
211+
| Input | Description | Required | Default |
212+
| --------------------- | ---------------------------------------------------------------- | -------- | -------------------- |
213+
| `firewall-version` | Specify the firewall version number | No | `latest` |
214+
| `github-token` | GitHub API Token used for downloading binaries | No | `${{ github.token}}` |
215+
| `job-summary` | Create a [job summary][job-summary] (`all`, `errors`, or `none`) | No | `all` |
216+
| `shims` | Create shims so package managers are routed through sfw | No | `true` |
217+
| `socket-token` | Socket API Token | **YES** | `-` |
218+
| `use-cache` | Cache the Socket binaries (force download if `false`) | No | `true` |
193219

194220
#### Outputs
195221

196222
| Output | Description |
197223
| ---------------------- | ------------------------------------------ |
198-
| `firewall-path-report` | Path to the generated firewall report JSON |
199224
| `firewall-path-binary` | Path to the installed binary |
225+
| `firewall-path-report` | Path to the generated firewall report JSON |
226+
227+
### Supported Ecosystems
228+
229+
When `shims` is `true` (the default), the action creates shims so package manager commands are automatically routed through sfw. The supported ecosystems depend on the edition.
230+
231+
#### Free + Enterprise
232+
233+
Available in both [sfw-free][sfw-free-ecosystems] and [sfw-enterprise][sfw-enterprise-ecosystems]:
234+
235+
| Ecosystem | Package Manager |
236+
| ------------------- | --------------- |
237+
| JavaScript/Node | `npm` |
238+
| JavaScript/Node | `pnpm` |
239+
| JavaScript/Node | `yarn` |
240+
| Python | `pip` |
241+
| Python | `pip3` |
242+
| Python | `uv` |
243+
| Rust | `cargo` |
244+
245+
#### Enterprise only
246+
247+
Additional ecosystems available with [sfw-enterprise][sfw-enterprise-ecosystems]:
248+
249+
| Ecosystem | Package Manager | Note |
250+
| ------------------- | --------------- | ------------ |
251+
| .NET | `nuget` | |
252+
| Go | `go` | Linux only |
253+
| Ruby | `bundler` | |
254+
| Ruby | `gem` | |
255+
256+
[sfw-free-ecosystems]: https://github.com/SocketDev/sfw-free?tab=readme-ov-file#supported-package-managers
257+
[sfw-enterprise-ecosystems]: https://github.com/SocketDev/firewall-release/wiki#support-matrix
258+
259+
### Bypassing shims for publishing
260+
261+
When shims are enabled the action exports `SFW_SHIM_DIR` as an environment variable pointing to the shim directory. If you need to bypass sfw for a specific step (e.g. `npm publish`), you can temporarily disable the shims by renaming them and restore them afterwards:
262+
263+
```yaml
264+
# disable shims before publishing
265+
- name: Disable sfw shims
266+
run: |
267+
if [ -n "$SFW_SHIM_DIR" ] && [ -d "$SFW_SHIM_DIR" ]; then
268+
for SHIM in "$SFW_SHIM_DIR"/*; do
269+
[ -f "$SHIM" ] && mv "$SHIM" "${SHIM}.disabled"
270+
done
271+
fi
272+
273+
- run: npm publish
274+
275+
# re-enable shims after publishing
276+
- name: Restore sfw shims
277+
if: always()
278+
run: |
279+
if [ -n "$SFW_SHIM_DIR" ] && [ -d "$SFW_SHIM_DIR" ]; then
280+
for SHIM in "$SFW_SHIM_DIR"/*.disabled; do
281+
[ -f "$SHIM" ] && mv "$SHIM" "${SHIM%.disabled}"
282+
done
283+
fi
284+
```
285+
286+
### Checksum Validation
287+
288+
The action validates the SHA256 checksum of the downloaded firewall binary against the checksum file published alongside each release. This ensures the binary was not tampered with during download.
200289

201290
[job-summary]: https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries

‎action.yml‎

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,46 +9,53 @@ branding:
99
color: purple
1010

1111
inputs:
12-
mode:
13-
description: Operation mode firewall, patch, or cli
14-
required: true
12+
firewall-version:
13+
description: Specify the firewall version number
14+
default: latest
1515

1616
github-token:
1717
description: GitHub API Token used for downloading binaries
1818
required: true
1919
default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
2020

21-
socket-token:
22-
description: The Socket API Token
23-
24-
use-cache:
25-
description: Cache the Socket binaries
26-
default: 'true'
27-
2821
job-summary:
2922
description: Create a job summary
3023
default: all
3124

32-
firewall-version:
33-
description: Specify the firewall version number
34-
default: latest
35-
36-
patch-version:
37-
description: Specify the socket-patch version number
38-
default: latest
25+
mode:
26+
description: Operation mode firewall, patch, or cli
27+
required: true
3928

40-
patch-ecosystems:
41-
description: Comma-separated list of ecosystems to patch (npm, pypi, cargo)
29+
patch-cwd:
30+
description: Working directory for socket-patch apply
4231
default: ''
4332

4433
patch-dry-run:
4534
description: Verify patches without modifying files
4635
default: 'false'
4736

48-
patch-cwd:
49-
description: Working directory for socket-patch apply
37+
patch-ecosystems:
38+
description: Comma-separated list of ecosystems to patch (npm, pypi, cargo)
5039
default: ''
5140

41+
patch-version:
42+
description: Specify the socket-patch version number
43+
default: latest
44+
45+
shims:
46+
description: Create shims so package manager commands are automatically routed through sfw
47+
default: 'true'
48+
49+
socket-token:
50+
description: The Socket API Token
51+
52+
socket_api_key:
53+
description: Socket API key mapped to the SOCKET_API_KEY environment variable
54+
55+
use-cache:
56+
description: Cache the Socket binaries
57+
default: 'true'
58+
5259
outputs:
5360
firewall-path-report:
5461
description: Path to the generated firewall report JSON

‎dist/main.js‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/main.js‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,24 +18,25 @@ process.on('unhandledRejection', errorHandler)
1818
process.on('uncaughtException', errorHandler)
1919

2020
const inputs = {
21+
jobSummary: core.getInput('job-summary', { required: false }).toLowerCase(),
2122
mode: core.getInput('mode', { required: true }).toLowerCase(),
23+
patchCwd: core.getInput('patch-cwd'),
24+
patchDryRun: core.getBooleanInput('patch-dry-run'),
25+
patchEcosystems: core.getInput('patch-ecosystems'),
26+
shims: core.getBooleanInput('shims'),
2227
tokenGithub: core.getInput('github-token', { required: true }),
2328
tokenSocket: core.getInput('socket-token'),
24-
versionFirewall: core.getInput('firewall-version'),
25-
versionPatch: core.getInput('patch-version'),
26-
patchEcosystems: core.getInput('patch-ecosystems'),
27-
patchDryRun: core.getBooleanInput('patch-dry-run'),
28-
patchCwd: core.getInput('patch-cwd'),
2929
useCache: core.getBooleanInput('use-cache'),
30-
jobSummary: core.getInput('job-summary', { required: false }).toLowerCase()
30+
versionFirewall: core.getInput('firewall-version'),
31+
versionPatch: core.getInput('patch-version')
3132
}
3233

3334
// backward compatibility
3435
if (inputs.jobSummary === 'true') inputs.jobSummary = 'all'
3536
if (inputs.jobSummary === 'false') inputs.jobSummary = 'none'
3637

3738
if (inputs.tokenSocket) {
38-
// setup socket token as a secret env
39+
// setup socket token as a secret env so sfw can use it
3940
core.exportVariable('SOCKET_API_KEY', inputs.tokenSocket)
4041
core.exportVariable('SOCKET_API_TOKEN', inputs.tokenSocket)
4142
core.setSecret(inputs.tokenSocket)

0 commit comments

Comments
 (0)