Engine¶

The EnforceGate vX engine processes requests received from local and remote connectors. It is the central intelligence component where all policy evaluation occurs. The engine maintains highly optimised in-memory match structures to scan request attributes (URI, SNI, user-agent, client IP, …) and persists compiled ACLs in a local DuckDB database.

The engine binary is /usr/local/bin/enforcegate-engine inside the standalone image. It runs as the unprivileged enforcegate user. Its long-running siblings are Squid (/usr/sbin/squid) and the Squid connector helper (/usr/local/bin/enforcegate-squid-connector); the connector is launched by Squid as a url_rewrite_program child, not by the container init.

When bump-mode SSL inspection is active, the engine also produces encrypted verdict-redirect payloads using the shared secret from the enforcegate-shared volume. The captive portal verifies and decrypts them on the visitor's behalf — see captive portal.

Command-line flags¶

Configuration file¶

The engine reads its configuration from a TOML file. The default location is /etc/enforcegate/engine.conf. The shipped default ships with eight sections — [global], [connectors], [license], [database], [policy], [learning], [captive_portal], [aaa] — plus an optional [logging] section. Each is described below.

Operator-tunable keys can be overridden via the bundle's .env file: matching ENFORCEGATE_* environment variables take precedence over the persisted conf at every boot, so .env wins. See your image's documentation for the variable-name to conf-key mapping.

[global]¶

Engine-wide tunables that don't fit a more specific section.

[connectors]¶

The [connectors] table contains one sub-table per declared connector. Each sub-table ([connectors.<name>]) describes one allowed peer. The engine accepts an incoming Defendr session only from a source IP that matches a configured [connectors.<name>].ip, after the connector authenticates with the shared key.

ip¶

In the standalone bundle the engine binds to 127.0.0.1 because the connector runs in the same container. Multi-image or distributed deployments override to 0.0.0.0.

key¶

In the standalone image, the generate-engine-key boot one-shot writes a random 32-character key into both files on first boot, so for the shipped deployment no manual configuration is required.

[license] — required for first boot¶

The license configuration. The engine refuses to start if any of serial, username, password is empty.

Override every credential field for test/prod tiers via .env (ENGINE_LICENSE_SERIAL, ENGINE_LICENSE_USERNAME, ENGINE_LICENSE_PASSWORD). The boot card prints a [ WARN ] line for the serial and username overrides; the password override is silenced (length-only) so credentials don't leak into docker logs.

[database]¶

Where the engine's DuckDB store lives.

[policy]¶

Policy source and snapshot configuration.

See policy rollback for the snapshot workflow and policy audit for the optional git-tracked history layer that sits on top of snapshots. The single source of truth for the live policy is the engine's DuckDB store at [database].database_file — see Inspecting the live policy for the operator-side ways to read it.

The active domain backend is reported by show database status and the detailed show system uri-engine verb — operators sizing memory against real numbers reach for the latter.

[learning]¶

Learning-mode (V1 shipped 2026-05-26) configuration. If the section is absent or database_file is unset, the learning subsystem stays silently disabled and request learning … calls return "learning subsystem not initialised".

See learning mode for the operator workflow.

[feed]¶

Configures the sealed managed-category feed behind the match-category: policy attribute. The feed is entitled by the license — a Licensed engine loads it, a Grace-state engine freezes at the boot generation, and a Floor-state engine drops it (see never bricks on a license lapse). A missing, unreadable, or rejected feed file is never fatal — the engine logs a Warning and match-category rules simply do not match.

Apply a newly-downloaded feed generation without restarting the engine with request feed reload; pull a newer generation from the Control Server on demand with request feed update; inspect the loaded generation with show feed, and query what the feed says about a specific domain with show feed lookup.

Automatic feed updates (on by default)¶

A fresh install from 2026.56.0 starts pulling automatically — auto_update ships true and the trust anchor (factory_pubkey) is pre-pinned in the image, so there is nothing to configure. The engine primes its first poll about 90 seconds after boot. If that poll fails or finds no usable feed yet — the fresh-install case, or a broken on-disk file — it retries every 60 seconds for up to five attempts before settling into the steady interval, so a fresh install typically has a feed within a few minutes rather than waiting out a full cycle. A failed poll never drops a feed that is already loaded.

> show feed
Generation: 3    Entitlement: licensed    Age: 40s

An existing deployment upgrading to 2026.56.0 is unaffected. auto_update is an ordinary engine.conf value: if your [feed] section was already written by an earlier install, it keeps whatever value is already on disk across the upgrade — the new default only applies to a section that does not exist yet. An upgrade never silently turns on outbound polling on a deployment that had it off.

Check or change the setting explicitly with eghost feed auto-update:

$ eghost feed auto-update
Automatic feed delivery: off

$ eghost feed auto-update on
Automatic feed delivery: off -> on. Recreate the engine to apply? [y/N]: y

Every key in the table above is also overridable directly from the bundle's .env, using an ENFORCEGATE_FEED_ prefix and the key name upper-cased — ENFORCEGATE_FEED_AUTO_UPDATE, ENFORCEGATE_FEED_POLL_INTERVAL_SECONDS, ENFORCEGATE_FEED_MIN_CONFIDENCE, and so on:

ENFORCEGATE_FEED_AUTO_UPDATE=false

eghost up

[captive_portal]¶

Captive portal v=1 integration. The engine produces encrypted verdict-redirect URLs with the shared secret; the squid connector relays the URL to client browsers as HTTP 301.

In the standalone bundle, the generate-engine-key boot one-shot mints the shared secret on first boot and writes it to the shared volume — no operator paste, no two-place drift.

Spec: see captive portal.

[aaa]¶

Authentication, authorisation and first-boot bootstrap.

See Privilege model below for the four levels and what each can do.

[control]¶

The Control API is the engine's HTTPS REST interface — egctl talks to it via docker exec and the captive portal sidecar reaches it server-side over the compose network for the /api/captive/ack round-trip.

ip¶

The default 0.0.0.0 inside the container makes :11225 reachable from the captive-portal sidecar across the compose network. The shipped docker-compose.yml does not publish :11225 to the host. For single-image deployments without a portal sidecar, lock down to 127.0.0.1 via ENGINE_CONTROL_API_IP=127.0.0.1 in .env.

port¶

The default 11225 matches egctl.conf's default and the captive portal sidecar's ENGINE_INTERNAL_URL.

TLS material¶

The Control API serves a self-signed X.509 certificate generated by the generate-ssl-certs boot one-shot on first boot. The portal sidecar verifies with verify=False because the TLS hop is loopback-equivalent inside the compose bridge; trust comes from the compose-network boundary, not from PKI verification. For egctl from outside the container, configure cert in egctl.conf to pin the certificate the engine serves.

[logging] (optional)¶

Logger configuration. Absent → file logger with default /var/log/enforcegate/engine.log and error level.

eghost shell                                                       # → /bin/sh in the enforcegate container
/usr/local/bin/enforcegate-engine --loglevel debug --logtype console

Diagnostic file¶

A top-level key (no enclosing section) that historically lived outside [license]:

Override via ENGINE_APM_DIAGNOSTIC_FILE only for tmpfs deployments, systemd-managed paths, or read-only-rootfs containers where a different writable path is required. The reason-string set is enumerated in the troubleshooting page.

Privilege model¶

EnforceGate vX uses a four-level privilege model for operator accounts. Each Control API verb checks the requesting user's privilege against a minimum threshold; verbs that mutate state require higher privileges than verbs that read state.

The four levels¶

Verb privilege thresholds¶

A representative sample of which egctl verbs each level can call:

Operational guidance¶

• Principle of least privilege. Give an analyst Monitoring (1), not Administrator (10), unless they need to mutate state.
• The request user * verbs enforce a must-outrank invariant: an Administrator cannot edit a Super-Administrator, and no user can remove themselves.
• The shipped default account is enforcegate / enforcegate-changeme at Super Administrator (11) — was admin / enforcegate-changeme pre-2026.43.1. On the appliance the installer prompts the operator to override both the username and the password in the wizard's Operator account step; on Docker bundles the operator sets ENFORCEGATE_ADMIN_USERNAME / ENFORCEGATE_ADMIN_PASSWORD in .env. If the shipped default is still in place after setup, eghost status raises an audit warning — change it via request user passwd <name> (after auth) or remove the account entirely once another Super Administrator exists.
• The bootstrap admin is provisioned at Super Administrator (11) so it can mint additional Administrator-level accounts via request user add directly out of the box — the must-outrank invariant requires the requestor to outrank any account it creates.

First-boot bootstrap¶

With [aaa].auto_bootstrap = true in engine.conf, the engine on first boot (when passwd is empty) generates a random admin password, writes the cleartext to bootstrap_credential_file, and logs it once at [critical]. The appliance installer surfaces the password in the setup wizard; on Docker bundles operators read it from the boot log.

File paths summary¶

For quick reference — what the engine reads and writes when configured with the shipped defaults: