Policies¶

Policies define which subnets, hosts, user agents, SNI patterns, or other request attributes are permitted, denied, warned about, or shown an Acceptable Use Policy gate before they reach the proxy upstream. They are the primary mechanism by which operators control web traffic in EnforceGate vX.

Policies are ordered sets of rules. The fine-grained control they provide protects endpoints and infrastructure against a wide range of threats — C2 channels, malware downloads, data exfiltration, and other malicious activity.

The policy file format closely resembles JavaScript Object Notation (JSON) but is significantly more permissive: it supports inline and block comments, multi-line values, and unquoted keys and string values.

Rule files¶

Policy rules are defined in .policy files under /etc/enforcegate/rules.d/ inside the standalone container. The directory holds an arbitrary number of files; they are loaded in lexicographical order and the engine assigns rule ids in load order. The lowest-id matching rule wins on every match path — so the conventional two-digit precedence prefix (e.g. 05-, 40-, 90-) controls precedence by way of controlling the id. A rule in 10-allow-internal.policy always wins over a conflicting rule in 90-block-categories.policy. This approach is modelled on the popular udevd rules directory and significantly simplifies policy management.

Policies¶

A rule file consists of one or more policy blocks. Each block must contain a name and at least one match attribute.

# Allow Package Mirrors

accept-ubuntu-initseven: {
    match-uri: https://mirror.init7.net/ubuntu/      # (1)!
    action: permit
    description: Local Ubuntu Mirror
}

accept-mirror-switch: {
    match-uri-regex: ^(https?:\/\/)?.*mirror\.switch\.ch.*   # (2)!
    action: permit
    description: SWITCH mirror
}

1. Match all URIs that start with https://mirror.init7.net/ubuntu/.
2. Match all URIs (HTTP or HTTPS, with or without scheme) whose domain is mirror.switch.ch. Regular-expression syntax — see the Squid connector reference for the full set of request attributes available to match against.

Both policies above use URI matching. The first uses a literal match-uri prefix; the second uses match-uri-regex (a regular expression). The action: permit allows the request to proceed. The scheme (http / https) is implicit in the URL itself — a separate application: attribute is not required and would produce a load-time Warning as of 2026.46.0.

Available match attributes¶

The full match-attribute reference is part of the policy DSL specification (currently proprietary). The most commonly used:

Multiple match-* attributes on the same rule are AND-combined — the rule matches only when the URL / domain dimension and every other match-* gate (client IP, method, user-agent, time window) hold. For an OR, split into separate rules. match-client-ip, match-method, match-user-agent, and time-window: are secondary gates in the verdict path: a URL-matched rule is accepted only if the request's client IP, method, User-Agent, and time-of-day satisfy every gate the rule specifies; otherwise the request falls through to the next lowest-id rule.

Time-scheduled rules¶

Any rule can carry an optional time-window: attribute. The rule only matches during the window; outside it, the rule behaves as if it were not loaded and the request falls through to the next rule. A rule with no time-window: is always active — the attribute is purely additive, and every existing policy keeps working unchanged.

The grammar is time-window: [<days>] HH:MM-HH:MM:

block-social-business-hours: {
    match-domain-list: /etc/enforcegate/rules.d/lists/social-media.list
    action: deny
    description: No social media during work hours
    time-window: weekdays 08:00-18:00
}

time-window: works on every rule shape — match-uri, match-uri-regex, match-domain-list, match-url-list / match-urls, match-url-prefix-list / match-url-prefixes, match-uri-regex-list, match-category, match-sni, match-client-ip, match-user-agent, match-method.

Fall-through, not flip — the important mental model¶

When a rule's window is closed, the engine treats the rule as non-existent for that request. The match falls through to the next-applicable rule, and ultimately to the catch-all baseline. A closed window does not turn a permit into a deny (or vice versa).

This composes with the lowest-id-wins precedence operators already know. Worked example:

10-allow-vendor.policy   permit  time-window: weekdays 08:00-18:00
90-deny-vendor.policy    deny

• During weekday business hours: the id-10 permit wins (lowest id), vendor traffic is allowed.
• Outside that window: the id-10 rule does not match, so the id-90 deny takes over.

A time-limited permit placed above a broad deny therefore gives "allow only during these hours, deny the rest of the time" with no extra rules. A time-limited deny placed above a permit gives the inverse.

The engine re-evaluates every request — there is no "session already allowed" carry-over. When the clock crosses the window edge, the next request gets the new verdict immediately.

Timezone¶

Windows evaluate against the engine's local wall clock by default. The [policy].time_window_tz knob in engine.conf switches this to UTC — see [policy] reference. On a local deployment, keep NTP in sync: a wrong system clock makes time-windows fire at the wrong times. Confirm what "local" means on the engine with show clock.

Validation¶

• A malformed time-window: in a hand-authored [policy].path file fails the reload loudly — egpolicy load exits non-zero and a live request policy reload reports failure, naming the file, the rule, and the problem. The previous good policy stays live (same strict-file behaviour as any other parse error).
• A malformed time-window: in a toolbox shared-dir file ([policy].shared_path) is not fatal — that one rule loads always-active with a Warning, and the rest of the load proceeds.

Scope of the 2026.31.0 implementation¶

The time-window: attribute described above is shipped and supported as of 2026.31.0 — author it directly in any .policy file under [policy].path or [policy].shared_path and the engine enforces it. Two adjacent capabilities other gateway products expose are deferred to a future release and are not yet available:

• Absolute one-shot windows — a specific calendar date range (Cisco IOS absolute / Palo Alto non-recurring). Today's time-window: is recurring weekly/daily only.
• Named, reusable time-range objects — defining BUSINESS-HOURS once and referencing it from many rules. Today the window is inline per rule; if two rules need the same hours, each spells out its own time-window:.

Pinned destinations¶

Certificate-pinned destinations — Windows Update, Apple MDM, mobile banking, several enterprise SaaS clients — refuse the forged leaf certificate Squid mints during bump-mode SSL inspection and fail closed. The historical workaround was a static bypass file outside the policy system; from 2026.35.0 onwards, pinned destinations are handled by policy, using the same match-* attributes and the same loader as block / permit rules.

A pin rule carries a pin: attribute instead of action::

pin-microsoft-update: {
    match-domain-list: /etc/enforcegate/rules.d/lists/pinned-microsoft.list
    pin: splice
    description: Microsoft cert-pinned endpoints
}

deny-pinned-app: {
    match-domain-list: /etc/enforcegate/rules.d/lists/blocked-pinned.list
    pin: terminate
    description: Block this pinned app entirely
}

The three pin: verdicts:

Matching is suffix-walk, identical to match-domain-list: for action: rules. A list entry windowsupdate.com pins *.windowsupdate.com; push.apple.com pins only *.push.apple.com, not apple.com. A host with no matching pin: rule defaults to bump — the engine inspects as normal.

pin: rules are orthogonal to action: rules. The pin: verdict is consulted at the SslBump peek step, before any certificate is forged; action: is consulted post-bump against the inspected request. A destination can be pinned (splice) and also have a permit / deny action: rule — the splice decides whether Squid sees the cleartext, the action decides what the engine does with it. For a host pinned to splice, the engine sees the SNI hostname only and any action: rule must match on that.

The connector's [ssl_bump_acl].fail_action knob controls what happens when the connector can't reach the engine for a peek-step verdict (engine down, session timeout). Default splice for availability — pinned apps keep working through an engine blip instead of breaking under a forced bump. Switch to bump for inspection-first deployments or terminate for fail-closed postures.

Pin rules are introspectable through the same verbs as action: rules — see show policy match, show policy list, and show policy summary for the operator-side views.

Available actions¶

warn and aup verdicts require the engine to see a usable client IP — that is, request_line_format = 1 (QF-3) on the connector side, since only QF-3 carries the client IP all the way through to the engine. With request_line_format = 0, warn/aup degrade to a terminal block page with no actionable CTA. See Squid connector — [redirector].

Managed categories¶

Exosys Curated Domain Lists are a signed, on-box managed-category feed — 50+ maintained categories (adult content, gambling, malware, phishing / threat-intel, ad-trackers, social networks, streaming, and more) that operators enforce with ordinary .policy rules. Unlike the community script ecosystem (where the operator sources and refreshes their own lists), the curated feed is maintained by Exosys and shipped as a single sealed file.

A rule gates on one or more categories with match-category::

deny-malware-and-phishing: {
    match-category: [ "malware", "phishing" ]
    action: deny
    description: Known-bad — blocked by Exosys curated threat feed
}

warn-gambling: {
    match-category: gambling
    action: warn
    description: Gambling — proceed with caution
}

match-category: composes with every other rule dimension — time-window:, match-client-ip:, match-method:, ack_scope: — and all four actions, inside the usual lowest-id-wins precedence. Matching is a single bounded host-suffix walk per request (host, then parent labels down to the registrable domain, Public-Suffix-List-aware so shared-host tenants stay isolated), then a bitwise category test — independent of the taxonomy size, so a rule against many categories costs no more than a rule against one.

Offline by design. The feed is a single file (/var/lib/enforcegate/managed.egsf by default) downloaded once at install and loaded at engine boot — no cloud lookup on the request path, and the deployment stays fully air-gapped after the initial download. Operators who opt in can pull incremental feed generations from the Exosys CDN (the feed publishes several times a day); a new generation is applied with request feed reload without an engine restart. The feed and its refresh cadence are configured in the [feed] block of engine.conf; the loaded generation and category counts are visible with show feed.

Managing policies¶

Two operator interfaces author and load policies:

• eghost policy — host-side operator commands. The recommended path for day-to-day work. Wraps file authoring (new, edit, show, list, remove) plus the compile-and-reload cycle, with $EDITOR integration. new, edit and remove recompile the policy set and tell the engine to reload on save / confirm — no separate reload step needed.
• egpolicy — the engine compilation utility that eghost policy calls. Use it directly only for bind-mount or docker cp edits, CI lints, and offline rebuilds.

For the online policy-reload verb operators run from the egctl REPL, see the egctl reference.