From ef761ea520dc1ec9c3798f45db688357d2784206 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:31:37 +0000 Subject: [PATCH 1/5] Initial plan From d1916af0a1b2b92b6dfc62d71d9e0f63493e86d8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:40:53 +0000 Subject: [PATCH 2/5] docs: add mTLS & HMAC request signing environment variables to documentation Agent-Logs-Url: https://github.com/github/gh-aw-mcpg/sessions/c5f47d0c-2f0d-427f-bdbd-98c0f8cc7774 Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com> --- AGENTS.md | 6 ++++++ config.example.toml | 30 ++++++++++++++++++++++++++++++ docs/ENVIRONMENT_VARIABLES.md | 4 ++++ 3 files changed, 40 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 65cb1725d..476ac408c 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, all requests 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..f0fea2b00 100644 --- a/config.example.toml +++ b/config.example.toml @@ -176,6 +176,36 @@ 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, all requests must include: +# X-MCP-Timestamp — Unix-second timestamp +# X-MCP-Nonce — unique per-request random nonce +# X-MCP-Signature — hex-encoded HMAC-SHA256 signature +# 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..2ae74ce2c 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. When set, all incoming 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) | From f271bda0a3d279885ec676f2e4701b702d19a85e Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Tue, 28 Apr 2026 09:40:42 -0700 Subject: [PATCH 3/5] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 476ac408c..bdd4d4fa3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -398,7 +398,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml - `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, all requests must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers (sets default for `--hmac-secret`) +- `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. From d6cd6b6d4a4c4fb4cf14bb7d50d5508f95d7fc89 Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Tue, 28 Apr 2026 09:40:52 -0700 Subject: [PATCH 4/5] Update config.example.toml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- config.example.toml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/config.example.toml b/config.example.toml index f0fea2b00..61fbd3507 100644 --- a/config.example.toml +++ b/config.example.toml @@ -193,10 +193,13 @@ args = [ # # HMAC request signing: # --hmac-secret Shared HMAC-SHA256 secret for request signing and replay -# protection. When set, all requests must include: +# 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): From 0041be63fd7a6ad477baf3781a4369fba4c02116 Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Tue, 28 Apr 2026 09:41:03 -0700 Subject: [PATCH 5/5] Update docs/ENVIRONMENT_VARIABLES.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/ENVIRONMENT_VARIABLES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md index 2ae74ce2c..1e0ef91d4 100644 --- a/docs/ENVIRONMENT_VARIABLES.md +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -32,7 +32,7 @@ When running locally (`run.sh`), these variables are optional (warnings shown if | `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. When set, all incoming requests must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers. Sets default for `--hmac-secret`. | (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) |