Skip to content

Commit b68e7f8

Browse files
lelialelia
authored
docs: cleanup docs guidance, additional workflow hardening (#60)
* docs: cleanup versioning guidance, pinning examples, container scanning status Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * ci: make pyproject.toml the canonical release version source Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * ci: harden dependabot review workflow Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * chore(ci): workflows with zizmor remediations Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * docs: add explicit Trivy versioning guidance for interim use Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * docs: fix markdown formatting, tweak phrasing Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> * docs: tweak reference link, use markdown section anchor Signed-off-by: lelia <2418071+lelia@users.noreply.github.com> --------- Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>
1 parent 5aa26ce commit b68e7f8

17 files changed

+520
-296
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@
2121

2222
<!-- Only fill this out if this PR is cutting a new release (e.g. v2.1.0). -->
2323

24+
- [ ] `pyproject.toml` `version:` field updated to new version
25+
- [ ] `python3 scripts/sync_release_version.py --write` run after updating `pyproject.toml`
2426
- [ ] `socket_basics/version.py` updated to new version
25-
- [ ] `pyproject.toml` `version:` field updated to match
26-
- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>` *(auto-updated by `publish-docker.yml`
27+
- [ ] `socket_basics/__init__.py` updated to the same version
28+
- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>`
2729
- [ ] `CHANGELOG.md` `[Unreleased]` section reviewed
28-
29-
> See [docs/releasing.md](../docs/releasing.md) for the full release process.

‎.github/dependabot.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ updates:
99
directory: "/"
1010
schedule:
1111
interval: "weekly"
12+
open-pull-requests-limit: 5
13+
allow:
14+
- dependency-name: "python"
15+
- dependency-name: "ghcr.io/astral-sh/uv"
16+
- dependency-name: "trufflesecurity/trufflehog"
17+
- dependency-name: "aquasec/trivy"
1218
labels:
1319
- "dependencies"
1420
- "docker"
@@ -23,6 +29,13 @@ updates:
2329
directory: "/app_tests"
2430
schedule:
2531
interval: "weekly"
32+
open-pull-requests-limit: 2
33+
allow:
34+
- dependency-name: "python"
35+
- dependency-name: "golang"
36+
- dependency-name: "securego/gosec"
37+
- dependency-name: "trufflesecurity/trufflehog"
38+
- dependency-name: "aquasec/trivy"
2639
labels:
2740
- "dependencies"
2841
- "docker"
@@ -37,6 +50,14 @@ updates:
3750
directory: "/"
3851
schedule:
3952
interval: "weekly"
53+
open-pull-requests-limit: 4
54+
groups:
55+
github-actions-minor-patch:
56+
patterns:
57+
- "*"
58+
update-types:
59+
- "minor"
60+
- "patch"
4061
labels:
4162
- "dependencies"
4263
- "github-actions"

‎.github/workflows/_docker-pipeline.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,8 @@ jobs:
6666
steps:
6767
- name: Checkout
6868
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
69+
with:
70+
persist-credentials: false
6971

7072
- name: 🔨 Set up Docker Buildx
7173
uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

‎.github/workflows/dependabot-review.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: dependabot-review
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened, ready_for_review]
6+
7+
permissions:
8+
contents: read
9+
10+
concurrency:
11+
group: dependabot-review-${{ github.event.pull_request.number }}
12+
cancel-in-progress: true
13+
14+
jobs:
15+
inspect:
16+
if: github.event.pull_request.user.login == 'dependabot[bot]'
17+
runs-on: ubuntu-latest
18+
outputs:
19+
root_docker_changed: ${{ steps.diff.outputs.root_docker_changed }}
20+
app_tests_docker_changed: ${{ steps.diff.outputs.app_tests_docker_changed }}
21+
workflow_or_action_changed: ${{ steps.diff.outputs.workflow_or_action_changed }}
22+
steps:
23+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
24+
with:
25+
fetch-depth: 0
26+
persist-credentials: false
27+
28+
- name: Inspect changed files
29+
id: diff
30+
env:
31+
BASE_SHA: ${{ github.event.pull_request.base.sha }}
32+
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
33+
run: |
34+
CHANGED_FILES="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")"
35+
36+
echo "Changed files:" >> "$GITHUB_STEP_SUMMARY"
37+
echo '```' >> "$GITHUB_STEP_SUMMARY"
38+
printf '%s\n' "$CHANGED_FILES" >> "$GITHUB_STEP_SUMMARY"
39+
echo '```' >> "$GITHUB_STEP_SUMMARY"
40+
41+
has_file() {
42+
local pattern="$1"
43+
if printf '%s\n' "$CHANGED_FILES" | grep -Eq "$pattern"; then
44+
echo "true"
45+
else
46+
echo "false"
47+
fi
48+
}
49+
50+
echo "root_docker_changed=$(has_file '^Dockerfile$')" >> "$GITHUB_OUTPUT"
51+
echo "app_tests_docker_changed=$(has_file '^app_tests/Dockerfile$')" >> "$GITHUB_OUTPUT"
52+
echo "workflow_or_action_changed=$(has_file '^\\.github/workflows/|^action\\.yml$|^\\.github/dependabot\\.yml$')" >> "$GITHUB_OUTPUT"
53+
54+
- name: Summarize review expectations
55+
env:
56+
PR_URL: ${{ github.event.pull_request.html_url }}
57+
run: |
58+
{
59+
echo "## Dependabot Review Checklist"
60+
echo "- PR: $PR_URL"
61+
echo "- Confirm upstream release notes before merge"
62+
echo "- Confirm Docker/toolchain changes match the files in this PR"
63+
echo "- Do not treat a Dependabot PR as trusted solely because of the actor"
64+
echo "- This workflow runs in pull_request context only; no publish secrets are exposed"
65+
} >> "$GITHUB_STEP_SUMMARY"
66+
67+
docker-smoke-main:
68+
needs: inspect
69+
if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.root_docker_changed == 'true'
70+
uses: ./.github/workflows/_docker-pipeline.yml
71+
permissions:
72+
contents: read
73+
with:
74+
name: socket-basics
75+
dockerfile: Dockerfile
76+
context: .
77+
check_set: main
78+
push: false
79+
80+
docker-smoke-app-tests:
81+
needs: inspect
82+
if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.app_tests_docker_changed == 'true'
83+
uses: ./.github/workflows/_docker-pipeline.yml
84+
permissions:
85+
contents: read
86+
with:
87+
name: socket-basics-app-tests
88+
dockerfile: app_tests/Dockerfile
89+
context: .
90+
check_set: app-tests
91+
push: false
92+
93+
workflow-notice:
94+
needs: inspect
95+
if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.workflow_or_action_changed == 'true'
96+
runs-on: ubuntu-latest
97+
steps:
98+
- name: Flag workflow-sensitive updates
99+
run: |
100+
{
101+
echo "## Sensitive File Notice"
102+
echo "This Dependabot PR changes workflow or action metadata files."
103+
echo "Require explicit human review before merge."
104+
} >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/publish-docker.yml‎

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ jobs:
4242
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
4343
with:
4444
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
45+
persist-credentials: false
4546

4647
- name: 🏷️ Resolve version
4748
id: version
@@ -97,6 +98,7 @@ jobs:
9798
with:
9899
ref: main
99100
fetch-depth: 0
101+
persist-credentials: false
100102

101103
- name: 🤖 Generate socket-release-bot token
102104
id: bot
@@ -129,25 +131,13 @@ jobs:
129131
--version "$VERSION" \
130132
--date "$DATE"
131133
132-
- name: 🔀 Commit CHANGELOG + action.yml back to main
134+
- name: 🔀 Commit CHANGELOG back to main
133135
env:
134136
BOT_TOKEN: ${{ steps.bot.outputs.token }}
135-
REF_NAME: ${{ github.ref_name }}
136137
run: |
137138
git config user.name "socket-release-bot[bot]"
138139
git config user.email "socket-release-bot[bot]@users.noreply.github.com"
139140
git remote set-url origin "https://x-access-token:${BOT_TOKEN}@github.com/SocketDev/socket-basics.git"
140-
141-
# Auto-update action.yml image ref to the new version.
142-
# No-op if action.yml still uses `image: "Dockerfile"` (handles the
143-
# chicken-and-egg on the initial v2.0.0 release).
144-
if grep -q 'docker://ghcr.io/socketdev/socket-basics:' action.yml; then
145-
sed -i "s|docker://ghcr.io/socketdev/socket-basics:[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*|docker://ghcr.io/socketdev/socket-basics:${VERSION}|" action.yml
146-
echo "Updated action.yml image ref to ${VERSION}"
147-
else
148-
echo "action.yml not yet using pre-built image — skipping version update"
149-
fi
150-
151-
git add CHANGELOG.md action.yml
152-
git diff --cached --quiet || git commit -m "chore: release ${REF_NAME} — update CHANGELOG and action.yml [skip ci]"
141+
git add CHANGELOG.md
142+
git diff --cached --quiet || git commit -m "chore: release ${github.ref_name} — update CHANGELOG [skip ci]"
153143
git push origin HEAD:main

‎.github/workflows/python-tests.yml‎

Lines changed: 2 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -45,34 +45,7 @@ jobs:
4545
run: |
4646
python -m pip install --upgrade pip
4747
pip install -e ".[dev]"
48-
- name: 🔒 Assert version files in sync
49-
run: |
50-
V_PY=$(python -c "from socket_basics.version import __version__; print(__version__)")
51-
V_TOML=$(python -c "import tomllib; print(tomllib.loads(open('pyproject.toml').read())['project']['version'])")
52-
[ "$V_PY" = "$V_TOML" ] || (echo "Version mismatch: version.py=$V_PY pyproject.toml=$V_TOML" && exit 1)
53-
echo "Version in sync: $V_PY"
54-
55-
- name: 🔒 Assert action.yml image ref matches version (once switched to pre-built)
56-
run: |
57-
python3 - <<'EOF'
58-
import re, sys, tomllib
59-
from pathlib import Path
60-
61-
action = Path("action.yml").read_text()
62-
version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
63-
64-
match = re.search(r'image:\s*["\']docker://[^:]+:([^"\']+)["\']', action)
65-
if not match:
66-
print(f"SKIP: action.yml still uses Dockerfile — check will activate once switched to pre-built image")
67-
sys.exit(0)
68-
69-
action_version = match.group(1)
70-
if action_version != version:
71-
print(f"FAIL: action.yml refs {action_version} but version is {version}")
72-
print(f" Update action.yml image ref to docker://ghcr.io/socketdev/socket-basics:{version}")
73-
sys.exit(1)
74-
75-
print(f"OK: action.yml image ref matches version {version}")
76-
EOF
48+
- name: 🔒 Assert release version metadata is in sync
49+
run: python3 scripts/sync_release_version.py --check
7750
- name: 🧪 Run tests
7851
run: pytest -q tests/

‎README.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,8 @@ jobs:
4343
socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
4444
```
4545
46-
> **Why pin to a SHA?** Socket Basics is a security tool — its own supply-chain
46+
> [!NOTE]
47+
> Why pin to a SHA? Socket Basics is a security tool, so its own supply-chain
4748
> integrity matters. Version tags can be force-pushed or deleted; a commit SHA is
4849
> immutable. Dependabot manages the upgrade automatically so you still get updates
4950
> with a review gate. See [docs/github-action.md](docs/github-action.md#pinning-strategies)
@@ -54,7 +55,7 @@ jobs:
5455
### What You Get
5556

5657
- ✅ **Zero Configuration Required** — Configure scanning policies in the Socket Dashboard
57-
- ✅ **All Scanners Included** — SAST, secrets, containers, and dependency analysis
58+
- ✅ **Unified Scanning** — SAST, secrets, dependency analysis, and native container scanning support
5859
- ✅ **PR Comments** — Automated security findings on pull requests
5960
- ✅ **Centralized Management** — Update policies across all repos from one place
6061

@@ -64,6 +65,21 @@ jobs:
6465

6566
Socket Basics can also run locally or in other CI/CD environments:
6667

68+
> [!IMPORTANT]
69+
> The supported pre-built GitHub Action and Docker image paths currently ship
70+
> _without_ Trivy while we evaluate the safest way to bundle it with Basics
71+
> again.
72+
> If you need Trivy in the meantime, use the native/manual path and pin to
73+
> `v0.69.3` or Docker tag `0.69.3`.
74+
> [Aqua's official incident summary](https://www.aquasec.com/blog/trivy-supply-chain-attack-what-you-need-to-know/)
75+
> lists the known-safe Trivy binary range as `v0.69.2` to `v0.69.3`; we
76+
> standardize on the latest known-safe version.
77+
> Do not use `v0.69.4`, and audit any cached Docker Hub images for `0.69.5` and
78+
> `0.69.6`.
79+
> See [Local Installation](docs/local-installation.md#trivy-container-scanning)
80+
> for the detailed version guidance, installation options, and the
81+
> corresponding Aqua action versions.
82+
6783
- **[Pre-Commit Hook](docs/pre-commit-hook.md)** — Catch issues before they're committed
6884
- **[Local Docker Installation](docs/local-install-docker.md)** — Run in Docker with no tool installation required
6985
- **[Local Installation](docs/local-installation.md)** — Install security tools natively on your machine
@@ -73,7 +89,7 @@ Socket Basics can also run locally or in other CI/CD environments:
7389
**Built-in Security Scanners:**
7490
- 🔍 **SAST** — Static analysis for 15+ languages (Python, JavaScript, Go, Java, Ruby, C#, and more)
7591
- 🔐 **Secret Scanning** — Detect leaked credentials and API keys with TruffleHog
76-
- 🐳 **Container Scanning** — Vulnerability scanning for Docker images and Dockerfiles with Trivy
92+
- 🐳 **Container Scanning** — Trivy-backed image and Dockerfile scanning for native installs
7793
- 📦 **Dependency Analysis** — Socket Tier 1 reachability analysis for supply chain security
7894

7995
**Enterprise Features** (requires [Socket Enterprise](https://socket.dev/enterprise)):
@@ -108,8 +124,7 @@ Every feature is customizable via GitHub Actions inputs, CLI flags, or environme
108124
- [PR Comment Guide](docs/github-pr-comment-guide.md) — Detailed guide to PR comment customization
109125
- [Pre-Commit Hook Setup](docs/pre-commit-hook.md) — Two installation methods (Docker vs native)
110126
- [Local Docker Installation](docs/local-install-docker.md) — Run with Docker, no tools to install
111-
- [Local Installation](docs/local-installation.md) — Install Socket CLI, Trivy, and other tools natively
112-
- [Releasing](docs/releasing.md) — Maintainer guide: How to cut a release for Socket Basics
127+
- [Local Installation](docs/local-installation.md) — Install Socket CLI and other tools natively with version pinning guidance
113128

114129
### Configuration
115130
All configuration can be managed through:
@@ -153,16 +168,18 @@ For GitHub Actions, see the [Quick Start](#-quick-start---github-actions) above
153168

154169
```bash
155170
# Pull the pre-built image (recommended — no build step required)
156-
docker pull socketdev/socket-basics:1.1.3
171+
docker pull ghcr.io/socketdev/socket-basics:2.0.2
157172
158173
# Run scan
159-
docker run --rm -v "$PWD:/workspace" socketdev/socket-basics:1.1.3 \
174+
docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:2.0.2 \
160175
--workspace /workspace \
161176
--python-sast-enabled \
162177
--secret-scanning-enabled \
163178
--console-tabular-enabled
164179
```
165180

181+
The pre-built image is versioned and intended to be pinned exactly. Avoid floating tags like `:latest` in CI.
182+
166183
📖 **[View Docker Installation Guide](docs/local-install-docker.md)**
167184

168185
### CLI
@@ -175,12 +192,12 @@ socket-basics --python --secrets --containers --verbose
175192

176193
## 🔧 Requirements
177194

178-
**For GitHub Actions & Docker:** No installation needed — all tools are bundled in the container.
195+
**For GitHub Actions & Docker:** No local installation needed for the supported bundled scanners.
179196

180197
**For Local Installation:**
181198
- Python 3.10+
182199
- [Socket CLI](https://docs.socket.dev/docs/cli) (for dependency analysis)
183-
- [Trivy](https://github.com/aquasecurity/trivy) (for container scanning)
200+
- [Trivy](https://github.com/aquasecurity/trivy) (for native container scanning)
184201
- [OpenGrep/Semgrep](https://semgrep.dev/) (for SAST)
185202
- [TruffleHog](https://github.com/trufflesecurity/trufflehog) (for secret scanning)
186203

@@ -258,7 +275,6 @@ We welcome contributions! To add new features:
258275
2. **New Notifiers:** Implement under `socket_basics/core/notification/`
259276
3. **Configuration:** Add entries to `socket_basics/connectors.yaml` or `socket_basics/notifications.yaml`
260277
4. **Testing:** See [Testing](#-testing) section below
261-
5. **Releasing:** See [docs/releasing.md](docs/releasing.md) for the maintainer release process
262278

263279
## 🧪 Testing
264280

‎action.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ runs:
7676
INPUT_SWIFT_DISABLED_RULES: ${{ inputs.swift_disabled_rules }}
7777
INPUT_SWIFT_ENABLED_RULES: ${{ inputs.swift_enabled_rules }}
7878
INPUT_SWIFT_SAST_ENABLED: ${{ inputs.swift_sast_enabled }}
79+
# Trivy-backed scanning is temporarily disabled in the pre-built GitHub Action image.
7980
INPUT_TRIVY_DISABLED_RULES: ${{ inputs.trivy_disabled_rules }}
8081
INPUT_TRIVY_IMAGE_SCANNING_DISABLED: ${{ inputs.trivy_image_scanning_disabled }}
8182
INPUT_TRIVY_NOTIFICATION_METHOD: ${{ inputs.trivy_notification_method }}
@@ -383,19 +384,19 @@ inputs:
383384
required: false
384385
default: "false"
385386
trivy_disabled_rules:
386-
description: "Comma-separated list of Trivy rules to disable"
387+
description: "Comma-separated list of Trivy rules to disable. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
387388
required: false
388389
default: ""
389390
trivy_image_scanning_disabled:
390-
description: "Disable Trivy image scanning"
391+
description: "Disable Trivy image scanning. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
391392
required: false
392393
default: "false"
393394
trivy_notification_method:
394-
description: "Notification method for Trivy (e.g., console, slack)"
395+
description: "Notification method for Trivy (e.g., console, slack). Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
395396
required: false
396397
default: ""
397398
trivy_vuln_enabled:
398-
description: "Enable Trivy vulnerability scanning for all supported language ecosystems"
399+
description: "Enable Trivy vulnerability scanning for all supported language ecosystems. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
399400
required: false
400401
default: "false"
401402
trufflehog_exclude_dir:

0 commit comments

Comments
 (0)