Skip to content
Open
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
16 changes: 15 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,20 @@ jobs:
- name: No per-player data tracked in data/world/ (public repo)
run: python3 tests/test_world_no_player_data.py

# CC:Tweaked hands children a programmable computer with an HTTP API. Its
# stock rules allow every host, so any whitelisted player could make the
# server issue outbound requests anywhere. This gate keeps the lockdown
# deny-by-default and correctly targeted; liveness is proved separately on
# the droplet with tools/verify_cc_http.sh.
- name: In-game computers cannot call arbitrary hosts
run: python3 tests/test_cc_http_lockdown.py

# A parental control that is silently off is worse than one that is
# absent, and this repo shipped a month of documentation claiming the
# limiter was dead while it was running. Guard the control and the claim.
- name: Playtime limiter is present, wired and observable
run: python3 tests/test_playtime_limiter.py

# Generated and binary artefacts must not be tracked. A compiled .pyc for
# .github/scripts/server_health.py rode along for months because
# .gitignore had no __pycache__ rule, and `sync_client_pack.py --write`
Expand Down Expand Up @@ -212,7 +226,7 @@ jobs:
run: |
for f in gitops/deploy.sh gitops/install_gitops.sh bootstrap_droplet.sh harden_sshd.sh \
add_admin_user.sh server-audit.sh tests/test_droplet_hardening.sh \
alerts/security_alert.sh alerts/install_alerts.sh; do
alerts/security_alert.sh alerts/install_alerts.sh tools/verify_cc_http.sh; do
[ -f "$f" ] && bash -n "$f" && echo "OK $f"
done

Expand Down
59 changes: 59 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,46 @@ being corrected, and those are the ones most likely to save someone time later.
verify before anything goes back in. **No pack re-import required.**

### Security
- **In-game computers can no longer call arbitrary hosts.** CC:Tweaked ships
every child a programmable computer with an HTTP API, and its stock rules are
`deny $private` then `allow *`. Any whitelisted player could write four lines
of Lua and make the server issue outbound requests to anything on the
internet, including the DigitalOcean metadata endpoint. That is server-side
request forgery with a child at the keyboard, and it was reachable on the
live server.

The rules cannot be committed: they are Forge SERVER config, stored per-world
at `world/serverconfig/computercraft-server.toml`, and both `data/config/` and
`data/world/` are gitignored on purpose because tracking files the server
rewrites leaves the droplet worktree dirty and blocks `git pull --ff-only`.
So they are applied at every container start through itzg's
`PATCH_DEFINITIONS`, which has the useful property of re-asserting itself on
every boot rather than being an edit someone can undo by hand on the box.
See `data/patches/computercraft-http.json`.

**Player impact:** the built-in `pastebin` and `wget` programs now fail with
"domain not permitted" for every host. Allowing one host back is a single
entry above the catch-all deny.

**Verified locally against the pinned image before shipping**, by running
`mc-image-helper patch` over a seeded stock config and parsing the result.
That caught two format traps that would each have failed silently on the
droplet with CI green: a file in a `PATCH_DEFINITIONS` *directory* must be a
PatchDefinition (`file` + `ops`) and not a PatchSet (`patches: [...]`), and it
must be strict JSON, because `--json-allow-comments` applies to the files
being patched and not to the definition itself. Both are now CI failures and
are written up in `data/patches/README.md`.

Note the patcher rewrites TOML in a flattened single-quoted form rather than
`[[http.rules]]` blocks. Both are valid TOML, but it means grepping for
`host = "*"` finds nothing, so `tools/verify_cc_http.sh` parses the TOML
properly instead of pattern-matching it.

**Still not verified on the droplet.** Local proof is that the patch applies
and produces correct rules; only reading the effective config inside the
running container proves it applied there. Run `tools/verify_cc_http.sh` after
the first deploy carrying this change.

- **Removed unused base-image binaries and upgraded OpenSSL** (`Dockerfile`).
`gosu` (22 Trivy findings) only runs when the container starts as root, and
this one runs as uid 1000. `restify` (8) is only used for Bukkit/Spigot.
Expand Down Expand Up @@ -84,6 +124,25 @@ being corrected, and those are the ones most likely to save someone time later.
droplet; see `alerts/`. [#25, #26]

### Fixed
- **The daily playtime limiter was never actually off, and this repo said it
was for a month.** #21 deleted the Windows `playtime_limit.ps1` and wrote
"there is currently no time limit of any kind" into DEPLOY.md and this
changelog. That conflated two different limiters: the KubeJS one,
`data/kubejs/server_scripts/playtime_limit.js`, was added 2026-07-20 and has
been tracked, mounted and loading on every boot the whole time.

A parent told no parental control exists goes looking for another way to
limit their child, or concludes the server is unsuitable. Being wrong in the
alarming direction is still being wrong.

The root cause was not the deletion, it was that nothing was observable. The
limiter now announces itself on load (`[playtime] limiter ACTIVE ...`, so
`docker logs minecraft-java | grep playtime` answers the question), and any
player can run `/playtime` to see their usage and remaining time. Ops, who
are exempt and whose own numbers prove nothing, see the limiter's configured
state instead. DEPLOY.md now carries a dated correction, and
`tests/test_playtime_limiter.py` fails if the claim is reintroduced.

- Health check and security alerts rebuilt around zero false positives. Three
collectors fired during normal operation, one of which (`RestartCount > 0`)
would have alerted on **every run forever** after any deploy, because that
Expand Down
48 changes: 36 additions & 12 deletions DEPLOY.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,21 +100,45 @@ with a cron job instead:
tar czf ~/mc-backup-$(date +\%F).tgz -C ~/minecraft/data world ops.json whitelist.json server.properties
```

> ### Daily playtime limits are NOT running
> ### Daily playtime limits: what is actually running
>
> There used to be a Windows script (`playtime_limit.ps1`) that read each kid's
> `play_time` from the server stats, and once they passed a daily cap (default
> 120 minutes) removed them from the whitelist, which `ENFORCE_WHITELIST` turns
> into an instant kick. It put them back at the next day rollover.
> **CORRECTION (2026-09-09).** This section previously said "no time limit of any kind."
> That was wrong, and had been wrong since 2026-08-15. Read this before trusting
> either claim.
>
> It only ever worked against a local Windows host and has not run since the move
> to the droplet. It was deleted rather than left in the repo pretending to be a
> control that was actually switched off.
> Two different limiters existed. The Windows one, `playtime_limit.ps1`, read
> each kid's `play_time` from the server stats and removed them from the
> whitelist past a daily cap, which `ENFORCE_WHITELIST` turns into an instant
> kick. It only ever worked against a local Windows host, never ran on the
> droplet, and was correctly deleted in #21.
>
> **So there is currently no time limit of any kind.** If you want one back, it
> needs writing for Linux: a cron job every few minutes calling
> `docker exec minecraft-java rcon-cli` to read stats and adjust the whitelist.
> The original logic is in git history if it is ever wanted as a starting point.
> The KubeJS one, `data/kubejs/server_scripts/playtime_limit.js`, was added
> 2026-07-20 and has been tracked and mounted the whole time. #21 deleted the
> PowerShell script and declared there was no limit at all, conflating the two.
> `data/` is bind-mounted to `/data` and KubeJS reads `server_scripts/` from
> there, so this script loads on every boot.
>
> **What it does.** Counts each player's seconds in `persistentData`, warns at
> 10, 5 and 1 minutes remaining, and kicks at zero. Resets on the local date
> rolling over in the server timezone, so no external scheduler is involved.
> Ops are exempt, checked live against `ops.json`. The cap is
> `data/kubejs/config/playtime_limits.json`: `default_minutes` for everyone,
> `players` for per-child overrides, `exempt` for non-ops with no cap.
>
> **How to check it is running**, so nobody has to take this document's word
> for it again:
>
> ```bash
> docker logs minecraft-java 2>&1 | grep playtime
> # expect: [playtime] limiter ACTIVE - default 120 min/day, ...
> ```
>
> In game, any player can run `/playtime` for their own usage and remaining
> time. An op sees the limiter's configured state instead, because ops are
> exempt and their own numbers would prove nothing.
>
> After editing the config, apply it with `/kubejs reload server_scripts` or
> restart the container. The config is read once at script load.

## Later: add a domain

Expand Down
40 changes: 40 additions & 0 deletions data/kubejs/server_scripts/playtime_limit.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@
const LocalDate = Java.loadClass('java.time.LocalDate')
const CONFIG = JsonIO.read('kubejs/config/playtime_limits.json') || { default_minutes: 120, exempt: [], players: {} }

// Announce on load. DEPLOY.md and the CHANGELOG both claimed for a month that
// there was "no time limit of any kind" while this script was tracked, mounted
// and running, because the Windows playtime_limit.ps1 was deleted at the same
// time and the two got conflated. Nothing in the server output said either way.
// This line is how anyone checks in future: `docker logs minecraft-java | grep playtime`.
console.info('[playtime] limiter ACTIVE - default ' + CONFIG.default_minutes
+ ' min/day, ' + ((CONFIG.exempt || []).length) + ' exempt, '
+ Object.keys(CONFIG.players || {}).length + ' per-player override(s). Ops are always exempt.')

function limitSecondsFor(player) {
if (player.isOp()) return -1 // ops are always unlimited, checked live against ops.json - no config needed
const username = player.username
Expand Down Expand Up @@ -44,3 +53,34 @@ PlayerEvents.tick(event => {
player.kick(Text.red("Your playtime for today is up! Come back tomorrow."))
}
})

ServerEvents.commandRegistry(event => {
const { commands: Commands } = event
event.register(
Commands.literal('playtime')
.executes(ctx => {
const player = ctx.source.player
if (!player) return 0

const limitSeconds = limitSecondsFor(player)
const used = player.persistentData.getInt('ptSeconds')
const usedMin = Math.floor(used / 60)

if (limitSeconds < 0) {
// Ops and exempt players have no cap, so their own numbers say
// nothing about whether the limiter works. Report its state
// instead: this is the admin answer to "is it actually on?".
player.tell(Text.gold('Playtime limiter: ACTIVE'))
player.tell(Text.white('- You are exempt, so no cap applies to you.'))
player.tell(Text.white('- Default cap for everyone else: ' + CONFIG.default_minutes + ' minutes per day.'))
player.tell(Text.white('- You have played ' + usedMin + ' minute(s) today.'))
return 1
}

const remainingMin = Math.max(0, Math.ceil((limitSeconds - used) / 60))
player.tell(Text.gold('You have played ' + usedMin + ' minute(s) today.'))
player.tell(Text.white(remainingMin + ' minute(s) left before the daily limit.'))
return 1
})
)
})
57 changes: 57 additions & 0 deletions data/patches/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Startup config patches

Files here are applied by `mc-image-helper patch` at every container start, wired
through `PATCH_DEFINITIONS: "/data/patches"` in `docker-compose.yml`.

## Two format rules, both learned the hard way

Both of these fail **silently in effect**: the patch is rejected at startup, the
server boots with stock config, and CI stays green. Local testing against the
pinned image caught both before they reached the droplet.

1. **A file in this directory must be a PatchDefinition, not a PatchSet.**
PatchDefinition is `{"file": ..., "ops": [...]}`. The `{"patches": [...]}`
wrapper is a PatchSet and is only valid when `PATCH_DEFINITIONS` points at a
single file rather than a directory. Getting it wrong produces
`Unrecognized field "patches"`.

2. **No comments. Not even `//`.** `mc-image-helper patch --help` advertises
`--json-allow-comments` defaulting to true, but that applies to the files
being *patched*, not to the definition read from this directory. A `//` line
here produces `ALLOW_COMMENTS not enabled for parser`. That is why this
README exists instead of comments in the JSON.

Verify a change applied by re-reading the effective file inside the container,
which is what `tools/verify_cc_http.sh` does. Never assume a patch landed.

## computercraft-http.json

Locks CC:Tweaked's HTTP API down to deny-by-default.

**What it closes.** Children write and run arbitrary Lua on this server.
CC:Tweaked's stock rules are `deny $private` then `allow *`, so any whitelisted
player could make the SERVER issue outbound HTTP to any host on the internet.
That is server-side request forgery with a child at the keyboard.

**Why a patch and not a committed config file.** CC:Tweaked's HTTP rules are
Forge SERVER config, stored per-world at
`world/serverconfig/computercraft-server.toml`. Both `data/config/` and
`data/world/` are gitignored deliberately: tracking files the server rewrites
leaves the droplet worktree permanently dirty and makes `git pull --ff-only` in
`gitops/deploy.sh` abort every run. So the rules cannot be committed. Patching at
startup also re-asserts them after any manual edit on the box.

**Rule order matters.** CC:Tweaked evaluates `http.rules` top to bottom, first
match wins. The private-range denies come first, then the catch-all deny.
`$private` already covers loopback, RFC1918 and link-local; the explicit CIDRs
are belt-and-braces in case `$private` is unsupported on a future version, and
because `169.254.169.254` is the cloud metadata endpoint on this DigitalOcean
droplet and deserves to be named.

**`http.enabled` stays true on purpose**, so a denied request returns a readable
"domain not permitted" instead of the confusing "http is disabled".

**Functional tradeoff, accepted deliberately.** The built-in `pastebin` and
`wget` programs now fail for every host. To allow one host back, insert a single
`{host, action: allow}` entry **above** the catch-all deny. That is also how the
Instructor Terminal gets its one allowed origin.
58 changes: 58 additions & 0 deletions data/patches/computercraft-http.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
{
"file": "/data/world/serverconfig/computercraft-server.toml",
"ops": [
{
"$set": {
"path": "$.http.enabled",
"value": true
}
},
{
"$set": {
"path": "$.http.websocket_enabled",
"value": false
}
},
{
"$set": {
"path": "$.http.max_requests",
"value": 8
}
},
{
"$set": {
"path": "$.http.rules",
"value": [
{
"host": "$private",
"action": "deny"
},
{
"host": "127.0.0.0/8",
"action": "deny"
},
{
"host": "10.0.0.0/8",
"action": "deny"
},
{
"host": "172.16.0.0/12",
"action": "deny"
},
{
"host": "192.168.0.0/16",
"action": "deny"
},
{
"host": "169.254.0.0/16",
"action": "deny"
},
{
"host": "*",
"action": "deny"
}
]
}
}
]
}
7 changes: 7 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,13 @@ services:
# Wipe mods not in the list above on each boot, so version bumps replace
# cleanly instead of leaving a stale jar behind (a classic mismatch cause).
REMOVE_OLD_MODS: "TRUE"

# CC:Tweaked HTTP lockdown. In-game computers could otherwise make the
# SERVER issue outbound HTTP to any host on the internet, which is SSRF
# with a child at the keyboard. The rules live in the per-world server
# config, which is gitignored and cannot be committed, so they are applied
# here at every container start instead. See data/patches/ for the why.
PATCH_DEFINITIONS: "/data/patches"
# Raised for Ad Astra, which adds five dimensions (Moon, Mars, Venus,
# Mercury, Glacio) on top of Terralith and When Dungeons Arise.
# 5G heap inside a 6.5g container cap, NOT 6G. A JVM needs meaningful
Expand Down
Loading
Loading