SECURITY.md

Security and deployment notes

Student Python execution

• Docker installs Bubblewrap and prlimit; the app runs as the unprivileged telearn account.
• Each public Python run gets a copied, size-limited project workspace and CPU/address-space/file/process limits. Child environments use an allowlist and do not inherit application tokens or admin credentials.
• RUNNER_ISOLATION_MODE=sandbox (the source default) additionally requires Linux user/PID/network namespaces and read-only system mounts, and fails closed if the host blocks namespace creation.
• At the owner's request, the Docker image explicitly sets RUNNER_ISOLATION_MODE=process to restore Python demos on Hugging Face, whose current host rejects unprivileged namespace creation. This mode runs a separate, resource-limited process as telearn, but provides no filesystem, network, or same-user process isolation. Environment filtering and temporary project copies are not a security sandbox. Set the mode back to sandbox on a compatible execution host.
• Uvicorn caps WebSocket frames at 1 MiB. Classroom sockets also have per-IP handshake and per-student message budgets; saved checkpoints/submissions have per-hour limits, cooldowns, a per-course quota, and a rolling retention cap.

Classroom storage

Defaults are configured in Dockerfile and may be changed with CLASSROOM_* environment variables. The database retains up to 100 checkpoints and 100 submissions per student per Lesson, with a 1 GiB active-data quota per course. Older versions are removed from the active SQLite history and Hugging Face repository tree.

Deleting a file from a Hugging Face repository's current tree does not rewrite earlier Git commits. Therefore these limits bound the active version set and current tree, but cannot strictly cap the repository's historical Git object storage. A hard lifetime storage cap requires moving classroom versions to bounded object storage or periodically archiving/recreating the repository; neither is performed automatically.

Browser security

The app sends CSP, COOP/COEP, X-Content-Type-Options, Referrer Policy, Permissions Policy, and HSTS (enabled in the Docker image). CodeMirror, JSZip, and Pyodide are served same-origin from exact package versions included during image build. The pinned pygame-ce wheel and its lockfile dependency closure are also vendored same-origin, with each wheel SHA-256 checked against Pyodide's lockfile during the image build. Google Fonts, the QR service, Appetize, and MakeCode remain explicit external sources. Student HTML remains inside an opaque-origin sandbox iframe.

After deployment, inspect the final public HTTPS response headers: Hugging Face's edge proxy must preserve or add HSTS and must not replace the application CSP with a weaker policy. Local source changes cannot prove what the edge returns.

Dependency scanning and lock files

Every Docker build resolves requirements.txt in a Python 3.11 build stage, generates a complete transitive lock with hashes, audits that resolved lock using pip-audit, then installs the runtime dependencies with --require-hashes. The generated lock is included in the image as /app/requirements.lock; it is build-specific rather than checked into source, so rebuilding later may select newer versions allowed by requirements.txt. GitHub Actions also runs pip-audit on pull requests and weekly when this repo is mirrored to GitHub; the canonical remote for this project is Hugging Face, which does not execute that GitHub workflow by itself.