Header filter

​

Overview

The Header-filtering section (safesquid-header-filtering(5)) allows administrators to strip out or inject HTTP headers into client requests or server responses.

​

Core Mechanics (C++ Source Validation)

Allow/Deny list order, Insert with variable expansion.

• Dual-List Policy Engine: Header filtering utilizes a global Allow/Deny switch. If the global policy is set to Allow, SafeSquid first scans the Deny List to strip headers (action = FALSE), then evaluates the Allow List to preserve exceptions.
• Insertion Engine: Independent of the filter list, the Insert list injects entirely new headers into the stream. The inserted headers undergo variable expansion, meaning runtime variables (like usernames or IP addresses) can be dynamically injected into the header value.
• Flags Targeting: Both filter and insert rules target either the Request, Response, or Both (which & flags).

​

Schema Fields

​

Global Fields

• Enabled (enabled): Turn Header filter on or off for all connections (unless bypassed on the Access entry).
• Policy (policy): Default when no allow/deny row matches a header field: Deny strips it; Allow forwards it. List walk order depends on this setting (see section help).

​

Rule-Based Fields (Per Connection Tuning)

• Enabled (enabled): Skip this row when disabled. Enabled rows participate in matching.
• Comment (comment): Notes for operators. Shown only in configuration, not to end users.
• Profiles (profiles): Apply only when the connection has one of these profiles. Blank = all connections. Prefix ! to skip connections that have a profile (for example !Guest ).
• Type (type): Regex on the header field name (for example Referer , User-Agent ). Blank matches any header name. On Insert rows this is the literal header name to add, not a regex.
• Value (value): Regex on the header field value for Allow/Deny rows. Blank matches any value. On Insert rows this is the header body (variables expanded). Both Type and Value must be set for Insert to apply.
• Applies to (which): Choose request headers (client), response headers (server), or both. Must include the direction being filtered.

​

How SafeSquid processes the lists

1. For each header field on the message being filtered:
2. If Policy is Deny, SafeSquid walks Allow first, then Deny.
3. If Policy is Allow, SafeSquid walks Deny first, then Allow (Allow can restore a field Deny removed, and vice versa on the second pass).
4. Within each list pass, the first matching row decides allow or strip for that field.
5. Stripped fields are removed and logged as removed in native header logs.
6. Insert runs after allow/deny. Both Type and Value must be non-empty; Value supports connection variables.

​

Important entry fields

• Profiles — Apply only when the connection has one of these profiles. Blank = all connections. Prefix ! to skip connections that have a profile (for example !Guest).
• Type — On Allow/Deny: regex on the header field name (for example Referer, User-Agent); blank matches any name. On Insert: literal header name to add (not a regex).
• Value — On Allow/Deny: regex on the field value; blank matches any value. On Insert: header body with variables expanded.
• Applies to — CLIENT HEADER — request headers (browser → origin). SERVER HEADER — response headers (origin → browser). Row must include the direction being filtered.

​

Examples

​

How to verify

1. Use View headers in the Web UI to capture real header names and values before writing regexes.
2. Enable HEADER in LOG_LEVEL and read native removed: / added: lines.
3. Open Reports → Detailed logs while reproducing from a known client.
4. Enable System configuration debug response headers (see Debug response headers) to inspect policy outcomes on the wire.