diff --git a/AGENTS.md b/AGENTS.md index 65cb1725d..bdd4d4fa3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -395,6 +395,10 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml - `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER` - AllowOnly owner scope value (sets default for `--allowonly-scope-owner`) - `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO` - AllowOnly repo name, requires owner (sets default for `--allowonly-scope-repo`) - `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY` - AllowOnly integrity level: `none`, `unapproved`, `approved`, `merged` (sets default for `--allowonly-min-integrity`) +- `MCP_GATEWAY_TLS_CERT` - Path to TLS server certificate PEM file; enables HTTPS when set together with `MCP_GATEWAY_TLS_KEY` (sets default for `--tls-cert`) +- `MCP_GATEWAY_TLS_KEY` - Path to TLS server private key PEM file; required when `MCP_GATEWAY_TLS_CERT` is set (sets default for `--tls-key`) +- `MCP_GATEWAY_CA_CERT` - Path to CA certificate PEM file for client certificate verification; enables mutual TLS (mTLS) when set alongside `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY` (sets default for `--tls-ca`) +- `MCP_GATEWAY_HMAC_SECRET` - Shared HMAC-SHA256 secret for request signing and replay protection; when set, requests to MCP handlers must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers (sets default for `--hmac-secret`) - `RUNNING_IN_CONTAINER` - Set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable **Note:** `PORT`, `HOST`, and `MODE` are not read by the `awmg` binary directly. However, `run.sh` does use `HOST` (default: `0.0.0.0`) and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly. @@ -471,6 +475,8 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml - **Auth**: `Authorization: ` header (plain API key per spec 7.1, NOT Bearer scheme) - **Sessions**: Session ID extracted from Authorization header value - **Stdio servers**: Containerized execution only (no direct command support) +- **mTLS**: Mutual TLS can be enabled with `--tls-cert`, `--tls-key`, and `--tls-ca` flags (or corresponding env vars) to require client certificates for all connections +- **HMAC request signing**: Set `--hmac-secret` (or `MCP_GATEWAY_HMAC_SECRET`) to require HMAC-SHA256 signed requests; protects against replay attacks using `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers ## Resources diff --git a/config.example.toml b/config.example.toml index b70a8a3cd..61fbd3507 100644 --- a/config.example.toml +++ b/config.example.toml @@ -176,6 +176,39 @@ args = [ # Useful when servers have ordering dependencies or for debugging startup issues # sequential_launch = false +# ============================================================================ +# Security: mTLS & HMAC Request Signing +# ============================================================================ +# These options are configured via CLI flags or environment variables, NOT +# directly in the TOML file. They are documented here for reference. +# +# TLS (one-way or mutual): +# --tls-cert Path to TLS server certificate PEM file (enables HTTPS) +# Env: MCP_GATEWAY_TLS_CERT +# --tls-key Path to TLS server private key PEM file (required with --tls-cert) +# Env: MCP_GATEWAY_TLS_KEY +# --tls-ca Path to CA certificate PEM file for client certificate +# verification — enables mutual TLS (mTLS) +# Env: MCP_GATEWAY_CA_CERT +# +# HMAC request signing: +# --hmac-secret Shared HMAC-SHA256 secret for request signing and replay +# protection. When set, requests to HMAC-protected MCP +# handler routes must include: +# X-MCP-Timestamp — Unix-second timestamp +# X-MCP-Nonce — unique per-request random nonce +# X-MCP-Signature — hex-encoded HMAC-SHA256 signature +# Common operational endpoints such as /health and +# /close are intentionally not HMAC-protected. +# Env: MCP_GATEWAY_HMAC_SECRET +# +# Example (run command): +# ./awmg --config config.toml \ +# --tls-cert /path/to/server.crt \ +# --tls-key /path/to/server.key \ +# --tls-ca /path/to/ca.crt \ +# --hmac-secret "$(openssl rand -hex 32)" + # ============================================================================ # Notes # ============================================================================ diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md index 94b745866..1e0ef91d4 100644 --- a/docs/ENVIRONMENT_VARIABLES.md +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -29,6 +29,10 @@ When running locally (`run.sh`), these variables are optional (warnings shown if | `MCP_GATEWAY_WASM_GUARDS_DIR` | Root directory for per-server WASM guards (`//*.wasm`, first match is loaded) | (disabled) | | `MCP_GATEWAY_GUARDS_MODE` | Guards enforcement mode: `strict` (deny violations), `filter` (remove denied tools), `propagate` (auto-adjust agent labels) (sets default for `--guards-mode`) | `strict` | | `MCP_GATEWAY_GUARDS_SINK_SERVER_IDS` | Comma-separated sink server IDs for JSONL guards tag enrichment (sets default for `--guards-sink-server-ids`) | (disabled) | +| `MCP_GATEWAY_TLS_CERT` | Path to TLS server certificate PEM file. When set together with `MCP_GATEWAY_TLS_KEY`, enables HTTPS. Sets default for `--tls-cert`. | (disabled) | +| `MCP_GATEWAY_TLS_KEY` | Path to TLS server private key PEM file. Required when `MCP_GATEWAY_TLS_CERT` is set. Sets default for `--tls-key`. | (disabled) | +| `MCP_GATEWAY_CA_CERT` | Path to CA certificate PEM file for client certificate verification. When set (requires `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY`), enables mutual TLS (mTLS). Sets default for `--tls-ca`. | (disabled) | +| `MCP_GATEWAY_HMAC_SECRET` | Shared HMAC-SHA256 secret for request signing and replay protection on MCP request endpoints (for example, `/mcp` and `/mcp/`). When set, those MCP requests must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers. Sets default for `--hmac-secret`. | (disabled) | | `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*,launcher:*`) | (disabled) | | `DEBUG_COLORS` | Control colored debug output (0 to disable, auto-disabled when piping) | Auto-detect | | `RUNNING_IN_CONTAINER` | Manual override; set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable | (unset) |