Clients & Policies

Define who can access what with client mappings and policy rules.

---

Client Configuration

Clients map source IP addresses to policies. Defined in clients.toml or files in clients.d/.

Client Fields

Field	Type	Required	Description
name	String	Yes	Unique identifier for the client
ip	String	One of ip/cidr	Single IP address (e.g., "127.0.0.1", "::1")
cidr	String	One of ip/cidr	CIDR block (e.g., "10.0.0.0/8", "2001:db8::/32")
policies	Array	Yes	List of policy names to apply in order
fallback	Boolean	No	Mark as fallback client (exactly one required)

Matching

Client selectors must not overlap, so each source IP maps to at most one non-fallback client. If no selector matches, the fallback client is used.

Validation Rules

• Client names must be unique
• Either ip or cidr must be specified, not both
• Non-fallback selectors must not overlap (IP vs IP, IP vs CIDR, CIDR vs CIDR)
• Exactly one client must have fallback = true
• All referenced policies must exist

Example

# Analytics workers subnet
[[client]]
name = "analytics-workers"
cidr = "10.42.16.0/27"
policies = ["analytics-policy", "fallback-deny"]

# Payment gateway subnet
[[client]]
name = "payments-gateway"
cidr = "10.42.48.0/28"
policies = ["payments-policy", "fallback-deny"]

# Localhost for testing
[[client]]
name = "loopback"
ip = "127.0.0.1"
policies = ["local-allow"]

# Fallback: deny everything else
[[client]]
name = "fallback"
cidr = "0.0.0.0/0"
policies = ["default-deny"]
fallback = true

---

Policy Configuration

Policies contain ordered rules that determine whether requests are allowed or denied. Defined in policies.toml or files in policies.d/.

Policy Structure

[[policy]]
name = "policy-name"
  [[policy.rule]]
  # rule fields...

Rules are evaluated in order. The first matching rule determines the action.

---

Rule Fields

Field	Type	Default	Description
action	String	Required	"ALLOW" or "DENY"
methods	Array	["ANY"]	HTTP methods to match (non-CONNECT by default)
url_pattern	String	None	URL pattern to match (see syntax below)
https_mode	String	"inspect"	HTTPS handling mode: "inspect" or "tunnel"
cache	Table	None	Cache configuration (see below)
status	u16	Required for DENY	HTTP status code for denial response
reason	String	None	HTTP reason phrase (DENY only)
body	String	None	Response body (DENY only)

ALLOW vs DENY

ALLOW Rules

• Permit the request to proceed upstream
• Must not set status, reason, or body
• Can use https_mode = "tunnel" for explicit CONNECT tunneling

DENY Rules

• Block the request with specified response
• Must set status (HTTP status code)
• Optional: reason and body

---

HTTP Methods

Valid method values:

• "ANY" - Matches all non-CONNECT methods (default)
• "GET", "POST", "PUT", "PATCH", "DELETE"
• "HEAD", "OPTIONS", "TRACE", "CONNECT"

# Single method
methods = ["GET"]

# Multiple methods
methods = ["GET", "POST", "DELETE"]

# Any method (default)
methods = ["ANY"]

Note

Cannot mix "ANY" with explicit methods in the same array. "CONNECT" must be the only method in its rule.

CONNECT requests are evaluated against explicit CONNECT tunnel rules first. If no tunnel rule matches, ExfilGuard can still perform a TLS bump preflight when matching HTTPS inspect rules exist for the same host/port. The real policy decision is then attached to the inner HTTP request. Private upstream addresses are never permitted, whether the request is plain HTTP, tunneled CONNECT, or bumped HTTPS.

---

URL Pattern Syntax

URL patterns follow the format: scheme://host[:port][/path]

Scheme

http or https (required)

Host Matching

Pattern	Matches
example.com	Exact domain
*.example.com	Exactly one subdomain label of example.com
**.example.com	Any depth of subdomains of example.com (one or more)
example.**	Any suffix depth under example
*	Any host
192.0.2.1	Exact IPv4 address
[2001:db8::1]	Exact IPv6 address (bracketed)

Note

Host matching is case-insensitive. Wildcards can only appear as entire labels: *.example.com and **.example.com are valid, a*b.com is not. * matches a single label and ** matches one or more labels.

Port

Optional. Defaults to 80 for HTTP, 443 for HTTPS.

url_pattern = "https://example.com:8443/api/**"

Path Matching

Pattern	Matches
/api/v1/users	Exact path
/users/*	Single segment: /users/123, /users/abc
/api/**	Any depth: /api/v1, /api/v1/users/123
/users/*/profile	/users/123/profile, /users/abc/profile

Note

Policy path matching uses a canonical path view. Query strings are ignored, literal . and .. segments are normalized, and ambiguous path syntax is rejected instead of being rewritten. ExfilGuard preserves the raw request target for upstream forwarding, so signed requests keep their original path bytes.

Note

Requests are rejected if the path contains invalid escapes, backslashes, encoded path separators, or encoded dot-segments such as %2e%2e.

Complete Examples

# HTTPS to specific API endpoint
"https://api.example.com/v1/exports/**"

# Any subdomain of partner.com on custom port
"https://*.partner.com:8443/payments/**"

# HTTP to any host, specific path
"http://*/health"

# IPv6 address
"https://[2001:db8::1]/api/**"

---

HTTPS Modes

The https_mode option controls how ExfilGuard handles HTTPS traffic.

https_mode = "inspect" (default)

• Full HTTP inspection after TLS interception
• TLS is terminated and re-encrypted (MITM)
• Used for normal HTTPS GET/POST/PUT/DELETE style rules
• Matching HTTPS rules authorize a TLS bump preflight for the same host/port
• The real policy decision is attached to the inner HTTP request
• Private upstream resolution is still blocked
• Enables normal request logging, metrics, and caching (when configured)
• Request metrics are labeled effective_mode="bump" on the inspected inner request

https_mode = "tunnel"

• Traffic is tunneled without inspection
• Only valid with methods = ["CONNECT"]
• Only valid with URL pattern path /** (e.g., https://secure.partner.com/**)
• CONNECT tunnel rules must appear before non-CONNECT rules inside each policy
• Request metrics are labeled effective_mode="tunnel" on the CONNECT tunnel request
• Useful for certificate-pinned services that refuse MITM

Warning

Tunnel mode bypasses content inspection. Use only when necessary (e.g., payment gateways with certificate pinning).

---

Response Caching

Rules can enable caching for matched responses when the cache subsystem is configured globally.

[[policy.rule]]
action = "ALLOW"
methods = ["GET"]
url_pattern = "https://cdn.example.com/**"
  [policy.rule.cache]
  force_cache_duration = 3600  # Fallback: cache for 1 hour

Field	Type	Description
force_cache_duration	u64	Fallback cache lifetime in seconds (used only when upstream sends no cache headers)

How Caching Works

The cache respects standard HTTP caching headers from upstream:

• Cache-Control: s-maxage, max-age, public, private, no-cache, no-store
• Expires: HTTP date for expiration
• Vary: Responses vary by specified request headers

force_cache_duration is a fallback only - it does not override upstream freshness. It applies when the upstream response omits s-maxage, max-age, and Expires (including cases where only public is set).

Note

Only GET and HEAD responses with status 200, 203, 204, 205, 206, 301, or 302 are cached. See Cache Settings for full details.

---

Complete Examples

Deny-All Fallback

[[policy]]
name = "fallback-deny"
  [[policy.rule]]
  action = "DENY"
  status = 470
  reason = "Policy Blocked"
  body = "Blocked by ExfilGuard\n"

Allow Specific API Endpoints

[[policy]]
name = "api-policy"
  [[policy.rule]]
  action = "ALLOW"
  methods = ["GET", "POST"]
  url_pattern = "https://api.trusted.com/v1/exports/**"

  [[policy.rule]]
  action = "ALLOW"
  methods = ["ANY"]
  url_pattern = "https://reports.trusted.com/dashboards/**"

Certificate-Pinned Service (Tunnel)

[[policy]]
name = "pinned-payments"
  [[policy.rule]]
  action = "ALLOW"
  methods = ["CONNECT"]
  url_pattern = "https://secure.partner.com/**"
  https_mode = "tunnel"

Cached Static Content

[[policy]]
name = "cached-content"
  [[policy.rule]]
  action = "ALLOW"
  methods = ["GET"]
  url_pattern = "https://cdn.example.com/**"
    [policy.rule.cache]
    force_cache_duration = 3600