salticidae.io
← Back to all articles
10 min readBy salticidae.io Security Team

Introducing Project Charlotte: A Security-Minded Rust Web Server

Introducing Project Charlotte: A Security-Minded Rust Web Server

Most web server hardening guides start with the same move: take a general-purpose server and switch things off. Disable modules you don't use, lower privileges after binding, fix permissions on config files, and bolt on a WAF and rate limiting. Project Charlotte starts from the other end. It's an asynchronous Rust web server, soon to be released, where those controls are part of the design rather than steps you add later.

Charlotte serves static sites and virtual-hosted applications. It can serve your static files, connect to or supervise FastCGI applications, run classic CGI scripts, inspect traffic with ModSecurity, terminate TLS, serve HTTP/3 over QUIC, and provision certificates with ACME. Run a single node.js app? Charlotte's got your back. Run a fleet of servers running untrusted content? Charlotte's got you, too. This post covers what it does and, more importantly for this blog, how it limits the damage when something goes wrong.

What it does

  • Static file serving with MIME types, index files, optional directory listings, try_files, byte ranges, and conditional requests.
  • YAML virtual hosts with exact and wildcard names, per-host document roots, and isolated worker processes that drop to configured user and group IDs, or transparent reverse proxies.
  • FastCGI over TCP or Unix sockets, with optional server-managed application pools that scale from zero, plus classic CGI.
  • Optional ModSecurity request and response inspection, with a ready-made OWASP Core Rule Set example.
  • TLS with SNI-based certificate selection, ACME HTTP-01 provisioning and renewal, and HTTP/3.
  • Hot reload of virtual-host files, plus a local configuration API so you can add or modify site configurations on the fly.

Getting a page on screen takes three commands:

mkdir -p public
printf '%s\n' '<h1>Hello from Charlotte</h1>' > public/index.html
cargo run -- --root public

The server listens on 127.0.0.1:8080 by default. One safety note worth repeating: the default document root is the current directory and listings are on by default, so point --root at a directory that contains only what you mean to publish, or add --no-listing.

Build only what you need

Every unused feature is attack surface. Charlotte's major subsystems are Cargo features: hosting, proxy, acme, and http3. All four are on by default, and you can leave any of them out. A TLS-terminating reverse proxy that gets its certificates through ACME and speaks HTTP/3, but hosts nothing itself, is one build command:

cargo build --release --no-default-features --features proxy,acme,http3

The important detail is what happens when your configuration asks for something the binary doesn't have. Charlotte refuses to start and names the missing feature instead of quietly ignoring the setting. A config that expects a virtual host with a document root won't silently turn into a 404 machine. project-charlotte --help lists the features a binary was built with, and scripts/check-features.sh checks that every feature combination compiles without warnings.

For Ubuntu, cargo-deb produces two packages: the full project-charlotte and the slimmer project-charlotte-proxy.

Privilege separation by default

This is the part of Charlotte I'm most excited about from a security standpoint. When started as root with --user (and optionally --group), the server splits into three kinds of process:

  1. The master handles requests as the unprivileged account. After the drop, its only remaining capability is CAP_NET_BIND_SERVICE (if it had it), so it can't change identity again or signal other accounts' processes.
  2. A small root helper does only the jobs that need privilege: opening log files, reading TLS certificate and key files, and starting and stopping virtual-host workers. It only starts the same binary in worker mode, never as UID 0, with a short environment allowlist, and keeps only CAP_DAC_OVERRIDE, CAP_SETUID, CAP_SETGID, and CAP_KILL.
  3. Per-vhost workers run each site as its own configured user, started on the first request and stopped after an idle timeout (300 seconds by default).

The helper is deliberately narrow. It works only inside directories fixed at startup: the ones holding configured log and TLS files, the ACME cache, and anything added with --log-dir or --tls-dir. It resolves paths with openat2(RESOLVE_BENEATH), so neither .. nor a symlink can leave those directories. It handles only regular files, refuses a final-component symlink, hands back append-only descriptors for logs, and returns only the parsed DER sections of certificates and keys rather than raw files.

The documentation is upfront about the residual risk. A compromised master can still append to logs and read PEM sections in the listed directories, and ask for a worker under any non-root account its configuration could already name, but nothing beyond that. Because a listed directory includes all its subdirectories, keep logs in a directory of their own: configuring /var/log/site.log lists all of /var/log.

Workers can also be placed in cgroup v2 groups with memory, CPU, and PID limits, globally or per virtual host:

options:
  worker_cgroup: charlotte/sites/{uid}/{name}
  worker_cgroup_memory_max: 512M
  worker_cgroup_cpu_max: 150%
  worker_cgroup_pids_max: 64

CGI scripts and FastCGI applications inherit the worker's cgroup, so a runaway PHP process can't starve the neighboring site.

Configuration files are trusted input, so they're checked

The main config, the --vhost-dir directory, and the files in it decide which accounts and programs the server runs. Charlotte refuses any of them that is not owned by root or by the server's account, that is world-writable, or that is group-writable by a group other than root's. Each file is checked and read through the same open descriptor, which closes the time-of-check/time-of-use gap where a file could be swapped between the permission check and the read.

--check-config validates the virtual-host YAML and reports errors with source locations, which fits well into a CI pipeline.

A local control API that fails closed

--control-socket exposes a small HTTP/1.1 JSON API over a Unix socket (mode 0600) for listing, creating, replacing, and deleting directory-backed virtual hosts. The charlotte-ctl binary wraps it:

charlotte-ctl list
charlotte-ctl put example example.yaml
charlotte-ctl delete example

Every change is validated against the complete virtual-host configuration, including duplicate names and worker setup, before Charlotte atomically writes the file and switches the running router. An invalid change leaves both the file and the live configuration untouched. The socket directory handling is careful too: Charlotte will tighten a directory it owns, but it won't take over a shared, non-empty directory such as /run. It fails with an explanation instead.

Edge defenses: rate limits, bot detection, and a WAF

Requests pass through a fixed sequence in the master: ACME challenge check, rate limit, bot detection, ModSecurity, then routing. Anything blocked early never reaches a worker, a script, or a proxied upstream.

Rate limiting (--rate-limit 20/s, with optional burst) returns 429 with Retry-After. IPv4 clients are tracked individually and IPv6 clients by /64, so rotating through a single allocation doesn't help an attacker. X-Forwarded-For is only honored from peers listed with --trusted-proxy. From anyone else it is stripped, which closes the usual spoofing hole in rate limits and access logs.

Bot detection scores each request and then allows it, challenges it, or blocks it:

  • Explicit allow and deny lists for IPs, user agents, and JA4 fingerprints.
  • Built-in rules that flag scanner user agents (sqlmap, nikto, nuclei, ffuf, and others), automation clients, and "browsers" missing headers a real browser would send.
  • JA4 TLS fingerprinting of the ClientHello, including checks for a Chrome user agent without GREASE values or a client that doesn't offer TLS 1.3. The fingerprint is also available in access logs as %{ja4}n.
  • Crawler verification through reverse and forward DNS, so a request claiming to be Googlebot from a random VPS adds 100 points.
  • Honeypot paths like /wp-login.php that ban the client for a configurable period.

Mid-range scores get a SHA-256 proof-of-work challenge instead of a hard block. Once solved, the client gets an HMAC-signed, HttpOnly, SameSite=Lax cookie tied to its IPv4 /24 or IPv6 /64. Practical advice straight from the docs: curl scores 50 and gets challenged by default, which will break health checks. Start with mode: log, read the logged reasons, add exemptions, and only then enforce.

mode: log
allow_ips: [192.0.2.0/24]
exempt_paths: [/health/, /api/]
honeypot_paths: [/wp-login.php]
honeypot_ban: 86400

The documented limitations are worth knowing before you rely on it. The signing key and bans live in memory, so a restart clears them. All virtual hosts share one key and one ban list. HTTP/3 and plaintext connections have no JA4 fingerprint. exempt_paths is a plain prefix match, so /health also exempts /healthcheck. User-agent and JA4 allow rules rely on values the client controls, so use allow_ips for anything that must never be challenged.

ModSecurity is part of every build. examples/modsecurity-crs.conf wires up the Debian/Ubuntu OWASP Core Rule Set packages directly, working around the packaged IncludeOptional that libmodsecurity doesn't support. Block status is configurable globally or per host.

Logging you can actually investigate with

Access logs follow Apache mod_log_config formats (common, combined, and custom strings), and error logs follow ErrorLogFormat. Both can be set per virtual host. Unsupported format directives are rejected at startup rather than silently dropped. Control characters in logged fields are escaped, CGI and FastCGI stderr is routed to the error log of the virtual host that ran the script, and bot-detection decisions are logged with their reasons:

bot detection: client=198.51.100.7:51234 score=50 action=Challenge reasons=["automation user-agent"]

Migrating from Apache or nginx

Two converters, apache2charlotte and nginx2charlotte, translate existing configurations into Charlotte's virtual-host YAML. They follow includes and globs, and every directive they can't convert is kept as a comment with its source location for manual review. --user-from-root sets each host's worker account to the owner of its document root. That's a convenient way to move a shared Apache box onto per-site identities without hand-editing dozens of hosts. Keep in mind that the converters are best-effort: they don't know your site's runtime behavior, so you should review the output and test it before deployment.

apache2charlotte /etc/apache2/apache2.conf --output charlotte-vhosts.yaml

Deployment

The Debian packages ship a systemd unit that runs the server as www-data via --user, with ProtectSystem=full, private /tmp and devices, a capability bounding set, and a system-call filter. The unit won't start until /etc/charlotte/charlotte.yaml exists, so a fresh install never comes up with a default configuration you didn't choose.

Tested like it handles hostile input

The project includes fuzz targets (documented in FUZZING.md), coverage through cargo tarpaulin, callgrind benchmarks with Gungraun, and feature-gated tests, so a reduced build is tested with the same flags it's built with. There's also a browser-driven live demo (demo/run.sh) with an optional headless validation mode.

What's next

Project Charlotte requires Rust 1.85 or newer (2024 edition). The release is coming soon, and we'll follow up here with deeper dives into the privilege-separation model, a bot-detection tuning walkthrough, and a migration guide for moving a real Apache site across. As with everything on this blog, start in log mode, read what your server is telling you, and tighten from there.

A note from salticidae.io Security Team, who writes about security, software, and operating internet services.