SECURITY.md

CrumbZeros TTYD + BashPanda + Crumbmissions

Version: 1.0
Status: RC0
Date: 2026‑02‑21

1. Scope

This document describes the security model for:

• CrumbZeros TTYD deployment (check.sh, test.sh, make.sh)
• BashPanda lessons (currently: Lesson 1 – “Protect your directory”)
• Crumbmissions server-side structure
• kruemelN user isolation on the Crumbforest server

It is written for:

• Local admins / operators
• NGOs / educators considering a fork
• Anyone reviewing the risk profile of TTYD‑based shell access for children (“Krümel”).

2. Security Objectives

1. Child safety first
2. No uncontrolled shell access from home or untrusted networks.

3. TTYD is only available in supervised, on‑site learning contexts.

4. Containment of damage

5. A compromised kruemelN session must not compromise:

   • the host OS,
   • other krümel accounts,
   • other services on the machine.

6. Minimal exposed surface

7. Publicly reachable services are strictly limited (HTTPS reverse proxy only).

8. TTYD itself does not listen on public interfaces.

9. Transparent, reproducible security

10. All security measures are implemented as scripts in the repo.

11. check.sh, test.sh, make.sh and security_check.sh document the effective state.

12. Conscious risk (“Passkante”)

13. TTYD is explicitly treated as a “high‑value target”.
14. The project does not pretend there is zero risk; instead it documents:
    • what is mitigated,
    • what remains as intentional, supervised risk.

3. High‑Level Architecture

• Users
• kruemel1, kruemel2, … (number configurable via NUM_KRUEMEL).

• All in group crumbforest.

• User isolation

• Home directories: /home/kruemelN
• Permissions: 700 (owner only).
• Dedicated practice directory: /home/kruemelN/mein_verzeichnis (700).

• Welcome + training files with restrictive perms (600).

• TTYD

• One systemd service per user: ttyd-kruemelN.service.
• Each binds to a local port (e.g. 7681–7685) on 127.0.0.1.
• su -l kruemelN used to enter the user shell.

• Additional TTYD credential (--credential user:password) per service.

• Reverse proxy

• Nginx vhost: ttyd.crumbforest.com.
• HTTPS with Let’s Encrypt certificates.
• One location /kruemelN block per user.

• auth_basic with per-user .htpasswd-kruemelN.

• Security tooling

• check.sh – current state (“Was ist im Wald?”).
• test.sh – feature validation (“Was soll neu?”).
• make.sh – deployment (“wuuuhuuu!”).

• security_check.sh – firewall, port bindings, fail2ban, SSL, auth.

• AI / RAG

• Ollama + Qdrant run locally for Crumbforest AI use.
• Access is via dedicated applications / browser workflows, not via TTYD.

4. Threat Model & Assumptions

4.1 In‑Scope Threats

• A krümel (or someone sitting at a krümel workstation) tries to:
• access another krümel’s files,
• escalate privileges on the host,
• break out of their shell environment,

• access TTYD without credentials via the public URL.

• Automated attacks from the internet:

• Bots scanning ttyd.crumbforest.com,
• brute‑force attempts on HTTP Basic Auth,
• misuse of open ports if misconfigured.

4.2 Out‑of‑Scope / Assumptions

• The physical environment is supervised:
• children are on‑site, in the container / classroom,

• at least one adult crew member is present.

• The host OS is properly maintained by admins:

• regular security updates,
• restricted sudo / root access,

• no additional, unknown services opened to the internet.

• This is not a multi‑tenant, hostile cloud environment.
  It is a pedagogical lab with strict network rules and physical control.

5. Security Controls

5.1 Network & Firewall

• ufw (Uncomplicated Firewall) enabled:
• Only necessary ports open (80/443, SSH as configured).

• TTYD ports (7681–7685 by default) must not be opened in UFW.

• TTYD services bind to 127.0.0.1 only
  → No direct external access to TTYD, only via nginx reverse proxy.

• HTTPS enforced:

• HTTP (:80) redirects to HTTPS (:443).
• TLS certificates managed by Let’s Encrypt.

5.2 Authentication & Access Control

1. HTTP Basic Auth (nginx)
2. Each /kruemelN location is protected by auth_basic.

3. Credentials stored in per‑user .htpasswd-kruemelN files under /etc/nginx/auth.

4. TTYD credentials

5. Each TTYD service is configured with --credential user:password.

6. Ensures TTYD itself requires authentication even if nginx is misconfigured.

7. System accounts

8. kruemelN system users with individual home directories.
9. No sudo rights for krümel accounts.

10. Group crumbforest used for pedagogical sharing patterns, not privilege escalation.

11. Directory permissions

12. Home directories: 700 (only owner can access).
13. Practice directory mein_verzeichnis: 700.
14. Sensitive files (like willkommen.txt, future configs): 600.

5.3 Process Isolation

• One systemd service per TTYD instance:
• Service restarts automatically on failure.

• Clear audit trail via journalctl -u ttyd-kruemelN.

• Shell runs under the kruemelN user context:

• No shared shell between users.
• If one account is misused, impact is limited to that account.

5.4 Logging & Monitoring

• Nginx access and error logs for:
• login attempts,

• unusual patterns or high volume.

• Systemd logs for TTYD services.

• security_check.sh:

• Verifies firewall status, port bindings, fail2ban, certificate validity,
• Detects insecure configurations (e.g. TTYD bound to 0.0.0.0, missing auth).

Operators are encouraged to:

• Run ./check.sh and ./security_check.sh regularly.
• Set up cron or external monitoring where possible.

5.5 Bruteforce Protection

• fail2ban recommended and supported:
• sshd jail for SSH brute‑force.
• nginx / http‑auth jail for repeated login failures.

If fail2ban is not installed or not running, security_check.sh will warn.

6. Conscious Risks (“Passkante”)

TTYD in the browser is intentionally treated as a Passkante:

A boundary where learning value and technical risk meet,
and where errors become teaching moments – not silent failures.

We deliberately do not pretend that web‑based shells are risk‑free.
Instead we:

• restrict usage to supervised on‑site sessions,
• restrict user privileges (no sudo),
• restrict network exposure (local bind + firewall + proxy),
• document the risks clearly.

6.1 Known Risks

• If nginx and firewall are misconfigured, a TTYD port could be exposed.
• If krümel credentials are re‑used elsewhere, attackers might try them on other systems.
• If NUM_KRUEMEL and service definitions drift apart, some users may have accounts but no UI access (or vice versa).

6.2 Not Supported / Must Not Be Done

The Crumbforest / CrumbZeros design explicitly forbids:

• Exposing TTYD directly to the internet on 0.0.0.0.
• Granting krümel users sudo privileges or access to sensitive system files.
• Using this deployment as a generic “shell provider” for the public.
• Running this stack in an unsupervised, home‑use setting for children.

These limitations are part of the ethical and pedagogical core of the project.

7. Operational Practices

Recommended ops checklist:

1. Before first deployment
2. Review and adjust NUM_KRUEMEL and port ranges.
3. Ensure ufw is active and default‑deny for incoming connections.
4. Install fail2ban and enable at least sshd and nginx auth jails.

5. Obtain valid TLS certificates for ttyd.crumbforest.com.

6. Deployment

7. Run sudo ./check.sh to see the current state.
8. Run sudo ./test.sh to validate prerequisites.
9. Run sudo ./make.sh to deploy.

10. Run sudo ./security_check.sh to confirm secure state.

11. After deployment

12. Change or rotate initial passwords stored in passwords.txt.
13. Test access via browser and via curl (expect 401 without credentials).

14. Verify that krümel can only see their own home directories.

15. Ongoing

16. Apply OS security updates regularly.
17. Renew TLS certificates (Let’s Encrypt auto‑renew or manual).
18. Monitor logs for anomalies (nginx, TTYD, fail2ban).
19. Periodically re‑run security_check.sh.

8. For Forks and NGOs

If you fork this repository for another context (school, NGO, maker space):

• Keep the structure, adapt the names.

• You can rename kruemel users, but keep:

  • per‑user system accounts,
  • 700 home directories,
  • per‑user TTYD instances and credentials.

• Keep the boundary conditions.

• On‑site, supervised use only.
• No dual‑use as “public shell” service.

• No escalation to security / surveillance tooling.

• Document your own adaptations.

• If you relax or change any security controls,
  clearly document:
  • why you did it,
  • what risks you accept,
  • who is responsible.

9. Reporting & Contact

This project is operated in the spirit of:

“Präzision über Geschwindigkeit.
Verstehen über Quick‑Fix.
Atmen vor Ausführen.”

If you discover a security issue or have improvements:

• Open an issue in the repository (if appropriate), or
• Contact the maintainer / crew via the channels provided in the main README.

When reporting, please include:

• Steps to reproduce,
• Affected components (TTYD, nginx, scripts, etc.),
• Any logs or configurations that help to understand the issue.

10. Summary

• TTYD is intentionally used as a learning boundary, not a generic remote shell.
• The design focuses on local, supervised, offline‑first education.
• Security is implemented via:
• network isolation (127.0.0.1, UFW),
• multiple auth layers (nginx + TTYD),
• OS user isolation (per‑user accounts, 700 perms),
• logging, monitoring and scripted checks.

Security here is not a marketing claim;
it is a living practice that grows with the forest.

wuuuhuuu 🐼🌲