Repository navigation
chore: whole-repo review snapshot of main a1ac487 (do not merge) #287
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,221 @@ | ||
| # .coderabbit.yaml — BeatsCheck (audio integrity / ID3 analysis; raw-Python HTTP server + Docker) | ||
| language: "en-US" | ||
| reviews: | ||
| # assertive: chill passed a diff clean that assertive flagged with two Major findings (2026-09-03); the "**" rule keeps style nits out | ||
| profile: "assertive" | ||
| request_changes_workflow: false | ||
| pre_merge_checks: | ||
| # off: the 80% docstring-coverage warning contradicts the one-line-docstring rule under "**" | ||
| docstrings: | ||
| mode: "off" | ||
| title: | ||
| mode: warning | ||
| requirements: |- | ||
| Conventional Commits, `type(scope)?: subject`. release-please reads the | ||
| squash-merge title to pick the next version: feat bumps minor, fix bumps | ||
| patch, a `!` after the type or a BREAKING CHANGE footer bumps major, and | ||
| chore/ci/test/build are hidden from the changelog and never release on | ||
| their own. Flag a title whose type understates the diff (a behaviour | ||
| change labelled chore or ci ships unversioned) or overstates it. | ||
| auto_review: | ||
| enabled: true | ||
| drafts: false | ||
| # Single branch: main is the default and is always auto-reviewed. No other PR | ||
| # targets exist, so base_branches is intentionally omitted. | ||
| path_filters: | ||
| - "!**/*.png" | ||
| - "!design_handoff_beatscheck_redesign/**" | ||
| - "!**/.pytest_cache/**" | ||
| - "!**/__pycache__/**" | ||
| - "!**/*.pyc" | ||
| path_instructions: | ||
| - path: "app/webui.py" | ||
| instructions: | | ||
| Raw http.server request handler — there is NO framework doing input | ||
| validation, routing safety, or auth for you. Enforce: | ||
| - FAIL CLOSED on every guard. _load_auth() must refuse setup AND login | ||
| when the auth file exists but is unreadable/corrupt or is missing | ||
| username/password_hash (it returns a sentinel for this — verify callers | ||
| treat the sentinel as DENY, never as "no account / allow setup"). | ||
| _check_auth() and _validate_session() must return False on any missing/ | ||
| expired/malformed token or lookup failure — never fall through to the | ||
| authorated path. Flag any `if config and not allowed(): deny` shape | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Correct the typo "authorated" to "authorized". Line 42 contains this misspelling inside the 🤖 Prompt for AI Agents |
||
| (that skips the check when config is falsy) and any except-clause that | ||
| calls the handler / serves content on error instead of sending 401/503. | ||
| - PATH TRAVERSAL: any filesystem path derived from self.path (static | ||
| files, /api/paths parent, log/corrupt files) must be resolved with | ||
| os.path.realpath() and re-asserted inside the allowed root via | ||
| _is_subpath() BEFORE opening. A string-only prefix/".." check is | ||
| defeated by a symlinked component or ../ collapse — require the | ||
| realpath re-confinement. _serve_static must reject anything whose | ||
| realpath escapes static_dir; /api/paths must reject anything whose | ||
| realpath escapes /data. Flag new file-serving/listing endpoints that | ||
| skip this. | ||
| - Validate and bound every request input (query params, JSON body, | ||
| Content-Length, headers) before use; malformed/oversized/absent input | ||
| must return 4xx, not raise or default-through. | ||
| - Never place the session token (secrets.token_hex) in a URL, redirect, | ||
| <img>/EventSource src, or log line — it is a 24h bearer credential. | ||
| Keep it in the HttpOnly cookie path only. | ||
| - Failed-login throttle (_login_lockout_remaining / _login_record_failure) | ||
| must count and lock BEFORE password verification, and must not be | ||
| bypassable by a malformed body reaching an early return. | ||
| - path: "app/main.py" | ||
| instructions: | | ||
| Scan engine, ID3 detector, and irreversible bulk-delete of user music. | ||
| - DOMAIN (ID3 false-positive): _strip_benign_metadata_noise / | ||
| _is_benign_metadata_noise must strip ONLY genuine ID3 tag-parse noise | ||
| (the _BENIGN_METADATA_MARKERS set) and MUST keep real decoder errors | ||
| (Header missing / Invalid data / backstep) so a corrupt file still | ||
| fails closed. Flag any broadening of the benign markers, substring | ||
| match, or logic that could make check_audio_file return is_corrupt=False | ||
| for a file with real decode errors. Old-ffmpeg (4.x-6.x) emits this | ||
| noise at error level; do not let that re-introduce false positives on | ||
| clean audio. | ||
| - TRANSIENT != CLEAN: a scan/decode failure that is transient — OSError | ||
| on stat, subprocess.TimeoutExpired, ffmpeg spawn failure, I/O error — | ||
| must NOT be recorded or cached as a "clean"/negative result. Distinguish | ||
| genuine decode-failure (real result) from infrastructure failure (retry, | ||
| do not persist as clean). Flag any except path that swallows a transient | ||
| error and returns/persists is_corrupt=False. | ||
| - DESTRUCTIVE BULK OPS (irrecoverable — rmtree/os.remove of the user's | ||
| music library): default to NOT deleting and gate on explicit intent. | ||
| Before any shutil.rmtree / os.remove, the RESOLVED physical target must | ||
| pass _validate_delete_folders: realpath, reject == music-root (mount | ||
| root), reject anything not under music_real + os.sep, reject symlinks, | ||
| reject non-directories. An EMPTY validated/allowed set means a FAILED | ||
| READ (corrupt.txt/details unreadable) — treat it as "delete nothing", | ||
| never "delete everything". delete_corrupt_files must only remove paths | ||
| confirmed present in the corrupt.txt allowed set; a path "not in corrupt | ||
| list" is an error, not a pass. | ||
| - DIFF THE SIBLING DELETE BRANCHES. _delete_one_folder has two destructive | ||
| arms: mode 'whole' -> _rmtree_and_collect (shutil.rmtree) and mode | ||
| 'corrupt' -> _direct_delete_untracked (os.remove). A containment/symlink/ | ||
| mount-root guard present on one arm and absent on the other is the bug — | ||
| require both arms to share the _validate_delete_folders confinement, and | ||
| flag any new delete path that reaches rmtree/remove without it. | ||
| - Confirm state cleanup (corrupt.txt / corrupt_details.json / | ||
| corrupt_tracking.json rewrite) is atomic (tmp + os.rename) and cannot | ||
| leave a deleted file still listed as corrupt or a surviving file dropped. | ||
| - path: "app/**/*.py" | ||
| instructions: | | ||
| - Python truthiness / 0-is-falsy: for durations, file sizes, counts, | ||
| corrupt totals, timestamps, and exit codes where 0 (or "") is a | ||
| legitimate value, use explicit `is None` / `is not None` checks, not | ||
| bare `if x:` / `x or default`. Flag `count or default`, `size or 0`, | ||
| `if not duration:` where 0 must be honoured. | ||
| - Read live config each pass in long-lived threads/handlers (scan loop, | ||
| background delete jobs); do not snapshot a config/state object at | ||
| startup and act on it after config is replaced on reload. | ||
| - Comments: navigational / gotcha only (<=1-2 lines, the non-obvious | ||
| "why"), matching existing density. Do not add restating-the-code or | ||
| history-essay comments. | ||
| - path: "app/static/app.js" | ||
| instructions: | | ||
| - JS 0/"" are falsy: do not use `||` to supply a fallback for a value | ||
| where 0 or "" is legitimate (corrupt counts, sizes, progress current/ | ||
| total, durations). Use `??` or an explicit null/NaN check | ||
| (Number.isFinite, `x == null`). The `n == null || isNaN(n)` guard is the | ||
| correct pattern; flag new `count || 0` / `value || '--'` fallbacks that | ||
| would mask a real 0. | ||
| - Never put the session/auth token in a URL, fetch query string, EventSource | ||
| src, or <img> src — auth rides the HttpOnly cookie. Flag any polling/ | ||
| streaming endpoint that appends a credential to the URL. | ||
| - path: "scripts/**" | ||
| instructions: | | ||
| Container helper wrappers (delete/rescan/reset-password/entrypoint) that | ||
| run as root then drop to PUID/PGID via su-exec, plus fix_ownership.py. | ||
| - fix_ownership.py opens the root O_NOFOLLOW and walks with fwalk | ||
| follow_symlinks=False so a directory swapped for a symlink is never | ||
| descended or chowned through; flag any change that follows symlinks or | ||
| that turns a per-file chown failure into a start failure — the | ||
| entrypoint's write probe is the real gate, by design. | ||
| - FAIL CLOSED: delete.sh must abort when MUSIC_DIR is not writable / not | ||
| present (it already checks `-w`); a destructive wrapper must never | ||
| proceed on an unverified or unreadable target. Quote every path | ||
| expansion ("$MUSIC_DIR", "${PUID}") to survive spaces. | ||
| - Preserve correct PUID/PGID drop (default 99:100) and UMASK; do not run | ||
| the delete/scan Python as root. | ||
| - No secrets echoed or baked into the script or its logs. | ||
| - path: "**/Dockerfile" | ||
| instructions: | | ||
| - Base image must stay pinned by digest (alpine@sha256:...) on every | ||
| stage; flag an unpinned or floating tag. Keep the ffmpeg fetch stage's | ||
| SHA-256 verification intact — a download without checksum verification | ||
| is a supply-chain hole. | ||
| - HEALTHCHECK must be present and meaningful (pgrep main.py + heartbeat | ||
| freshness); flag its removal or weakening. | ||
| - PUID/PGID/UMASK handling: keep the su-exec privilege drop; do not switch | ||
| the runtime to root or bake a fixed UID that breaks the drop. | ||
| - No secrets/tokens/credentials baked into any layer, ARG default, or | ||
| LABEL; nothing sensitive in ENV. | ||
| - Run a LIVE dependency/CVE audit (pip-audit for Python, and re-check the | ||
| apk-added packages + the pinned ffmpeg version) before tagging a release; | ||
| never rely on a stale offline CVE list. | ||
| - A recursive chown/chmod after a COPY re-materialises the whole tree in a | ||
| new layer and duplicates it in the image — use COPY --chown instead. | ||
| - path: "tests/**/*.py" | ||
| instructions: | | ||
| - Tests live under tests/, so app/**/*.py does not reach them. | ||
| - No side-effecting call inside an assert: python -O strips assert | ||
| statements and takes the call with them. Bind to a local, then assert. | ||
| - A guard that cannot fail is worse than none — an assertion reachable only | ||
| when a collection is non-empty passes vacuously. Pair it with a control | ||
| that fails when the defect is injected. | ||
| - Never let a test invoke real ffmpeg on a real library path or hit the | ||
| network; stub the boundary. | ||
| - path: "compose.yaml" | ||
| instructions: | | ||
| - Keep PUID/PGID/UMASK and the volume layout consistent with the Dockerfile | ||
| and README; a drift here silently breaks the privilege drop for users. | ||
| - No secrets inline — reference an env file or an existing environment | ||
| variable, never a literal token. | ||
| - Don't add privileged, host network mode, or a docker-socket mount. | ||
| - path: ".github/workflows/**" | ||
| instructions: | | ||
| - A gate that stops blocking (a lint/CVE/test step made non-blocking or | ||
| continue-on-error) must have every downstream step that relied on it | ||
| audited in the same change. | ||
| - Enumerate allowed states positively (== 'success' || == 'skipped'), never | ||
| by negation — a third state slips through `!= 'failure'`. | ||
| - Pin third-party actions by commit SHA, not a mutable tag. | ||
| - Never echo a token, and never interpolate untrusted input (PR title, | ||
| branch name, issue body) straight into a `run:` block — pass it via env. | ||
| - A paths filter added or renamed must stay in step with what the job | ||
| actually needs, or the image silently stops being built when it changes. | ||
| - path: "beats-check.xml" | ||
| instructions: |- | ||
| Published Unraid CA template — what a fresh install gets: | ||
| - <Network> stays bridge; a personal network name belongs only in the | ||
| user's my-*.xml copy, never in the repo template. | ||
| - /data defaults to Mode="ro" (report mode is the safe default); flag a | ||
| change to rw or a new host path that widens what the container can | ||
| delete. | ||
| - Every <Config> (PUID/PGID/UMASK/TZ, /config, port 8484) must match the | ||
| Dockerfile, compose.yaml and README; a renamed env var here without | ||
| the matching entrypoint change breaks fresh installs silently. | ||
| - path: "**" | ||
| instructions: |- | ||
| Applies to every file, whatever the language: | ||
| - Comments are navigational or instructional only and capped at 1-2 lines: | ||
| what a non-obvious block does, or the gotcha it guards. No why/history | ||
| essays, no before/after narrative, no restating the code, no section | ||
| banners. Docstrings: one line unless the signature genuinely cannot | ||
| carry it. Never ask for a docstring to be added; a missing docstring | ||
| is not a finding. | ||
| - The 1-2 line cap wins even inside an already heavily-commented file — | ||
| matching local density is not licence to exceed it. | ||
| - A comment, docstring, help text, column header, log message or UI label | ||
| that disagrees with what the code does is a correctness finding, not a | ||
| stale-comment nit: report it and say which side is wrong. | ||
| - Do not flag stylistic preferences that are consistent across the file | ||
| (naming, quoting, import order, formatting, line length). Report | ||
| correctness, security, data-loss and the classes named above. | ||
|
|
||
| tools: | ||
| ruff: | ||
| enabled: true | ||
| gitleaks: | ||
| enabled: true | ||
| hadolint: | ||
| enabled: true | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| .git | ||
| .github | ||
| *.md | ||
| LICENSE | ||
| beats-check.xml | ||
| compose.yaml | ||
| .dockerignore | ||
| .editorconfig | ||
| .gitignore | ||
| CLAUDE.md |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| root = true | ||
|
|
||
| [*] | ||
| end_of_line = lf | ||
| insert_final_newline = true | ||
| trim_trailing_whitespace = true | ||
| charset = utf-8 | ||
|
|
||
| [*.py] | ||
| indent_style = space | ||
| indent_size = 4 | ||
| max_line_length = 127 | ||
|
|
||
| [*.{yml,yaml}] | ||
| indent_style = space | ||
| indent_size = 2 | ||
|
|
||
| [*.{sh}] | ||
| indent_style = space | ||
| indent_size = 4 | ||
|
|
||
| [*.xml] | ||
| indent_style = space | ||
| indent_size = 2 | ||
|
|
||
| [Dockerfile] | ||
| indent_style = space | ||
| indent_size = 4 |
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,61 @@ | ||||||
| # Security Policy | ||||||
|
|
||||||
| ## Supported Versions | ||||||
|
|
||||||
| | Version | Supported | | ||||||
| |---------|-----------| | ||||||
| | latest | Yes | | ||||||
| | < latest | No | | ||||||
|
|
||||||
| ## Reporting a Vulnerability | ||||||
|
|
||||||
| If you discover a security vulnerability, please report it responsibly: | ||||||
|
|
||||||
| 1. **GitHub Security Advisory** (preferred): [Create a private advisory](https://github.com/chodeus/BeatsCheck/security/advisories/new) | ||||||
| 2. **Email**: Open a GitHub issue marked `[SECURITY]` if it is not sensitive | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win Fix the "Email" reporting channel: it has no email address. Line 15 has the label "Email", but it tells the reporter to open a public GitHub issue. The label and the text disagree. This line is also the only fallback channel, so a reporter who cannot use advisories has no private way to report. Add a real private email address, or rename the item so it describes a public issue for non-sensitive reports only. Proposed fix--- "a/.github/SECURITY.md"
+++ "b/.github/SECURITY.md"
@@ -12,7 +12,7 @@
If you discover a security vulnerability, please report it responsibly:
1. **GitHub Security Advisory** (preferred): [Create a private advisory](https://github.com/chodeus/BeatsCheck/security/advisories/new)
-2. **Email**: Open a GitHub issue marked `[SECURITY]` if it is not sensitive
+2. **Public issue** (non-sensitive reports only): Open a GitHub issue marked `[SECURITY]`
Please do **not** open a public issue for security vulnerabilities that could be exploited.
As per path instructions: a label "that disagrees with what the code does is a correctness finding". 📝 Committable suggestion
Suggested change
🤖 Prompt for AI AgentsSource: Path instructions |
||||||
|
|
||||||
| Please do **not** open a public issue for security vulnerabilities that could be exploited. | ||||||
|
|
||||||
| ## Security Measures | ||||||
|
|
||||||
| ### Container Security | ||||||
| - Runs as a non-root user via `su-exec` (configurable PUID/PGID) | ||||||
| - Minimal Alpine base image with only required packages | ||||||
| - Music directory mounted read-only by default (`:ro`) | ||||||
| - Core scanning needs no network access (`--network none` is supported | ||||||
| when the optional Lidarr integration is not configured) | ||||||
| - Tini init process for proper signal handling | ||||||
| - HEALTHCHECK for container orchestrator monitoring | ||||||
| - Supports two hardened deployment modes (both documented in `compose.yaml`): | ||||||
| - **Capability-dropped PUID/PGID:** `cap_drop: ALL` + `cap_add` of the five | ||||||
| capabilities the entrypoint actually needs (CHOWN, SETUID, SETGID, FOWNER, | ||||||
| DAC_OVERRIDE) plus `no-new-privileges:true`. Removes NET_RAW, SYS_ADMIN, | ||||||
| mount, and module-loading powers even during the brief root window. | ||||||
| - **Fully rootless:** `user: "99:100"` instead of PUID/PGID env vars, with | ||||||
| the host config dir pre-chowned to match. Container never runs as root. | ||||||
|
|
||||||
| ### CI/CD Security | ||||||
| - Trivy vulnerability scanning on every image build | ||||||
| - SARIF results uploaded to GitHub Security tab | ||||||
| - Dependabot monitoring for GitHub Actions and Docker base image updates | ||||||
| - CodeQL static analysis for Python code | ||||||
| - All GitHub Actions pinned to specific commit SHAs (not floating tags) | ||||||
| - Multi-arch builds with SBOM and build attestation | ||||||
|
|
||||||
| ### Application Security | ||||||
| - Outbound HTTP is limited to the configured Lidarr API (opt-in); the | ||||||
| Lidarr API key is sent via the `X-Api-Key` header (never in URLs), | ||||||
| redirects are blocked, and the key is never logged | ||||||
| - ffmpeg arguments are list-based (no shell injection) | ||||||
| - Symlink boundary checking prevents directory traversal | ||||||
| - Handles credentials: the Lidarr API key (stored in `beatscheck.conf` | ||||||
| or a Docker secret, masked in WebUI responses) and WebUI logins | ||||||
| (PBKDF2-SHA256 hashed passwords + in-memory session tokens) | ||||||
| - All file operations use safe patterns (atomic JSON writes) | ||||||
|
|
||||||
| ## Best Practices for Users | ||||||
|
|
||||||
| - Keep your container image updated (`docker pull ghcr.io/chodeus/beatscheck:latest`) | ||||||
| - Use read-only music mounts when running in report mode | ||||||
| - Set appropriate PUID/PGID for your environment | ||||||
| - Restrict the `/config` directory permissions to the container user | ||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| name: "CodeQL" | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ "main" ] | ||
| paths: | ||
| - '**/*.py' | ||
| - '.release-please-manifest.json' | ||
| - 'VERSION' | ||
| - '.github/workflows/codeql.yml' | ||
| pull_request: | ||
| branches: [ "main" ] | ||
| schedule: | ||
| - cron: '27 3 * * 1' | ||
|
|
||
| permissions: | ||
| contents: read | ||
| security-events: write | ||
|
|
||
| jobs: | ||
| analyze: | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 10 | ||
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
|
|
||
| - name: Initialize CodeQL | ||
| uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2 | ||
| with: | ||
| languages: python | ||
|
|
||
| - name: Perform CodeQL Analysis | ||
| uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Shorten the comment and remove the history from it.
The
**path instruction limits comments to navigation or instruction. It bans "why/history essays" and "before/after narrative". Line 4 explains a dated profile comparison from 2026-09-03, so it is a history note. Lines 23-24 also explain why a setting is absent. Replace each with a short instruction, or delete it.Proposed fix
As per path instructions: "No why/history essays, no before/after narrative".
📝 Committable suggestion
🤖 Prompt for AI Agents
Source: Path instructions