Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# .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
# Keep assertive: chill misses Major findings in this repo. The "**" rule filters style nits.
profile: "assertive"
request_changes_workflow: false
pre_merge_checks:
Expand Down Expand Up @@ -39,7 +39,7 @@ reviews:
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. The ONLY session-free pass is _AUTH_OFF, which
authorized path. The ONLY session-free pass is _AUTH_OFF, which
_load_auth() returns solely for the exact {"login": "off"} content;
any other unexpected content must stay _AUTH_UNREADABLE. Turning the
login off (/api/auth/disable) needs a session, the current password,
Expand Down Expand Up @@ -171,6 +171,8 @@ reviews:
spaces.
- Preserve correct PUID/PGID drop (default 99:100) and UMASK; do not run
the delete/scan Python as root.
- entrypoint.sh unsets TZ when /etc/localtime is a mounted file: libc
reads TZ (the image sets UTC) first, so keeping it ignores the mount.
- No secrets echoed or baked into the script or its logs.
- rescan.sh accepts only report/move modes and writes .rescan as PUID
via mkstemp + os.replace, so a symlink there is replaced, never
Expand Down Expand Up @@ -217,6 +219,8 @@ reviews:
- 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.
- Pass a called workflow only the secrets it declares, by name; never
`secrets: inherit`. Checkouts set persist-credentials: false.
- 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
Expand Down
2 changes: 1 addition & 1 deletion .github/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**: for a problem that can't be exploited, open a GitHub issue marked `[SECURITY]`

Please do **not** open a public issue for security vulnerabilities that could be exploited.

Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Initialize CodeQL
uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
Expand Down
16 changes: 11 additions & 5 deletions .github/workflows/docker-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ jobs:
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0
- id: count
run: |
Expand All @@ -37,15 +38,16 @@ jobs:
echo "date=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
} >> "$GITHUB_OUTPUT"

# Gate the image build/publish on lint + smoke tests so a broken push to
# main can't publish :latest. (CodeQL runs in its own workflow; enforce it
# as a required status check via branch protection.)
# Lint and tests gate the build, so a broken push to main can't publish :latest.
# CodeQL runs in codeql.yml; branch protection is what makes it required.
lint:
permissions:
contents: read
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
Expand All @@ -63,6 +65,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
Expand Down Expand Up @@ -92,7 +96,8 @@ jobs:
VCS_REF=${{ github.sha }}
VERSION=${{ github.ref_name }}
BUILD_NUMBER=${{ needs.build-number.outputs.number }}
secrets: inherit
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}

notify-failure:
needs: build
Expand All @@ -105,4 +110,5 @@ jobs:
status: failure
title: "❌ Docker build failed: ${{ github.ref_name }}"
commit_sha: ${{ github.sha }}
secrets: inherit
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
2 changes: 2 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
Expand Down
12 changes: 5 additions & 7 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,8 @@ jobs:
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}

# docker-publish.yml's tags:['v*'] trigger never fires: release-please pushes
# its tag with GITHUB_TOKEN, and GitHub runs no workflow for events raised by
# that token — so no release has ever produced a version-tagged image. Build it
# here instead, where release_created and the version are already known. The
# push-triggered build cannot do it: it starts in the same second as this
# workflow, before the tag exists.
# The version-tagged image is built here: a tag pushed with GITHUB_TOKEN starts
# no workflow, so docker-publish.yml's tag trigger never fires for a release.
version-tag-meta:
needs: release
if: needs.release.outputs.release_created == 'true'
Expand All @@ -39,6 +35,7 @@ jobs:
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0
- id: m
run: |
Expand All @@ -63,4 +60,5 @@ jobs:
VCS_REF=${{ github.sha }}
VERSION=${{ needs.release.outputs.tag_name }}
BUILD_NUMBER=${{ needs.version-tag-meta.outputs.build_number }}
secrets: inherit
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
8 changes: 4 additions & 4 deletions .github/workflows/repo-events.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Drop into .github/workflows/repo-events.yml of ANY repo.
# Fires Discord for: issue open/close, PR open/close/merge, release publish, discussion.
# Workflow-failure notifications are handled inline by the failing caller workflow (see caller-docker.yml).
# Discord posts for issues, PRs, discussions and manually published releases.
# release-please's releases post from release-please.yml: GITHUB_TOKEN events start no workflow.

name: Repo events

Expand All @@ -20,4 +19,5 @@ permissions:
jobs:
notify:
uses: chodeus/chodeus-ops/.github/workflows/repo-events.yml@6e15484f5348c9862408046b962fa7083ceeffeb # main
secrets: inherit
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
4 changes: 3 additions & 1 deletion .github/workflows/validate-workflows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,14 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Install actionlint
id: install
shell: bash
run: |
bash <(curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash)
bash <(curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash) 1.7.12
echo "exe=$PWD/actionlint" >> "$GITHUB_OUTPUT"

- name: Run actionlint
Expand Down
13 changes: 5 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ On first run, BeatsCheck creates `/config/beatscheck.conf` with all options and
| `output_dir` | `/corrupted` | Quarantine destination for move mode. Must match a mounted volume |
| `mode` | `setup` | `setup` (idle), `report`, `delete`, or `move`. Can be changed at runtime via `rescan` |
| `workers` | `4` | Parallel ffmpeg decode workers. 2 = conservative, 4 = balanced, 8+ = fast |
| `run_interval` | `0` | Hours between scans. `0` = run once and exit. `168` = weekly. `24` = daily |
| `run_interval` | `0` | Hours between scans. `0` = scan once, then stay idle until `rescan`. `168` = weekly. `24` = daily |
| `delete_after` | `0` | Days before corrupt files are auto-deleted. `0` = never (manual only). `7` = 7 day review window |
| `max_auto_delete` | `50` | Safety threshold — abort auto-delete if more than this many files would be removed. `0` = no limit |
| `min_file_age` | `30` | Skip files modified within this many minutes. Prevents flagging active downloads |
Expand Down Expand Up @@ -219,7 +219,7 @@ On the Configuration page, **Access → Turn off login** asks for your current p

### WebUI Security

- **Authentication required** — all API endpoints require a valid session (PBKDF2-SHA256 hashed passwords, HttpOnly session cookies), unless you chose **No login** or turned the login off. A damaged `webui_auth.json` keeps the WebUI locked, never open
- **Authentication required** — every API endpoint except setup, login, logout and the login status needs a valid session (PBKDF2-SHA256 hashed passwords, HttpOnly session cookies), unless you chose **No login** or turned the login off. A damaged `webui_auth.json` keeps the WebUI locked, never open
- **Login lockout** — 5 attempts per client within 15 minutes, then a 5-minute lockout. Behind a reverse proxy, set `WEBUI_TRUSTED_PROXIES` so each client gets its own lockout
- **Setup wizard** — on first access, create credentials (stored hashed in `/config/webui_auth.json`) or choose **No login**
- **Cross-site POSTs refused** — the API accepts only JSON POSTs, which a browser sends from another site only after a CORS check the WebUI never passes. This holds with the login off too
Expand All @@ -228,7 +228,7 @@ On the Configuration page, **Access → Turn off login** asks for your current p
- **Delete validation** — files must be in `corrupt.txt` and inside the music directory; symlinks rejected
- **Path traversal protection** — static file serving validates all paths against the static directory
- **API key masking** — Lidarr API key shown as `********` in the UI
- **No external dependencies** — built on Python stdlib only (no supply chain risk)
- **No third-party Python packages** — the WebUI uses only the standard library

**Important:** The WebUI is designed for trusted LAN / Docker bridge networks. For remote access, use a reverse proxy with HTTPS and authentication (Nginx, Caddy, Traefik). Do not expose the WebUI port directly to the internet.

Expand Down Expand Up @@ -329,12 +329,9 @@ Change the music mount to `rw`, then from the Unraid **terminal**:
docker exec -it BeatsCheck delete
```

**Option 3: Manual delete from corrupt.txt**
**Option 3: From the WebUI**

```bash
cat /mnt/user/appdata/beatscheck/corrupt.txt
while IFS= read -r f; do rm -v "$f"; done < /mnt/user/appdata/beatscheck/corrupt.txt
```
On **Corrupt Files**, select files or albums and click **Delete**. Each file is checked against `corrupt.txt` and the music directory. For an album, at least one flagged file must be in that album's folder before the whole folder is removed. Files Lidarr tracks are deleted through Lidarr; BeatsCheck removes the rest itself, so mount the music folder `rw` as in Option 2. Don't feed `corrupt.txt` to `rm` on the host: it lists paths as the container sees them (`/data/...`), not host paths.

### Unraid Notifications (Optional)

Expand Down
32 changes: 9 additions & 23 deletions compose.yaml
Original file line number Diff line number Diff line change
@@ -1,12 +1,5 @@
### BeatsCheck compose.yaml Example
### https://github.com/chodeus/BeatsCheck
###
### Usage:
### docker compose up -d # Start in background
### docker compose logs -f # Follow logs
### docker exec -it beatscheck delete # Interactive delete
### docker exec beatscheck rescan # Trigger rescan
###
### BeatsCheck compose.yaml example: https://github.com/chodeus/BeatsCheck
### docker compose up -d, then `docker exec beatscheck rescan` or `docker exec -it beatscheck delete`.
services:
beatscheck:
image: ghcr.io/chodeus/beatscheck:latest
Expand All @@ -18,7 +11,7 @@ services:
- /mnt/user/data:/data:ro
## Persistent config: logs, corrupt.txt, tracking data
- /path/to/config:/config
## Auto-detect host timezone (no TZ env var needed if mounted)
## Host timezone. While this is mounted it wins; TZ below applies only without it.
- /etc/localtime:/etc/localtime:ro
environment:
## Container user/group IDs and timezone
Expand All @@ -31,20 +24,14 @@ services:
# - WEBUI_TRUSTED_PROXIES=172.18.0.10
## All other settings (mode, workers, Lidarr, etc.) are configured in
## /config/beatscheck.conf — auto-created on first run.
## WebUI: uncomment to enable the web interface.
## Also set webui = true in /config/beatscheck.conf
## On first access you'll create login credentials via a setup wizard.
## To reset credentials: docker exec beatscheck reset-webui-password
## WARNING: Do not expose the WebUI port directly to the internet.
## Use a reverse proxy with HTTPS (Nginx, Caddy, Traefik) for remote access.
## WebUI: uncomment, and set webui = true in /config/beatscheck.conf.
## Never expose the port to the internet; for remote access, use an HTTPS reverse proxy with authentication.
# ports:
# - "8484:8484"
## Optional: limit CPU usage to avoid impacting other services
# cpus: 2
## Optional hardening: drop every capability, add back only the five
## the entrypoint actually needs (PUID/PGID remap + chown + su-exec),
## and block setuid escalation. Even during the brief root window at
## startup, the container has no NET_RAW, SYS_ADMIN, or mount powers.
## Optional hardening: only the five capabilities the entrypoint needs
## (PUID/PGID remap, chown, su-exec), and no setuid escalation.
# cap_drop:
# - ALL
# cap_add:
Expand All @@ -55,7 +42,6 @@ services:
# - DAC_OVERRIDE
# security_opt:
# - no-new-privileges:true
## Fully rootless alternative: replace PUID/PGID env with `user:` and
## pre-chown the host config dir (sudo chown -R 99:100 ./config).
## The entrypoint detects non-root invocation and skips the chown/su-exec.
## Fully rootless: replace PUID/PGID with `user:` and pre-chown the config dir
## (sudo chown -R 99:100 /path/to/config); the entrypoint then skips chown and su-exec.
# user: "99:100"
3 changes: 2 additions & 1 deletion scripts/entrypoint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ TZ=${TZ:-UTC}
# Timezone: if /etc/localtime is bind-mounted from host, use it as-is.
# Otherwise set it from the TZ env var.
if [ -f "/etc/localtime" ] && [ ! -L "/etc/localtime" ]; then
: # bind-mounted regular file from host
# libc reads TZ (the image defaults it to UTC) ahead of /etc/localtime.
unset TZ
elif [ -n "$TZ" ] && [ -f "/usr/share/zoneinfo/$TZ" ]; then
# Rootless cannot write /etc/localtime; TZ in the environment still applies.
ln -sf "/usr/share/zoneinfo/$TZ" /etc/localtime 2>/dev/null || true
Expand Down
Loading