Skip to content

Commit 244fdba

Browse files
sbp-bvanbclaude
sbp-bvanb
and
claude
authored
docs: add CLAUDE.md and remove incorrect Trivy references (#40)
* docs: add CLAUDE.md and remove incorrect Trivy references - Add CLAUDE.md for Claude Code guidance on architecture and workflows - Remove non-existent Trivy inputs from README (action uses Anchore) - Remove unused Trivy scanning steps from action.yml - Update dependabot to weekly schedule with grouped updates - Add release and license badges to README Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * build: use general action to check git lint etc * fix: install pyinstaller and flake8 using a hash for security reasons --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 6ed98b7 commit 244fdba

9 files changed

Lines changed: 219 additions & 61 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,33 @@
11
---
22
version: 2
33
updates:
4-
- package-ecosystem: 'github-actions'
5-
directory: '/'
4+
- package-ecosystem: github-actions
5+
directory: /
66
schedule:
7-
interval: 'daily'
7+
interval: weekly
8+
cooldown:
9+
default-days: 5
10+
groups:
11+
github-actions-all:
12+
patterns:
13+
- "*"
14+
- package-ecosystem: pip
15+
directory: /configs/pip/flake8
16+
schedule:
17+
interval: weekly
18+
cooldown:
19+
default-days: 5
20+
groups:
21+
github-actions-all:
22+
patterns:
23+
- "*"
24+
- package-ecosystem: pip
25+
directory: /configs/pip/pyinstaller
26+
schedule:
27+
interval: weekly
28+
cooldown:
29+
default-days: 5
30+
groups:
31+
github-actions-all:
32+
patterns:
33+
- "*"

‎.github/workflows/general.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: general
3+
"on": pull_request
4+
permissions:
5+
contents: read
6+
packages: read
7+
jobs:
8+
MCVS-general-action:
9+
strategy:
10+
matrix:
11+
args:
12+
- testing-type: lint-commit
13+
- testing-type: lint-git
14+
- testing-type: security-file-system
15+
- testing-type: yamllint
16+
runs-on: ubuntu-slim
17+
steps:
18+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
19+
# yamllint disable-line rule:line-length
20+
- uses: schubergphilis/mcvs-general-action@f52c4433add29d8eff9036bf37b5b69a2c4cf28b # v0.5.8
21+
with:
22+
testing-type: ${{ matrix.args.testing-type }}

‎.github/workflows/mcvs-pr-validation.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: MCVS-PR-validation-action
3-
'on':
3+
"on":
44
pull_request:
55
types:
66
- edited
@@ -13,7 +13,8 @@ permissions:
1313
pull-requests: read
1414
jobs:
1515
MCVS-PR-validation-action:
16-
runs-on: ubuntu-22.04
16+
runs-on: ubuntu-slim
1717
steps:
18-
- uses: actions/checkout@v4.2.2
19-
- uses: schubergphilis/mcvs-pr-validation-action@v0.2.0
18+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
19+
# yamllint disable-line rule:line-length
20+
- uses: schubergphilis/mcvs-pr-validation-action@b1c337a896fea52b52a93335713a435d5a07ea72 # v0.2.0

‎.github/workflows/python.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: python
3+
"on": pull_request
4+
permissions:
5+
contents: read
6+
packages: read
7+
jobs:
8+
mcvs-python-action:
9+
runs-on: ubuntu-slim
10+
steps:
11+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
12+
- uses: ./
13+
with:
14+
token: ${{ secrets.GITHUB_TOKEN }}

‎CLAUDE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is a **composite GitHub Action** (not a standalone application) that provides the Mission Critical Vulnerability Scanner (MCVS) for Python projects. The action performs security scanning, linting, testing, and optional binary building for Python codebases.
8+
9+
## Architecture
10+
11+
### Composite Action Structure
12+
13+
The action is defined in `action.yml` and executes as a series of composite steps:
14+
15+
1. **YAML Linting**: Validates YAML files using yamllint
16+
2. **Python Environment Setup**: Installs Python version from `.python-version`
17+
3. **Security Scanning**: Uses Anchore scan-action to detect vulnerabilities
18+
4. **Dependency Installation**: Installs packages from `requirements.txt` if present
19+
5. **Testing**: Runs pytest if tests are detected
20+
6. **Code Linting**: Uses Flake8 with a configurable error threshold
21+
7. **Binary Building**: Conditionally builds PyInstaller binaries on tag releases
22+
23+
### Key Design Decisions
24+
25+
- **Composite vs Docker**: Uses `using: composite` to avoid Docker overhead and enable caching
26+
- **Conditional Execution**: Steps like testing and binary building only run when applicable
27+
- **Token Authentication**: Requires GitHub token for package registry and Docker registry access
28+
- **Version Pinning**: All tools are pinned to specific versions for reproducibility
29+
30+
## Version Constraints
31+
32+
**CRITICAL**: The following versions are pinned in `action.yml`:
33+
34+
- `yamllint==1.37.1` (action.yml:21)
35+
- `actions/setup-python@v5.6.0` (action.yml:28)
36+
- `anchore/scan-action@v6.2.0` (action.yml:34)
37+
- `flake8==7.2.0` (action.yml:75)
38+
- `pyinstaller==v6.13.0` (action.yml:102)
39+
- `svenstaro/upload-release-action@2.9.0` (action.yml:106)
40+
41+
When updating dependencies:
42+
- Update the version in `action.yml`
43+
- Dependabot automatically creates PRs for GitHub Actions updates (see `.github/dependabot.yml`)
44+
- Python package versions must be updated manually
45+
46+
## Testing Changes
47+
48+
This action is tested via PR validation:
49+
50+
```yaml
51+
# Validation happens automatically on PRs via .github/workflows/mcvs-pr-validation.yml
52+
# Uses schubergphilis/mcvs-pr-validation-action@v0.2.0
53+
```
54+
55+
To test locally before committing:
56+
57+
```bash
58+
# Test YAML linting (matches action behavior)
59+
pip install yamllint==1.37.1
60+
yamllint .
61+
62+
# Validate action.yml structure
63+
# No local validation tool - rely on PR validation workflow
64+
```
65+
66+
## Dependency Management
67+
68+
### Dependabot Configuration
69+
70+
Dependabot is configured for GitHub Actions only (`.github/dependabot.yml`):
71+
- Runs weekly checks
72+
- 5-day cooldown between updates
73+
- Groups all GitHub Actions updates together
74+
75+
**Note**: Python package dependencies (yamllint, flake8, pyinstaller) are NOT managed by Dependabot and must be updated manually in `action.yml`.
76+
77+
## Flake8 Configuration
78+
79+
The action has a **configurable error threshold** for Flake8:
80+
81+
```bash
82+
# Current threshold: 4 errors/warnings maximum
83+
--max-line-length=150
84+
--exclude=client/,.venv/,venv/
85+
```
86+
87+
Pipeline fails if error count > 4 (action.yml:81-83). This threshold may need adjustment when adding strict linting rules.
88+
89+
## PyInstaller Binary Building
90+
91+
Binary building is **conditional** and requires:
92+
1. Push event to a tag (`refs/tags/*`)
93+
2. Non-empty `pyinstaller-binary-name` input
94+
95+
The binary is automatically attached to GitHub releases (action.yml:89-111).
96+
97+
## Action Inputs
98+
99+
Required inputs when using this action:
100+
101+
| Input | Required | Purpose |
102+
|-------|----------|---------|
103+
| `token` | Yes | GitHub token for package registry and Docker login |
104+
| `pyinstaller-binary-name` | No | If set, builds and releases a binary |
105+
106+
## Important Workflow Notes
107+
108+
- Projects using this action must have a `.python-version` file to specify Python version
109+
- `requirements.txt` is optional - only installed if present
110+
- Tests only run if `import pytest` is found in Python files
111+
- Security scanning uses severity cutoff of "high" (action.yml:39)
112+
- Docker login required for security scanning (action.yml:40-44)

‎README.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# MCVS-python-action
22

3+
[![GitHub release](https://img.shields.io/github/v/release/schubergphilis/mcvs-python-action)](https://github.com/schubergphilis/mcvs-python-action/releases)
4+
[![License](https://img.shields.io/github/license/schubergphilis/mcvs-python-action)](LICENSE)
5+
36
Mission Critical Vulnerability Scanner (MCVS) Python Action. Create Python code without high and critical vulnerabilities.
47

58
## Usage
@@ -16,20 +19,18 @@ jobs:
1619
MCVS-python-action:
1720
runs-on: ubuntu-24.04
1821
steps:
19-
- uses: actions/checkout@v4.2.2
20-
- uses: schubergphilis/mcvs-python-action@v0.2.1
22+
- uses: actions/checkout@some-hash # v4.2.2
23+
- uses: schubergphilis/mcvs-python-action@some-hash # v0.2.1
2124
with:
2225
token: ${{ secrets.GITHUB_TOKEN }}
2326
```
2427
2528
<!-- markdownlint-disable MD013 -->
2629
27-
| Option | Default | Required | Description |
28-
| :---------------------- | :----------------------------------- | -------- | :---------------------------------------------------------------------------------------------------------------- |
29-
| pyinstaller-binary-name | | | If populated, then a binary will be created using pyinstaller and attached to a release |
30-
| token | ' ' | x | GitHub token that is required to push a package to the registry of the project and to pull cached Trivy DB images |
31-
| trivy-action-db | ghcr.io/aquasecurity/trivy-db:2 | | Replace this with a cached image to prevent bump into pull rate limiting issues |
32-
| trivy-action-java-db | ghcr.io/aquasecurity/trivy-java-db:1 | | Replace this with a cached image to prevent bump into pull rate limiting issues |
30+
| Option | Default | Required | Description |
31+
| :---------------------- | :------ | -------- | :--------------------------------------------------------------------------------------------------------- |
32+
| pyinstaller-binary-name | | | If populated, then a binary will be created using pyinstaller and attached to a release |
33+
| token | | x | GitHub token required for Docker registry authentication and uploading release assets (if building binary) |
3334
3435
<!-- markdownlint-enable MD013 -->
3536

‎action.yml‎

Lines changed: 23 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -5,66 +5,33 @@ description: |
55
inputs:
66
pyinstaller-binary-name:
77
description: The name of the binary that is created using pyinstaller.
8-
trivy-action-db:
9-
default: 'ghcr.io/aquasecurity/trivy-db:2'
10-
description: |
11-
OCI repository to retrieve trivy-db from.
12-
trivy-action-java-db:
13-
description: |
14-
OCI repository to retrieve trivy-java-db from.
15-
default: 'ghcr.io/aquasecurity/trivy-java-db:1'
168
token:
179
description: |
1810
A token is required to allow the mcvs-python-action to push the
1911
package that it has been built, to the packages repository of the GitHub
20-
repository where the action has been run and to pull the cached trivy DBs
21-
to prevent bump into pull rate limits.
12+
repository where the action has been run.
2213
required: true
2314
runs:
24-
using: 'composite'
15+
using: composite
2516
steps:
2617
#
27-
# YAML linting.
28-
#
29-
- run: |
30-
pip install --user yamllint==1.37.1
31-
yamllint .
32-
shell: bash
33-
#
3418
# Install the python version that has been defined in the .python-version
3519
# file.
3620
#
37-
- uses: actions/setup-python@v5.6.0
21+
# yamllint disable-line rule:line-length
22+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
3823
with:
39-
cache: 'pip'
24+
cache: pip
4025
#
4126
# Code security scanning.
4227
#
43-
- uses: anchore/scan-action@v6.2.0
28+
# yamllint disable-line rule:line-length
29+
- uses: anchore/scan-action@e1165082ffb1fe366ebaf02d8526e7c4989ea9d2 # v6.2.0
4430
with:
4531
only-fixed: false
4632
output-format: table
47-
path: '.'
33+
path: .
4834
severity-cutoff: high
49-
- uses: 030/trivyignore-validator-action@v0.1.2
50-
- name: Log in to GitHub Packages Docker registry
51-
shell: bash
52-
run: |
53-
echo "${{ inputs.token }}" |\
54-
docker login ghcr.io -u ${{ github.actor }} --password-stdin
55-
- uses: aquasecurity/trivy-action@0.30.0
56-
env:
57-
TRIVY_DB_REPOSITORY: ${{ inputs.trivy-action-db }}
58-
TRIVY_JAVA_DB_REPOSITORY: ${{ inputs.trivy-action-java-db }}
59-
TRIVY_PASSWORD: ${{ inputs.token }}
60-
TRIVY_USERNAME: ${{ github.actor }}
61-
with:
62-
scan-type: 'fs'
63-
scan-ref: '.'
64-
exit-code: '1'
65-
ignore-unfixed: true
66-
severity: 'CRITICAL,HIGH'
67-
trivyignores: .trivyignore
6835
#
6936
# If a requirements file exists in the project, then install the packages.
7037
#
@@ -74,7 +41,7 @@ runs:
7441
requirements_file=requirements.txt
7542
if [ -f ${requirements_file} ]; then
7643
pip install \
77-
-r ${requirements_file}
44+
--requirement ${requirements_file}
7845
fi
7946
#
8047
# Run pytest if 'import pytest' is found.
@@ -92,10 +59,15 @@ runs:
9259
#
9360
# Lint code with Flake8
9461
#
62+
# yamllint disable rule:line-length
9563
- name: Code linting with Flake8
9664
shell: bash
9765
run: |
98-
pip install flake8==7.2.0
66+
python3 -m pip install \
67+
--require-hashes \
68+
--user \
69+
--requirement \
70+
${GITHUB_ACTION_PATH}/configs/pip/flake8/requirements.txt
9971
10072
errors=$(flake8 -v --max-line-length=150 --exclude=client/,.venv/,venv/ --count --statistics --exit-zero .)
10173
echo "Flake8 reported $errors errors/warnings."
@@ -111,7 +83,6 @@ runs:
11183
# Build binary using pyinstaller and attach it to a release once a tag has
11284
# been created.
11385
#
114-
# yamllint disable rule:line-length
11586
- name: Check Conditions
11687
id: condition_check
11788
run: echo "Checking conditions..."
@@ -123,10 +94,16 @@ runs:
12394
shell: bash
12495
run: |
12596
pip install pyinstaller==v6.13.0
97+
python3 -m pip install \
98+
--require-hashes \
99+
--user \
100+
--requirement \
101+
${GITHUB_ACTION_PATH}/configs/pip/pyinstaller/requirements.txt
126102
pyinstaller --onefile main.py --name gomod-go-version-updater
127-
- name: Attach a binary to a release
103+
# yamllint disable-line rule:line-length
104+
- uses: svenstaro/upload-release-action@04733e069f2d7f7f0b4aebc4fbdbce8613b03ccd # 2.9.0
105+
name: Attach a binary to a release
128106
if: ${{ steps.condition_check.outcome == 'success' }}
129-
uses: svenstaro/upload-release-action@2.9.0
130107
with:
131108
repo_token: ${{ inputs.token }}
132109
file: dist/${{ inputs.pyinstaller-binary-name }}

‎configs/pip/flake8/requirements.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
flake8==7.2.0 --hash=sha256:93b92ba5bdb60754a6da14fa3b93a9361fd00a59632ada61fd7b130436c40343
2+
pycodestyle==2.13.0 --hash=sha256:35863c5974a271c7a726ed228a14a4f6daf49df369d8c50cd9a6f58a5e143ba9
3+
pyflakes==3.3.2 --hash=sha256:5039c8339cbb1944045f4ee5466908906180f13cc99cc9949348d10f82a5c32a
4+
mccabe==0.7.0 --hash=sha256:6c2d30ab6be0e4a46919781807b4f0d834ebdd6c6e3dca0bda5a15f863427b6e

‎configs/pip/pyinstaller/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pyinstaller==v6.13.0 --hash=sha256:bc09795f5954135dd4486c1535650958c8218acb954f43860e4b05fb515a21c0

0 commit comments

Comments
 (0)