203 lines
9.3 KiB
Markdown
203 lines
9.3 KiB
Markdown
# To Do
|
|
|
|
Planned work, in order of priority. Each item names what to build, how it fits
|
|
the existing seams, and how to verify it. Finished items move to the design doc
|
|
they belong to.
|
|
|
|
## 1. Network access control (ACL)
|
|
|
|
The next feature push. Today a listener decides *who* a peer is (`tls`, `auth`);
|
|
nothing decides *where* a peer may connect from, and every limit except SCRAM
|
|
throttling is global. The ACL adds address rules and per-client limits at the
|
|
connection level, below TLS, so a refused peer costs no handshake.
|
|
|
|
### 1.1 One seam: a filtering listener
|
|
|
|
- New package `internal/netacl`, the third network seam beside `tlsx` and
|
|
`authz` (AGENTS.md lists the seams; add it there).
|
|
- `netacl.New(opts *config.ACLOptions, role) (*Policy, error)` compiles the
|
|
block; a nil policy is valid and transparent, like `authz`.
|
|
- `(*Policy).Listener(ln net.Listener) net.Listener` wraps the raw listener
|
|
before TLS:
|
|
- TCP plugins wrap it before `tls.NewListener`.
|
|
- HTTP plugins wrap it before `Serve`/`ServeTLS`.
|
|
- `Accept` reads an optional PROXY header (1.2), decides allow or deny (1.3),
|
|
applies per-address connection caps (1.4), and returns a `net.Conn` whose
|
|
`RemoteAddr` is the real client.
|
|
- Everything downstream then sees the real client with no further change:
|
|
`authz.remoteIP`, SCRAM throttling, sessions, logs and `http.Request.RemoteAddr`.
|
|
- Keep the proxy's own address as `peer_addr` in session metadata for audit.
|
|
- A denied connection is closed before any byte is read or written, with a
|
|
counter (`acl_denied`) and a rate-limited WARN.
|
|
|
|
### 1.2 PROXY protocol (deferred gap of SCRAM, see scram-auth-plan.md)
|
|
|
|
- Why: behind an L4 proxy that passes TLS through (nginx `stream` with
|
|
`ssl_preread`, HAProxy `mode tcp`), every peer arrives from the proxy's
|
|
address.
|
|
- All peers share one SCRAM throttling budget, so one client can lock out
|
|
every login.
|
|
- Logs, sessions and the ACL itself see only the proxy.
|
|
- What: accept PROXY v1 (text) and v2 (binary) headers, but only from
|
|
`proxy_from` addresses or CIDRs. Two config keys in the ACL block:
|
|
- `proxy_protocol = "off" | "optional" | "required"`, default off.
|
|
- `proxy_from = [...]`.
|
|
- Rules:
|
|
- A listed peer must send the header when `required`.
|
|
- An unlisted peer that sends a header is refused, since the header is
|
|
spoofable.
|
|
- The header must arrive within a short deadline (reuse
|
|
`tlsx.HandshakeTimeout`), with a size cap: v1 at most 107 bytes, v2 with a
|
|
bounded TLV length.
|
|
- `LOCAL`/`UNKNOWN` commands (proxy health checks) keep the socket address.
|
|
- TLVs are ignored.
|
|
- The header precedes the TLS ClientHello, so SCRAM channel binding is
|
|
unaffected: LogWisp still terminates TLS.
|
|
- nginx side:
|
|
- In the `stream` server, `proxy_protocol on` on the route to LogWisp (it
|
|
sends v1).
|
|
- HAProxy: `send-proxy` or `send-proxy-v2`.
|
|
- Relation to `auth.trusted_proxies` (HTTP proxy mode):
|
|
- That list trusts `X-Forwarded-For` from a TLS-terminating L7 proxy;
|
|
`proxy_from` trusts a PROXY header from an L4 proxy.
|
|
- Keep both, with distinct names and docs. They answer different layers, and
|
|
one deployment can use both: nginx `stream` with `proxy_protocol` into an
|
|
nginx `http` block that sets `X-Forwarded-For $proxy_protocol_addr`.
|
|
|
|
### 1.3 Address rules
|
|
|
|
- `allow = [CIDR...]`, `deny = [CIDR...]`, IPv4 and IPv6 (strict per family,
|
|
as the listeners are).
|
|
- Order: deny wins, then allow; an empty allow list admits everyone not denied.
|
|
- Rules match the real client (after PROXY), never the proxy.
|
|
- In HTTP proxy mode, `X-Forwarded-For` is applied by `authz.ClientAddr` after
|
|
the connection-level decision.
|
|
- Address rules for forwarded HTTP clients therefore belong in a second,
|
|
request-level check inside `authz.ClientAddr`: reuse the compiled `netacl`
|
|
rules there rather than duplicating them.
|
|
- Startup warnings (in `LogStartup` style): an allow list containing
|
|
`0.0.0.0/0` or `::/0`, `proxy_from` covering public ranges, a listener on a
|
|
wildcard host with no `allow`.
|
|
|
|
### 1.4 Per-client limits
|
|
|
|
- Generalize the SCRAM limiter in `internal/authz/scram.go` (token bucket per
|
|
key, bounded table that fails closed, idle sweep, IPv6 per /64 via
|
|
`throttleKey`) into the shared per-key limiter. One mechanism (AGENTS.md):
|
|
SCRAM throttling then uses it too.
|
|
- Keys:
|
|
- `max_connections_per_client` on every listener (concurrent connections per
|
|
address).
|
|
- `requests_per_second_per_client` on HTTP listeners (ingest, stream and
|
|
status requests).
|
|
- Later: per-identity limits once a peer is authenticated (the mtls plan's
|
|
deferred item 2), keyed by identity instead of address.
|
|
|
|
### 1.5 Config, validation, docs
|
|
|
|
- Config shape: `[...config.acl]` beside `tls` and `auth` on the four listener
|
|
plugins.
|
|
- Decode through `config.Scan`, so unknown keys fail.
|
|
- Dialers have no ACL block.
|
|
- Intent rule as in `authz`: an ACL key on a dialer, or `proxy_from` without
|
|
`proxy_protocol`, is an error.
|
|
- Stats: `acl_denied`, `acl_proxy_headers`, `acl_limited`, merged into the
|
|
plugin stats like `authz.Stats`.
|
|
- Docs: a security.md section, plus networking.md troubleshooting lines for
|
|
each refusal.
|
|
|
|
### 1.6 Verification
|
|
|
|
- Go tests, one per rule:
|
|
- PROXY v1 and v2 parse, including malformed, oversized and slow headers.
|
|
- A header from an unlisted peer refused; `required` without a header
|
|
refused; `LOCAL` kept.
|
|
- Deny over allow; IPv6 rules.
|
|
- Per-client connection cap; the limiter table failing closed.
|
|
- The real client reaching SCRAM throttling and session metadata.
|
|
- `test/acl-test.sh`:
|
|
- A Go stub proxy that sends v1 and v2 headers in front of each listener
|
|
type.
|
|
- nginx `stream` with `proxy_protocol on` when nginx is installed.
|
|
- Denied and allowed clients; per-client SCRAM budgets behind one proxy
|
|
address.
|
|
|
|
## 2. Hardening review of `lixenwraith/config` and `lixenwraith/toml`
|
|
|
|
Both parse untrusted-shaped input (config files, environment, command line)
|
|
and were not reviewed with the auth work. Review them as `auth` was reviewed:
|
|
adversarial lenses, reproduction before belief, a fix per confirmed finding in
|
|
the library repository, then a dependency bump here.
|
|
|
|
- toml parser:
|
|
- Limits on nesting depth, key count, string and array length, and number
|
|
sizes.
|
|
- Behaviour on invalid UTF-8, duplicate keys and tables, dotted-key and
|
|
inline-table redefinition.
|
|
- Fuzz targets (`go test -fuzz`) seeded with the TOML test suite.
|
|
- config:
|
|
- The weakly typed decoder: string-to-number overflow, duration and size
|
|
parsing, the comma split into slices.
|
|
- `maxValueDepth` and `MaxValueSize`, environment and CLI precedence, and
|
|
unknown-key reporting.
|
|
- Files:
|
|
- `PreventPathTraversal`, symlink handling and the file-size cap.
|
|
- The watcher: polling, debounce, a file replaced by rename or symlink swap,
|
|
TOCTOU between stat and read.
|
|
- Errors: values must never echo secrets (a misplaced password in a config
|
|
value reported back in an error).
|
|
- Deliverables:
|
|
- Findings per library.
|
|
- Fuzz targets committed in the library repositories.
|
|
- A note in this repository's security.md once done.
|
|
|
|
## 3. Packaging: AUR, FreeBSD ports, Debian
|
|
|
|
The foundation exists:
|
|
- The `lw` binary name.
|
|
- `make install` with `DESTDIR`, `PREFIX` and `SYSCONFDIR`.
|
|
- The `doc/lw.1` manual.
|
|
- Service files in `deploy/package/`: systemd unit, sysusers, tmpfiles and the
|
|
FreeBSD rc.d script.
|
|
- Skeletons in `deploy/package/arch/` and `deploy/package/freebsd/`.
|
|
|
|
What remains:
|
|
|
|
- Releases:
|
|
- The repository has no tags, so versions come from `git describe` and fall
|
|
back to a commit hash. Tag releases `vX.Y.Z`.
|
|
- Publish source tarballs with checksums, and sign them.
|
|
- Module path:
|
|
- The module is `logwisp`, so `go install github.com/lixenwraith/logwisp/cmd/lw@latest`
|
|
does not work.
|
|
- FreeBSD's `USES=go:modules` and Debian's dh-golang expect the canonical
|
|
path.
|
|
- Rename the module to `github.com/lixenwraith/logwisp`: a mechanical
|
|
import rewrite in one commit.
|
|
- Name check before submission:
|
|
- Arch: `pkgfile -s lw` against the official repositories, and the AUR
|
|
package list for `lw` and `logwisp`.
|
|
- Already checked: Ubuntu 26.04 and 24.04 contents and the FreeBSD 15.1
|
|
ports tree ship no `bin/lw`.
|
|
- Arch (AUR): `deploy/package/arch/PKGBUILD` already has the source URL, the
|
|
Arch Go flags (`-trimpath -buildmode=pie -mod=readonly -modcacherw`),
|
|
`backup` for the config and `check()`. Remaining:
|
|
- the checksum of a tagged tarball in place of `SKIP`, and a maintainer;
|
|
- namcap, `.SRCINFO`, and publishing `logwisp` (optionally `logwisp-git`).
|
|
- FreeBSD: `deploy/package/freebsd/` already has `USES=go:1.27,modules`,
|
|
`USE_RC_SUBR=logwisp`, `USERS`/`GROUPS`, and a pkg-plist with the `.sample`
|
|
config and the manual. Remaining:
|
|
- `distinfo` (or `GH_TUPLE`), which needs the module rename and a tag;
|
|
- a real `MAINTAINER` and a `UIDs`/`GIDs` entry for `logwisp`;
|
|
- poudriere on 14.x and 15.x, then submission through Bugzilla
|
|
(`sysutils/logwisp`).
|
|
- Debian:
|
|
- Debian policy wants every Go dependency packaged; the four `lixenwraith`
|
|
libraries are not.
|
|
- Either package them too (dh-golang), or start with an `.deb` built by the
|
|
Makefile `install` target (nfpm or `dpkg-deb`) and a PPA, and move to the
|
|
archive later.
|
|
- Shell completion for bash, zsh and fish, installed by `make install`.
|
|
- A packaging CI job: build the AUR package in an Arch container and the port
|
|
in a FreeBSD VM, run `lw --version` and `make image-check`.
|