vX Engine¶

The EnforceGate vX Engine processes requests received from both local and remote connectors. It serves as the central intelligence component, where all the requests processing occurs. The engine employs highly optimized in-memory data structures to scan and evaluate various request attributes, such as HTTP URIs and User-Agent strings.

Access Control Lists (ACLs), policies, and configuration parameters are stored in a local database. The latter can be accessed remotely for management purposes.

The engine can also retrieve real-time threat intelligence by querying a remote API. This live data feed enables advanced zero-day protection against a broad range of threats, including malware, spear-phishing attacks, information leakage, illegal content, and other emerging risks.

Configuration File¶

The EnforceGate vX Engine can be configured and fine-tuned using its main configuration file. The latter is written in the TOML format; a format very similar in structure and readability to the classic .ini files found in Windows environments. No advanced syntax or complex grammar is required: the configuration file consist of simple key-value pairs organized in sections. This approach makes configuration both intuitive and easy to maintain.

The default location for the engine configuration file is /etc/enforcegate/engine.conf.

[global]¶

The optional global section (technically called a TOML table), as its name suggests, is used to define the engine' global configuration parameters such as the identifier and the user-configurable timers.

Parameters:

Name	Type	Description	Default
`asn`	string	The engine's Autonomous System Number (ASN)	`64512`
`ip`	string	The IP address on which the engine service listens	`127.0.0.1`
`port`	integer	The TCP port to listen on	`11224`
`retry`	integer	The retry timer interval in milliseconds	`30000`
`timeout`	integer	the timeout timer timeout in milliseconds	`60000`
`dead`	integer	The dead timer interval in milliseconds	`180000`

asn¶

The asn parameter specifies the Autonomous System Number (ASN) of the engine. An ASN is a unique 16-bit integer in the range of 1 to 65534, assigned to identify a distinct administrative entity in the EnforceGate ecosystem. By default the ASN value is 64512.

ip¶

The ip parameter specifies the IP address on which the engine listens for incoming connections.

port¶

The port parameter specifies the TCP port on which the engine listens for incoming connections. The default value is TCP port 11224.

retry¶

The retry parameter specifies the retry timer interval in milliseconds. By default, the retry timer is set to 30,000 milliseconds (equivalent to 30 seconds).

timeout¶

The timeout parameter specifies the duration in milliseconds after which an inactive neighbor is considered timed out. When a timeout occurs, a keepalive message is sent to verify that the neighbor is still alive.

dead¶

The dead parameter specifies the time interval in milliseconds after which a session neighbor (a connector) is declared dead if no message or keepalive is received. Upon reaching this timer, the neighbor is marked as dead and scheduled for removal from the internal sessions' states.

[logging]¶

The logging section defines parameters such as the logging level or threshold and the log file path.

Command-line Parameters

All logging parameters and settings can be overridden via command-line arguments. This is particularly useful for debugging purposes when starting the engine in the foreground from the command line.

Parameters:

Name	Type	Description	Default
`type`	string	The logging type	`file`
`level`	string	The logging level or threshold	`error`

type¶

The type parameter defines the logging type to use. The below logging types are currently supported:

Console: The logging information is display directly on standard output and is set to the error level by default.
File: Logs are written to a file. By default, logging is directed to /var/log/enforceGate/engine.log.

level¶

The logging level specifies the minimum severity at which log messages are displayed or written. By default, only messages at the error level and higher are recorded.

logging severity¶

Debuging Level

The debug level should be used only for debugging purposes, as it can generate a large volume of output and may impact performance. Exercise caution when enabling this level.

The following error levels (or severity) are supported:

Emergency
Alert
Critical
Error
Warning
Notice
Info
Debug

[license]¶

Online Activation Only

The license section and its associated parameters are required only for the initial license activation process. After successful activation, this section must be removed from the configuration file, as it is no longer needed.

The license section contains the licensing information required for registering and validating your engine's license.

Parameters:

Name	Type	Description
`serial`	string	Your license serial number
`username`	string	Your account username for license activation
`password`	string	Your account password

serial¶

The serial parameter must contain your serial number, which can be found on your account dashboard.

username¶

The username attribute must be set to your account username.

password¶

The password attribute must be set to your account password.

[aaa]¶

The aaa section contains the parameters related to the engine’s Authentication, Authorization, and Accounting (AAA) functions.

Parameters:

Name	Type	Description	Default
`passwd`	string	The path to the password file	`conf/passwd`

passwd¶

Check password file permissions

The password file must not be edited manually, and its permissions must be restricted to allow read and write access exclusively by the engine's user and group.

The passwd parameter specifies the path to the password file. This file contains the authentication credentials required for the engine authentication and closely resembles the combined format of the Linux /etc/passwd and /etc/shadow files.

[tls]¶

The tls section defines the Transport Layer Security (TLS) parameters used by the engine. TLS secures communication between the engine and its peers, including the connectors, API clients, and other components. For the TLS subsystem to function correctly, it must be able to load a valid private key, a corresponding X.509 server certificate and a CA certificate.

During installation, a key pair and self-signed certificate are automatically generated. You may replace them with your own certificate and key if desired.

Parameters:

Name	Type	Description	Default
`disable`	bool	Disable TLS support	`false`
`key`	string	The path to the private key file	`conf/ssl/key.pem`
`cert`	string	The path to the public key file	`conf/ssl/cert.pem`
`ca`	string	The path to the certificate authority certificate	`conf/ssl/ca.pem`
`dhparams`	string	The path to the DH parameters file	`conf/ssl/dhparams.pem`

disable¶

The disable parameter allows TLS support to be deactivated.

Performance Considerations

Disabling TLS may improve performance by reducing the per-request processing overhead associated with encryption. However, this enhancement is achieved at the cost of security.

Disabling TLS at the Peer Level

When the disabled attribute is set to true, ensure that TLS support is also explicitly disabled for the connectors as well. This configuration is required to allow session establishment over unencrypted connections and prevents unintended downgrades to insecure protocols without the administrator's explicit approval.

We strongly recommend against disabling TLS, as doing so leaves all communication between the engine and its peers vulnerable to man-in-the-middle attacks and eavesdropping.

key¶

The key parameter specifies the path to the private key file used by the TLS subsystem to secure communication channels.

Generate a Self-signed Certificate

You can manually generate a private and public key pair for the TLS subsystem to secure communication. The below example create a 4096-bits RSA key pair and write the private key and certificate to the server.key and server.crt file respectively. It will also generate a self-signed X.509 certificate for a validity of 720 days:

$ openssl req -x509 -newkey rsa:4096 -keyout server.key \
-out server.crt -sha256 -days 720 -nodes

cert¶

The cert parameter specifies the path to the X.509 server certificate file. The certificate must be valid and not expired.

ca¶

The ca parameter specifies the path to a valid Certificate Authority (CA) certificate bundle used to verify client certificates. In the case of a self-signed server certificate, this parameter may point to the same file as the server certificate specified in the cert parameter.

dhparams¶

The dhparams parameter may specify the path to a Diffie-Hellman parameters (DH params) file. We strongly recommend providing a valid DH parameters file to enable Perfect Forward Secrecy (PFS), which significantly enhances communication security.

Generate a DH Parameter File

To manually generate a Diffie-Hellman DH parameter file, you can use the openssl command-line utility, which is included with most Linux distributions. The below example generate a 4096-bits prime number and write the parameter file to dhparams.pem on the local directory:

$ openssl dhparam -out dhparams.pem 4096

[database]¶

The database section contains the parameters related to the database configuration.

Parameters:

Name	Type	Description	Default
`type`	string	The database type	`duckdb`
`host`	string	Hostname or IP address of the database	`127.0.0.1`
`database_file`	string	The path to the database file if applicable	`db/engine.db`
`port`	integer	The port number used by the database service
`user`	string	The username required for database authentication
`password`	string	The password required for database authentication
`database`	string	The database instance name	`EnforceGate`

type¶

The type parameter specifies the database engine to be used. As of this writing, only the duckdb type is supported.

host¶

The host parameter specifies the IP address or hostname for the database connection (applicable only when a client-server database type is selected).

database_file¶

The database_file parameter specifies the path to the database file (applicable when a file-based database type is used).

port¶

The port parameter specifies the port number where the database instance is listening to.

user¶

The user parameter specifies the username to be used to authenticate to the database.

password¶

The password parameter specifies the password used for authentication to the database.

database¶

The database parameter specifies the name of the database.

[control]¶

The control section contains the configuration parameters related to the control client API.

Parameters:

Name	Type	Description	Default
`ip`	string	The IP address on which the control API listens	`127.0.0.1`
`port`	integer	The TCP port to the control API serves on	`11225`
`key`	string	The path to the private key file	`conf/ssl/key.pem`
`cert`	string	The path to the public key file	`conf/ssl/cert.pem`
`dhparams`	string	The path to the DH parameters file	`conf/ssl/dhparams.pem`

ip¶

The ip parameter specifies the IP address on which the control API serves requests on.

port¶

The port parameter specifies the TCP port on which the control API binds. The default value is TCP port 11225.

key¶

The key parameter specifies the path to the private key file that corresponds to the generated SSL certficate.

Generate a Self-signed Certificate

You can manually generate a private and public key pair for the TLS subsystem to secure communication. The below example create a 4096-bits RSA key pair and write the private key and certificate to the server.key and server.crt file respectively. It will also generate a self-signed X.509 certificate for a validity of 720 days:

$ openssl req -x509 -newkey rsa:4096 -keyout server.key \
-out server.crt -sha256 -days 720 -nodes

cert¶

The cert parameter specifies the path to the X.509 server certificate file. The certificate must be valid and not expired.

dhparams¶

The dhparams parameter specifies the path to a Diffie-Hellman parameters (DH params) file. Providing this file enables cipher suites that support Perfect Forward Secrecy (PFS).

Generate a DH Parameter File

To manually generate a Diffie-Hellman DH parameter file, you can use the openssl command-line utility, which is included with most Linux distributions. The below example generate a 4096-bits prime number and write the parameter file to dhparams.pem on the local directory:

$ openssl dhparam -out dhparams.pem 4096

[connectors]¶

The connectors section contains the configuration parameters to apply for all connectors, along with entries or sub-tables that describe each individual connector.

[connectors.entry]¶

Each connector must be declared individually by creating a separate entry (sub-table) within the connectors section.

Parameters:

Name	Type	Description	Default
`ip`	string	The IP address of the connector
`key`	string	The shared authentication key

ip¶

The ip parameter specifies the IP address of the local or remote connector. This parameter serves as a key and must match the source IP address used by the connector when establishing a session with the engine.

key¶

Mandatory Key Attribute

By default, EnforceGate enforces mutual peer authentication between the engine and the connectors. For this reason, the key attribute is mandatory and must be explicitly configured.

The key attribute value set the shared key used for mutual peer authentication. Any string of up to 128 characters may be used; longer strings will be truncated.