1# Security Hardening Controls
2
3This page summarizes Gordon's security-related configuration knobs and the defaults operators should know before exposing an instance.
4
5## Registry upload quotas
6
7Registry blob uploads are bounded by two limits under `[server]`:
8
9```toml
10[server]
11max_blob_chunk_size = "95MB"
12max_blob_size = "1GB"
13```
14
15- `max_blob_chunk_size` limits a single upload chunk.
16- `max_blob_size` limits the cumulative blob/layer upload size.
17- Exceeding either limit returns an OCI-compatible size error and the failed upload is cleaned up.
18
19## Admin logs permission
20
21Container and deploy logs can include environment-derived output. Gordon gates log access behind a dedicated scope:
22
23```bash
24gordon auth token generate --subject ops --scopes "admin:logs:read" --expiry 30d
25```
26
27- `/admin/logs` and deploy failure logs require `admin:logs:read`.
28- `admin:status:read` does not grant log access.
29- Common secret patterns are redacted before logs are returned.
30
31## Volume pruning scope
32
33Volume pruning only removes unused Docker volumes explicitly managed by Gordon (`gordon.managed=true`). It ignores unrelated Docker volumes even if they are unused.
34
35Use dedicated admin scopes:
36
37- `admin:volumes:read` for listing volumes.
38- `admin:volumes:write` for prune operations.
39
40## Pass migration plaintext handling
41
42When Gordon migrates legacy plaintext `.env` files into `pass`, it removes the plaintext source after a successful migration and does not leave `.env.migrated` copies by default. If pass entries already exist, migration fails closed and leaves the plaintext file in place for manual operator review rather than deleting potentially unique values.
43
44## External image registries
45
46Gordon's configured registry is always allowed. Explicit external registries must be allowlisted:
47
48```toml
49[images]
50allowed_registries = ["docker.io", "ghcr.io", "registry.example.com:5000"]
51require_digest = true
52```
53
54- Empty `allowed_registries` rejects explicit external registries.
55- `localhost`, loopback, private, link-local, unspecified, and metadata-style registries are rejected.
56- `require_digest = true` requires allowlisted external images to use `@sha256:<64 hex chars>`.
57- Include ports in allowlist entries when the registry uses a non-default port.
58
59## Docker network isolation
60
61Per-app Docker networks are enabled by default. To block direct external egress from isolated networks, opt into Docker internal networks:
62
63```toml
64[network_isolation]
65enabled = true
66internal = true
67```
68
69`internal = false` remains the compatibility default because some applications and attachments need direct egress during startup.
70
71## Container runtime profile
72
73```toml
74[containers]
75security_profile = "compat" # or "strict"
76```
77
78- `compat` preserves broad image compatibility while retaining `no-new-privileges` and default capability restrictions.
79- `strict` enables a read-only root filesystem, drops all capabilities, and only adds `NET_BIND_SERVICE`.
80
81Use `strict` for images designed to write only to mounted volumes and run without extra Linux capabilities.
82
83## Related
84
85- [Auth](./auth.md)
86- [Images](./images.md)
87- [Network Isolation](./network-isolation.md)
88- [Deploy](./deploy.md)
89- [Volumes](./volumes.md)
90- [Reference](./reference.md)