From e232571d14da936460c9079952b719098314bcde Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:27:15 +0100 Subject: [PATCH 01/14] add ipfilters, trustedips, trustedproxies --- docs/configuration/ip-filters.md | 63 +++++++++++++++++++++++++++ docs/configuration/trusted-ips.md | 16 +++++++ docs/configuration/trusted-proxies.md | 15 +++++++ docs/features/features.md | 5 +++ 4 files changed, 99 insertions(+) create mode 100644 docs/configuration/ip-filters.md create mode 100644 docs/configuration/trusted-ips.md create mode 100644 docs/configuration/trusted-proxies.md diff --git a/docs/configuration/ip-filters.md b/docs/configuration/ip-filters.md new file mode 100644 index 00000000..d78fa30b --- /dev/null +++ b/docs/configuration/ip-filters.md @@ -0,0 +1,63 @@ +--- +title: IP Filters +--- + +# IP Filters + +Restrict access to your **Secured Signal API** based on client IP addresses. + +IP filtering allows you to explicitly **allow** or **block** requests originating from specific IPs or CIDR ranges. + +## Default + +By default, **all IP addresses are allowed**. + +No IP-based restrictions are applied unless `access.ipFilter` is configured. + +## Customize + +You can modify IP access rules by configuring `access.ipFilter` in your config: + +```yaml +settings: + access: + ipFilter: + - "!123.456.78.9" + - "!234.567.89.0/24" + - 192.168.1.10 + - 10.0.0.0/24 +``` + +By default, adding an IP or range explicitly allows it, use `!` to block it instead. + +> [!IMPORTANT] +> When using `!` to block an IP or range, you must enclose it in quotes + +**Supports:** + +- Single IPv4 / IPv6 addresses +- CIDR notation (`10.0.0.0/24`, `2001:db8::/32`) + +## Behavior + +| Allow | Block | Result | +| -------------- | ----------------------- | ----------------------------------------- | +| `192.168.1.10` | — | Only `192.168.1.10` allowed | +| — | `!123.456.78.9` | All allowed, except `123.456.78.9` | +| `10.0.0.0/24` | `!10.0.0.10` | `10.0.0.0/24` allowed, except `10.0.0.10` | +| — | `!0.0.0.0/0`
`!::/0` | All IPv4 & IPv6 blocked | + +### Rules + +- Default: **allow all** +- Allow rules restrict access **only if no block rules exist** +- Block rules deny matching IPs +- Explicit allow overrides block +- IPv4 and IPv6 rules may be mixed + +## Clients behind Proxies + +For clients behind proxies IPs cannot be reliably determined without trusting the `X-Forwarded-For` HTTP header. +In order for **Secured Signal API** to trust the _XFF_ header it has to trust the request's originating proxy. + +Read more about trusted proxies [here](./trusted-proxies). diff --git a/docs/configuration/trusted-ips.md b/docs/configuration/trusted-ips.md new file mode 100644 index 00000000..ab73aecb --- /dev/null +++ b/docs/configuration/trusted-ips.md @@ -0,0 +1,16 @@ +--- +title: Trusted IPs +--- + +# Trusted IPs + +Trusted clients can bypass some security features and are often local or internal IPs. + +To trust IPs or ranges add them to `access.trustedIPs`. + +```yaml +access: + trustedIPs: + - 192.168.1.10 + - 192.168.2.0/24 +``` diff --git a/docs/configuration/trusted-proxies.md b/docs/configuration/trusted-proxies.md new file mode 100644 index 00000000..32e6afb2 --- /dev/null +++ b/docs/configuration/trusted-proxies.md @@ -0,0 +1,15 @@ +--- +title: Trusted Proxies +--- + +# Trusted Proxies + +Proxies can be marked as trusted. + +When determining the IP of a client behind a proxy it is important to use the `X-Forwarded-For` header, +but as you might know anyone can set headers (spoofing possible). + +To prevent IP spoofing you should only trust the HTTP headers of trusted proxies. +Otherwise malicious actors may change the `X-Forwarded-For` header to be able to bypass block list or rate limits. + +Add proxies to be trusted in `access.trustedProxies`. diff --git a/docs/features/features.md b/docs/features/features.md index b2166baa..7e792f4a 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -54,3 +54,8 @@ Find more about this feature [here](./configuration/field-policies). **Endpoints** are used for restricting unauthorized access and for ensuring least privilege. [Let's start blocking then!](./configuration/endpoints) + +## IP Filters + +**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and IP subnets. +Configure your _mini firewall_ [here](./configuration/ip-filters). From 994f3829ec58b8f7a00747065fe316aca3967513 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:27:23 +0100 Subject: [PATCH 02/14] brag about it --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index 15c59a2c..7086b55d 100644 --- a/docs/about.md +++ b/docs/about.md @@ -22,7 +22,7 @@ It's designed for developers who want to: ## Key Features -- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth) and [**endpoint restrictions**](./features#endpoints). +- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth), [**endpoint restrictions**](./features#endpoints) and [**ip filters**](./features#ip-filters). - 🧩 **Full Compatibility** — 100% protocol-compatible; all requests are still handled by your existing Signal CLI REST API. - ⚙️ **Configurable Proxy Behavior** — Define templates and limits via YAML or environment variables. - 🧠 **Message Templates** — Use [**variables**](./configuration/variables) and [**placeholders**](./features#placeholders) to standardize common message formats. From 3ca3da05a15c38d82cc9d05f07ae5331d44bd08e Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:27:31 +0100 Subject: [PATCH 03/14] recommend it --- docs/best-practices/best-practices.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/best-practices/best-practices.md b/docs/best-practices/best-practices.md index 638fe3a7..9e94985d 100644 --- a/docs/best-practices/best-practices.md +++ b/docs/best-practices/best-practices.md @@ -10,8 +10,8 @@ Here are some common best practices for running **Secured Signal API**, but thes ## Usage - Create **separate configs** for each service -- Use [**placeholders**](./usage/advanced#placeholders) extensively _(trust me, they are so useful)_ -- Always keep your stack **up-to-date** _(this is why we have Docker)_ +- Use [**placeholders**](./usage/advanced#placeholders) extensively +- Always keep your stack **up-to-date** ## Security @@ -19,4 +19,5 @@ Here are some common best practices for running **Secured Signal API**, but thes - Run behind a [**tls-enabled reverse proxy**](./reverse-proxy) - Be cautious when overriding [**blocked endpoints**](./features#endpoints) - Use per-token overrides to **enforce least privilege** -- Always allow the least possible access points +- Always allow the least possible [**endpoints**](./features#endpoints) +- Only allow access from [**IPs**](./features#ip-filter) **you trust** From 45960d643d4d15c3c82370e444809257c296ae65 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:27:55 +0100 Subject: [PATCH 04/14] update endpoints doc --- docs/configuration/endpoints.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/configuration/endpoints.md b/docs/configuration/endpoints.md index a08f8a34..e819b7fc 100644 --- a/docs/configuration/endpoints.md +++ b/docs/configuration/endpoints.md @@ -45,8 +45,18 @@ By default, adding an endpoint explicitly allows access to it, use `!` to block > [!IMPORTANT] > When using `!` to block you must enclose the endpoint in quotes, like in the example above -| Config (Allow) | (Block) | Result | | | | -| :------------- | :------------- | :--------: | --- | :---------------: | --- | -| `/v2/send` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ | -| `unset` | `!/v1/receive` | **all** | ✅ | **`/v1/receive`** | 🛑 | -| `!/v2*` | `/v2/send` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ | +## Behavior + +| Allow | Block | Result | +| ---------- | -------------- | -------------------------------------------- | +| `/v2/send` | — | **Only** `/v2/send` allowed | +| — | `!/v1/receive` | **All** allowed **except** `/v1/receive` | +| `/v2/send` | `!/v2/*` | `/v2*` allowed **except** `/v2/send` blocked | + +### Rules + +- Default: **allow all** +- Allow rules add explicit access +- Block rules deny matching endpoints +- Explicit allow overrides block +- Mixed allow + block rules keep permissive default From 686d4dbb0810b7a9e05d27c7757cffec9a392e47 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:28:04 +0100 Subject: [PATCH 05/14] add to config --- docs/configuration/examples/config.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/configuration/examples/config.yml b/docs/configuration/examples/config.yml index 3405163f..3af6d887 100644 --- a/docs/configuration/examples/config.yml +++ b/docs/configuration/examples/config.yml @@ -24,12 +24,14 @@ settings: "@message": [{ field: "msg", score: 100 }] access: + ipFilter: + - 192.168.1.10 + - 192.168.2.0/24 + - "!192.168.2.44" + endpoints: - "!/v1/about" - /v2/send fieldPolicies: - "@number": { - value: "+123400003", - action: block - } + "@number": { value: "+123400003", action: block } From 5b433cb8b48b820e7e6886e253d431f3441470ec Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:28:16 +0100 Subject: [PATCH 06/14] add trustedproxies section to rv proxies --- docs/reverse-proxy/caddy/caddy.md | 13 +++++++++++++ .../caddy/examples/caddy.docker-compose.yaml | 4 ++++ .../nginx/examples/nginx.docker-compose.yaml | 1 + docs/reverse-proxy/nginx/nginx.md | 13 +++++++++++++ .../examples/traefik.docker-compose.yaml | 17 ++++++++++++++++- docs/reverse-proxy/traefik/traefik.md | 13 +++++++++++++ 6 files changed, 60 insertions(+), 1 deletion(-) diff --git a/docs/reverse-proxy/caddy/caddy.md b/docs/reverse-proxy/caddy/caddy.md index e33534a6..fef9d0d2 100644 --- a/docs/reverse-proxy/caddy/caddy.md +++ b/docs/reverse-proxy/caddy/caddy.md @@ -22,12 +22,25 @@ Add Caddy to your `docker-compose.yaml` file. {{{ #://./examples/caddy.docker-compose.yaml }}} ``` +## Setup + Create a `Caddyfile` in your `docker-compose.yaml` folder and mount it to `/etc/caddy/Caddyfile` in your Caddy container. ```apacheconf {{{ #://./examples/Caddyfile }}} ``` +## Configuration + +Now you can switch over to **Secured Signal API** and add Caddy to your [trusted proxies](../../configuration/trusted-proxies.md): + +```yaml +settings: + access: + trustedProxies: + - 172.20.0.100 +``` + Then spin up your stack: ```bash diff --git a/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml b/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml index 2e5c42fd..73087b77 100644 --- a/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml +++ b/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml @@ -24,6 +24,10 @@ services: - data:/data depends_on: - secured-signal + restart: unless-stopped + networks: + backend: + ipv4_address: 172.20.0.100 networks: backend: diff --git a/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml b/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml index c2c7a00a..01b37831 100644 --- a/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml +++ b/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml @@ -28,6 +28,7 @@ services: restart: unless-stopped networks: backend: + ipv4_address: 172.20.0.100 networks: backend: diff --git a/docs/reverse-proxy/nginx/nginx.md b/docs/reverse-proxy/nginx/nginx.md index ebe173bc..2fe2fd26 100644 --- a/docs/reverse-proxy/nginx/nginx.md +++ b/docs/reverse-proxy/nginx/nginx.md @@ -24,6 +24,8 @@ To implement Nginx in front of **Secured Signal API** you need to update your `d To include the needed mounts for your certificates and your config. +## Setup + Create a `nginx.conf` file in the `docker-compose.yaml` folder and mount it to `/etc/nginx/conf.d/default.conf` in your Nginx container. ```apacheconf @@ -32,6 +34,17 @@ Create a `nginx.conf` file in the `docker-compose.yaml` folder and mount it to ` Add your `cert.key` and `cert.crt` into your `certs/` folder and mount it to `/etc/nginx/ssl`. +## Configuration + +Now you can switch over to **Secured Signal API** and add Nginx to your [trusted proxies](../../configuration/trusted-proxies.md): + +```yaml +settings: + access: + trustedProxies: + - 172.20.0.100 +``` + Lastly spin up your stack: ```bash diff --git a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml index 36a06622..31e9d7dd 100644 --- a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml +++ b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml @@ -23,7 +23,22 @@ services: aliases: - secured-signal-api + traefik: + image: traefik:v3.6.5 + container_name: traefik + ports: + - "80:80" + - "443:443" + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./config/traefik.yaml:/etc/traefik/traefik.yaml:ro + - certs:/var/traefik/certs/:rw + - logs:/var/log/traefik + restart: unless-stopped + networks: + proxy: + ipv4_address: 172.20.0.100 + networks: backend: proxy: - external: true diff --git a/docs/reverse-proxy/traefik/traefik.md b/docs/reverse-proxy/traefik/traefik.md index eb68398e..9f2734db 100644 --- a/docs/reverse-proxy/traefik/traefik.md +++ b/docs/reverse-proxy/traefik/traefik.md @@ -25,8 +25,21 @@ To implement Traefik in front of **Secured Signal API** you need to update your To include the Traefik router and service labels. +## Configuration + +Now you can switch over to **Secured Signal API** and add Traefik to your [trusted proxies](../../configuration/trusted-proxies.md): + +```yaml +settings: + access: + trustedProxies: + - 172.20.0.100 +``` + Then restart **Secured Signal API**: ```bash docker compose down && docker compose up -d ``` + +That's it, have fun! From 73fa589891e8b195c51081bf9ce71becb4f8992a Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:29:36 +0100 Subject: [PATCH 07/14] add space --- docs/configuration/ip-filters.md | 12 ++++++------ docs/features/features.md | 2 ++ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/configuration/ip-filters.md b/docs/configuration/ip-filters.md index d78fa30b..8dadc3e6 100644 --- a/docs/configuration/ip-filters.md +++ b/docs/configuration/ip-filters.md @@ -40,12 +40,12 @@ By default, adding an IP or range explicitly allows it, use `!` to block it inst ## Behavior -| Allow | Block | Result | -| -------------- | ----------------------- | ----------------------------------------- | -| `192.168.1.10` | — | Only `192.168.1.10` allowed | -| — | `!123.456.78.9` | All allowed, except `123.456.78.9` | -| `10.0.0.0/24` | `!10.0.0.10` | `10.0.0.0/24` allowed, except `10.0.0.10` | -| — | `!0.0.0.0/0`
`!::/0` | All IPv4 & IPv6 blocked | +| Allow | Block | Result | +| -------------- | ------------------------ | ----------------------------------------- | +| `192.168.1.10` | — | Only `192.168.1.10` allowed | +| — | `!123.456.78.9` | All allowed, except `123.456.78.9` | +| `10.0.0.0/24` | `!10.0.0.10` | `10.0.0.0/24` allowed, except `10.0.0.10` | +| — | `!0.0.0.0/0`
`!::/0` | All IPv4 & IPv6 blocked | ### Rules diff --git a/docs/features/features.md b/docs/features/features.md index 7e792f4a..23c63e88 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -53,9 +53,11 @@ Find more about this feature [here](./configuration/field-policies). > _Block unwanted access_ **Endpoints** are used for restricting unauthorized access and for ensuring least privilege. + [Let's start blocking then!](./configuration/endpoints) ## IP Filters **IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and IP subnets. + Configure your _mini firewall_ [here](./configuration/ip-filters). From feaf2af6cd561bb580514ae88f25a190945c731f Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:30:39 +0100 Subject: [PATCH 08/14] . --- docs/configuration/trusted-proxies.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/configuration/trusted-proxies.md b/docs/configuration/trusted-proxies.md index 32e6afb2..8d17e09c 100644 --- a/docs/configuration/trusted-proxies.md +++ b/docs/configuration/trusted-proxies.md @@ -10,6 +10,12 @@ When determining the IP of a client behind a proxy it is important to use the `X but as you might know anyone can set headers (spoofing possible). To prevent IP spoofing you should only trust the HTTP headers of trusted proxies. -Otherwise malicious actors may change the `X-Forwarded-For` header to be able to bypass block list or rate limits. +Otherwise, malicious actors may change the `X-Forwarded-For` header to be able to bypass block list or rate limits. Add proxies to be trusted in `access.trustedProxies`. + +```yaml +access: + trustedProxies: + - 172.20.0.100 +``` From 89d2c534860d7337500fcc661cb14f7281825065 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:34:34 +0100 Subject: [PATCH 09/14] . --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index 7086b55d..546f4743 100644 --- a/docs/about.md +++ b/docs/about.md @@ -22,7 +22,7 @@ It's designed for developers who want to: ## Key Features -- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth), [**endpoint restrictions**](./features#endpoints) and [**ip filters**](./features#ip-filters). +- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth), [**endpoint restrictions**](./features#endpoints) and [**IP filters**](./features#ip-filters). - 🧩 **Full Compatibility** — 100% protocol-compatible; all requests are still handled by your existing Signal CLI REST API. - ⚙️ **Configurable Proxy Behavior** — Define templates and limits via YAML or environment variables. - 🧠 **Message Templates** — Use [**variables**](./configuration/variables) and [**placeholders**](./features#placeholders) to standardize common message formats. From b8b118140fcb1dfd210fd4a4a05fd6bf8234ba90 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:38:56 +0100 Subject: [PATCH 10/14] . --- docs/features/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/features.md b/docs/features/features.md index 23c63e88..253af89f 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -21,7 +21,7 @@ Look at this complex template for example: It can extract needed data from the body and headers to then process them using Go's templating library and finally output a message packed with so much information. -Head to [configuration](./configuration/message-template) to see how-to use. +Head to [Configuration](./configuration/message-template) to see how-to use. ## Placeholders From 2f88c96dd52e572e8069b7aaea95b00327463fa2 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:53:36 +0100 Subject: [PATCH 11/14] . --- docs/features/features.md | 4 ++-- .../traefik/examples/traefik.docker-compose.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/features/features.md b/docs/features/features.md index 253af89f..8eaa3ae9 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -5,7 +5,7 @@ title: Features # Features -Here are some of the highlights of using **Secured Signal API** +Here are some of the highlights of using **Secured Signal API**. ## Message Template @@ -58,6 +58,6 @@ Find more about this feature [here](./configuration/field-policies). ## IP Filters -**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and IP subnets. +**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and IP ranges. Configure your _mini firewall_ [here](./configuration/ip-filters). diff --git a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml index 31e9d7dd..34f23703 100644 --- a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml +++ b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml @@ -24,7 +24,7 @@ services: - secured-signal-api traefik: - image: traefik:v3.6.5 + image: traefik:latest container_name: traefik ports: - "80:80" From 490bcab099d1e919d1529bd80bde6cd0a9474481 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 19:56:36 +0100 Subject: [PATCH 12/14] . --- docs/features/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/features.md b/docs/features/features.md index 8eaa3ae9..31222715 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -58,6 +58,6 @@ Find more about this feature [here](./configuration/field-policies). ## IP Filters -**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and IP ranges. +**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and CIDR ranges. Configure your _mini firewall_ [here](./configuration/ip-filters). From dc4fdeee46abc35ce62cd0f1de312fe893cebbf1 Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Tue, 6 Jan 2026 20:02:59 +0100 Subject: [PATCH 13/14] add trusted IPs and Proxies to config --- docs/configuration/examples/config.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/configuration/examples/config.yml b/docs/configuration/examples/config.yml index 3af6d887..cf7af121 100644 --- a/docs/configuration/examples/config.yml +++ b/docs/configuration/examples/config.yml @@ -24,6 +24,12 @@ settings: "@message": [{ field: "msg", score: 100 }] access: + trustedIPs: + - 192.168.1.10 + + trustedProxies: + - 172.20.0.100 + ipFilter: - 192.168.1.10 - 192.168.2.0/24 From db9525dfe8726dc0b78982cebe60e2a39e2e835e Mon Sep 17 00:00:00 2001 From: CodeShell <122738806+CodeShellDev@users.noreply.github.com> Date: Thu, 8 Jan 2026 20:05:26 +0100 Subject: [PATCH 14/14] docs: Hostnames (#189) --- docs/configuration/examples/config.yml | 2 ++ docs/configuration/hostnames.md | 21 +++++++++++++++++++++ docs/configuration/ip-filters.md | 2 +- docs/configuration/trusted-proxies.md | 17 +++++++++++------ 4 files changed, 35 insertions(+), 7 deletions(-) create mode 100644 docs/configuration/hostnames.md diff --git a/docs/configuration/examples/config.yml b/docs/configuration/examples/config.yml index cf7af121..e9037ec1 100644 --- a/docs/configuration/examples/config.yml +++ b/docs/configuration/examples/config.yml @@ -1,6 +1,8 @@ # Example Config (all configurations shown) service: port: 8880 + hostnames: + - mydomain.com api: url: http://signal-api:8080 diff --git a/docs/configuration/hostnames.md b/docs/configuration/hostnames.md new file mode 100644 index 00000000..4732dc21 --- /dev/null +++ b/docs/configuration/hostnames.md @@ -0,0 +1,21 @@ +--- +title: Hostnames +--- + +# Hostnames + +Hostnames can be set to create isolated realms or to restrict access by limiting to a only a small subset of hostnames. + +Add hostnames, that are allowed to be used in `service.hostnames`. (default: all) + +```yaml +service: + hostnames: + - mydomain.com +``` + +## Usage behind Proxy + +For clients behind proxies IPs cannot be reliably determined without using the `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-Port` HTTP headers. + +For **Secured Signal API** to trust a proxy it must be added to the trusted proxies, read more [here](./trusted-proxies). diff --git a/docs/configuration/ip-filters.md b/docs/configuration/ip-filters.md index 8dadc3e6..edbf820c 100644 --- a/docs/configuration/ip-filters.md +++ b/docs/configuration/ip-filters.md @@ -57,7 +57,7 @@ By default, adding an IP or range explicitly allows it, use `!` to block it inst ## Clients behind Proxies -For clients behind proxies IPs cannot be reliably determined without trusting the `X-Forwarded-For` HTTP header. +For clients behind proxies, IPs cannot be reliably determined without trusting the `X-Forwarded-For` HTTP header. In order for **Secured Signal API** to trust the _XFF_ header it has to trust the request's originating proxy. Read more about trusted proxies [here](./trusted-proxies). diff --git a/docs/configuration/trusted-proxies.md b/docs/configuration/trusted-proxies.md index 8d17e09c..eab800c8 100644 --- a/docs/configuration/trusted-proxies.md +++ b/docs/configuration/trusted-proxies.md @@ -6,12 +6,6 @@ title: Trusted Proxies Proxies can be marked as trusted. -When determining the IP of a client behind a proxy it is important to use the `X-Forwarded-For` header, -but as you might know anyone can set headers (spoofing possible). - -To prevent IP spoofing you should only trust the HTTP headers of trusted proxies. -Otherwise, malicious actors may change the `X-Forwarded-For` header to be able to bypass block list or rate limits. - Add proxies to be trusted in `access.trustedProxies`. ```yaml @@ -19,3 +13,14 @@ access: trustedProxies: - 172.20.0.100 ``` + +## `X-Forwarded-*` Headers + +HTTP listeners only get the `proto://host:port/uri` from the incoming request, but proxies often redirect requests causing modified request URLs +`http://sec-signal-api:8880`. + +To get the origin URL you have to use the `X-Forwarded-*` headers, but as you might know anyone can set headers (spoofing possible). +This means you should only trust _XF_ headers from trusted sources, +otherwise, malicious actors can change any `X-Forwarded-*` headers to be able to bypass block list, rate limits, hostname restrictions, … . + +This also applies to determining the IP of a client behind a proxy, so it is extremely important to allow for using the _XF_ headers when a proxy is trusted.