Configuring the Next-Gen WAF agent

The following are the current configuration options (as of v4.75.0 on the linux platform). You can view these options on the installed Agent version by running with the --usage command line option.

Configuration options

The configuration options are as follows:

	Name	Type	Status	Description	Default
	accesskeyid	string		Set access key ID, required in most cases
	anonymous-ip-secret-key	string		Set anonymous IP secret key. Default is to use secretaccesskey when generating anonymous IP addresses
	bypass-egress-proxy-for-upstreams	boolean		Exclude all upstream traffic from using the egress proxy	false
	cleaner-interval	time-duration		How often to run cleanup routine	10s
	client-ip-header	string		Specify the request header containing the client IP address	X-Forwarded-For
	config	string		Specify the configuration file	/etc/sigsci/agent.conf
	context-expiration	time-duration		How long to keep request context to match with response before cleanup	10s
	custom-request-headers	string		Add custom headers to the RPC response, which will be added to the HTTP request by the module [format is CSV if name:val pairs with $AgentResponse, $RequestID, $TagList dynamic values]
	debug-log-all-the-things	boolean		Log all the things	false
	debug-log-blocked-requests	boolean		Log when a request is blocked	false
	debug-log-config-updates	integer		Log when config updated or checked, 0=off, 1=updated, 2=more details	0
	debug-log-connection-errors	integer		Log when connections are dropped due an error. 0=off,1=on	0
	debug-log-engine-errors	integer		Log WAF engine errors: 0=off, 1=on, 2=verbose	1
	debug-log-proxy-requests	boolean		Generates debug output of proxied requests	false
	debug-log-rpc-data	string		Log (hexdump) raw RPC data to the given file
	debug-log-uploads	integer		Log what is being sent to Signal Sciences: 0=off, 1=json, 2=json-pretty	0
	debug-log-web-inputs	integer		Log web inputs coming from the module: 0=off, 1=json, 2=json-pretty	0
	debug-log-web-outputs	integer		Log web outputs going back to the module: 0=off,1=json,2=json-pretty	0
	debug-standalone	integer		Bitfield: 0=normal, 1=no upload, 2=no download, 3=no networking, 4=use empty rules, 7=no net+empty rules	0
	download-cdn-url	string		CDN URL to check and download new configurations before checking download-url, empty string disables CDN fetch	https://wafconf.signalsciences.net
	download-config-cache	string		Filename to cache latest downloaded config (if relative, then base it on shared-cache-dir)
	download-config-version	integer		Force the downloader to download a specific config version: 0=auto versioning	0
	download-failover-url	string		URL to check and download new configurations if download-url is not available	https://sigsci-agent-wafconf-us-west-2.s3.amazonaws.com
	download-interval	time-duration		How often to check for a new configuration	30s
	download-url	string		URL to check and download new configurations	https://sigsci-agent-wafconf.s3.amazonaws.com
	envoy-expect-response-data	integer		Expect response data from envoy: 0=response data is not expected and some dependent product features will not be available, 1=agent will wait for response data via http_grpc_access_log gRPC API	0
	envoy-grpc-address	string		Envoy gRPC address to listen on (unix domain socket path or host:port)
	envoy-grpc-cert	string		Envoy gRPC optional TLS cert file (PEM format)
	envoy-grpc-key	string		Envoy gRPC optional TLS key file (PEM format)
	haproxy-spoa-address	string		Haproxy SPOA address to listen on (unix domain socket path or host:port)	unix:/var/run/sigsci-ha.sock
	haproxy-spoa-enabled	boolean		Haproxy SPOA agent enabled	false
	haproxy-spoa-lua-enabled	boolean		Haproxy SPOA Lua support enabled to edit response headers	false
	--help			(commandline only option) Dump basic help text
	inspection-alt-response-codes	csv-integer		DO NOT USE: the alternative response code concept is deprecated - all codes 300-599 are now considered blocking codes and this option will be removed
	inspection-anomaly-duration	time-duration		Envoy/revproxy global duration after which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection	1s
	inspection-anomaly-size	integer		Envoy/revproxy global response size limit which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection	524288
	inspection-debug	boolean		Envoy/revproxy global enable/disable inspection debug logging	false
	inspection-max-content-length	integer		Envoy/revproxy global max request content length that is allowed to be inspected	307200
	inspection-timeout	time-duration		Envoy/revproxy global inspection timeout after which the system will fail open	100ms
	jaeger-tracing	boolean		Enables jaeger tracing - configured with JAEGER\_\* environment variables (currently for envoy only)	false
	--legal			(commandline only option) Show legal information and exit
	local-networks	string		Set local networks for determining the real client IP (CSV of CIDR, 'all', 'none', or 'private'). These are the networks trusted to set the client IP header.	all
	log-out	string		Log output location, 'stderr', 'stdout', or file name (NOTE: on Windows, important logs will be sent to the eventlog)
	max-backlog	integer		Maximum RPC requests in queue (by default scaled with rpc-workers)	0
	max-connections	integer		Maximum in-flight RPC connections (by default scaled with rpc-workers)	0
	max-inspecting	integer		Reverse proxy only - maximum in-flight transactions that the engine can be inspecting, 0=unlimited	0
	max-logs	integer		Maximum number of log lines held while waiting to send upstream	1000
	max-procs	string		Maximum number or percentage of CPUs (cores) to use e.g max-procs=4 or max-procs="100%".
	max-records	integer		Maximum number of records held while waiting to send (by default scaled with rpc-workers)	0
	reverse-proxy	boolean		Enable the reverse proxy, which requires setting a listener and upstream	false
	reverse-proxy-tls-min-version	string		Reverse proxy TLS listener min version	1.0
	revproxy-reload-on-update	boolean		Reload the reverse proxy service config on agent config updates to support dynamic reconfiguration (only functions on OSes that support zero downtime restarts such as Linux >= 3.9 kernel)	false
	rpc-address	string		RPC address to listen on and serve modules from	unix:/var/run/sigsci.sock
	rpc-version	integer		RPC protocol version	0
	rpc-workers	integer		RPC workers to use. If unset, then the max-procs value will be used	0
	sample-percent	integer		Sample input, 100=process everything, 0=ignore everything	100
	secretaccesskey	string		Set secretaccesskey, required along with accesskeyid in most cases
	server-flavor	string		Server-flavor, allow distinguishing this revproxy install as a buildpack or other flavor.
	server-hostname	string		Server hostname. By default, the agent asks the OS for the hostname configuration unless a value is configured here.
	service-shutdown-timeout	time-duration		Timeout waiting for pending transactions to complete during service shutdown	2s
	shared-cache-dir	string		Base directory for any cache files	/tmp/sigsci-agent.cache
	--show-tls-cipher-suites			(commandline only option) Show available TLS cipher suites and exit
	startup-probe-filepath	string		Filepath to create file checked by startup probes. Creates the file once the agent has loaded a ruleset. Ex: /sigsci/tmp/startup
	startup-probe-listener	string		HTTP listener for responding to startup probes. Returns HTTP 200 once the agent has loaded a ruleset. Ex: 0.0.0.0:2024
	statsd-address	string		Set the statsd address to send metrics to (e.g., hostname:port or unix:///path/socket)
	statsd-metrics	csv-string		Set the statsd metrics filter (glob patterns allowed - assumed prefix if no patterns used)	*
	statsd-type	string		Set the statsd server type to enable advanced features (e.g., statsd or dogstatsd)	statsd
	upload-log	string		Log filename to write agent event data
	upload-log-header-map	boolean		HTTP request,response header data in map format	false
	upload-syslog	boolean		Write agent event data to syslog	false
	upload-url	string		URL to upload agent data	https://c.signalsciences.net/0/push
	--usage			(commandline only option) Dump full usage text
	validate-config	boolean		Validate the config entries provided to warn against potentially invalid entries	true
	--version			(commandline only option) Show version information and exit
	waf-data-log	string		Filename to log WAF inspection data (currently JSON format). Using "eventlog" on Windows will send these to the eventlog. Requests are logged to the provided location if they have at least one signal added by default inspectors or if they have at least one signal added by a request rule with a Request logging value of Sampled.
	waf-data-log-all	boolean		When logging WAF inspection data, log every request not just those with signals.	false
	windows-eventlog-level	integer		Set the windows eventlog level (use names that will be converted to integers: debug, info, warning, error, or none).	3

Reverse proxy listener options

Reverse proxy mode supports multiple listeners. In the configuration file, each listener is defined in a revproxy-listener block that has its own set of directives. Each block is formatted as a TOML table. Each block must:

• have a unique name in the format [revproxy-listener.NAME], where NAME is a string that you define.
• be located at the end of the configuration after all other global options.

Alternatively, use command-line options or environment variables with this format:

• --option='name1:{opt=val,...};name2:{opt=val,...}'
• SIGSCI_OPTION='name1:{opt=val,...};name2:{opt=val,...}'

For more details and an example, check out our Reverse proxy listener configuration section.

	Name	Type	Status	Description	Default
	access-log	string		Access log filename
	close-conn-on-request-smuggling	boolean		'Connection: close' header will be added to requests that appear to be HTTP Request Smuggling attacks	false
	conn-idle-max	integer		Max idle connections in the upstream connection pool (0 will disable connection pooling)	100
	conn-idle-timeout	time-duration		Idle connection timeout for the upstream connection pool	1m30s
	conn-keepalive	time-duration		Connection keepalive interval for upstream connections	30s
	conn-max-per-host	integer		Maximum total number of upstream connections in any state per host (0 is unlimited). Connections over the limit will block until more are available	0
	conn-timeout	time-duration		Connection timeout for upstream connections	30s
	enabled	boolean		Enable/disable the reverse proxy listener	true
	expect-continue-timeout	time-duration		Timeout waiting for 'continue' after 'expect' for upstream traffic	1s
	expose-raw-headers	boolean		This experimental option replaces 'close-conn-on-request-smuggling' functionality. The option will need to be enabled per each reverse proxy listener.	true
	extend-content-types	boolean		Enables extended content inspection while running in reverse proxy mode	false
	grpc	boolean		Enable proxying and inspection of gRPC traffic	false
	http2	boolean		Enable HTTP/2 support for the listener	true
	http2-upstreams	boolean		Prefer HTTP/2 for the upstreams	true
	idle-timeout	time-duration		Network idle timeout for the listener	0s
	inspect-websocket	boolean		Enable/disable websocket inspection	false
	inspection-alt-response-codes	csv-integer		DO NOT USE: the alternative response code concept is deprecated - all codes 300-599 are now considered blocking codes and this option will be removed
	inspection-anomaly-duration	time-duration		Duration after which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection	1s
	inspection-anomaly-size	integer		Response size limit which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection	524288
	inspection-debug	boolean		Enable/disable inspection debug logging	false
	inspection-max-content-length	integer		Max request content length that is allowed to be inspected	307200
	inspection-timeout	time-duration		Inspection timeout after which the system will fail open	100ms
	listener	string		Listener URL [scheme://address:port]
	log-all-errors	boolean		Log all errors, not just common	false
	minimal-header-rewriting	boolean		Minimal header rewriting. If enabled, then only hop-by-hop headers will be removed as required by RFC-2616 sec 13.5.1. No proxy headers will be added/modified, though they will be passed through if trust-proxy-headers is set	false
	pass-host-header	boolean		Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation)	true
	read-buffer-size	integer		Configures the size of the network transport's read buffer in bytes	4096
	read-timeout	time-duration		Network read timeout for the listener	0s
	remove-hop-header	boolean		Unused hop headers will be removed from forwarded requests	true
	request-timeout	time-duration		Overall request timeout (will enable buffering, which may cause issues with streaming services)	0s
	response-flush-interval	time-duration		Interval to flush any buffered/streaming response data (0 disables forced flushes; -1 forces flushes after every write; interval values force flushes on a fixed time interval)	0s
	response-header-timeout	time-duration		Response header timeout waiting for upstream responses	0s
	shutdown-timeout	time-duration		Timeout waiting for pending transactions to complete during server shutdown	30s
	tls-ca-roots	string		TLS trusted certificate authority certificates file (PEM format)
	tls-cert	string		TLS certificate file (PEM format)
	tls-cipher-suites	csv-string		TLS listener cipher suites. Only affects TLS 1.2 and below. [use --show-tls-cipher-suites for a list]	TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256,TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA,TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA
	tls-handshake-timeout	time-duration		TLS handshake timeout for upstream connections	10s
	tls-insecure-skip-verify	boolean		Insecurely skip upstream TLS verification (for self signed certs, etc.)	false
	tls-key	string		TLS private key file (PEM format)
	tls-key-passphrase	string		TLS private key passphrase in the format type:data, where type is one of: pass or file (EX: pass:mypassword or file:/etc/secrets/tls-key-passphrase)
	tls-min-version	string		TLS listener min version	1.0
	tls-verify-servername	string		Force the servername used in upstream TLS verification; consider using pass-host-header first, but this may be required if neither the hostname used by the downstream client nor the hostname/ip used in the upstream URL is listed in the upstream TLS certificate
	trust-proxy-headers	boolean		Trust the incoming proxy (X-Forwarded-For*) header values. If not trusted, then incoming proxy headers are removed before any additions are made	true
	upstreams	csv-string		Upstream, comma separated upstream URLs [scheme://address:port]
	write-buffer-size	integer		Configures the size of the network transport's write buffer in bytes	4096
	write-timeout	time-duration		Network write timeout for the listener	0s

System environment options

These system level environment variable based options will also affect processing.

	Name	Type	Status	Description
	HTTP_PROXY or http_proxy	url		Proxy outbound HTTP requests through the proxy at the defined URL
	HTTPS_PROXY or https_proxy	url		Proxy outbound HTTPS requests through the proxy at the defined URL (takes precedence over HTTP_PROXY for HTTPS requests)
	NO_PROXY or no_proxy	csv-url		Comma separated list of URLs NOT to proxy or '*' for all URLs

The options are generally available in three forms, overridden in the following order:

1. In the configuration file (default: /etc/sigsci/agent.conf)
2. On the command line, prefixed with a double dash (--) (e.g., --help)
3. As an environment variable, all capitalized, prefixed with SIGSCI_ and dashes changed to underscores (_) (e.g., the max-procs option would become the SIGSCI_MAX_PROCS environment variable)

There are a few exceptions:

• Informational options such as --help, --legal, and --version only make sense as command line options as noted.
• The HTTP_PROXY environment variable is deprecated and will no longer be honored for https connections. HTTPS_PROXY must be used.
• The agent will honor the system HTTPS_PROXY environment variable allowing configuration of an egress HTTPS proxy URL for those sites where outbound access must be through a proxy (e.g., HTTPS_PROXY=http://10.0.0.1:8080).

Configuring FIPS 140-3 compliance for the agent

The Next-Gen WAF agent libraries and backend connections are FIPS 140-3 compliant when FIPS 140-3 mode is enabled. FIPS 140-3 is a North American security standard used to ensure hardware and software are secure, tamper-resistant, and properly implemented to protect sensitive information.

kill -s USR1 `pidof sigsci-agent`

Configuring HTTPS proxy for the agent

If the system the agent is running on does not have direct internet access, it may need to be configured to access the internet via a HTTPS proxy. To do this, one or more of the HTTPS_PROXY, or NO_PROXY system environment variables will need to be configured.

While some systems may set this system wide, we recommend using the proxy for only the Next-Gen WAF agent.

Also, note that the package the agent relies on to determine the proxy URL from HTTPS_PROXY, NO_PROXY variables, ignores localhost or loopback addresses (e.g., 127.0.0.1, 0.0.0.0) with or without the port number. If you are relying on HTTPS_PROXY or NO_PROXY environment variables to be set with either of the aforementioned addresses, use a fully qualified domain name (FQDN) via the operating systems host file (e.g., c:\Windows\System32\Drivers\etc\hosts or /etc/hosts) and use it as the value.

HTTPS_PROXY=http://10.0.0.1:8080

$ export HTTPS_PROXY=http://10.0.0.1:8080

Configuring the agent to use a proxy for egress traffic

The agent can be configured to use a local proxy for egress traffic to the Fastly cloud infrastructure by setting the HTTPS_PROXY environment variable. Add the following line to /etc/default/sigsci-agent, replacing IP-OR-HOST-NAME with the IP address or hostname to proxy traffic to:

export HTTPS_PROXY=IP-OR-HOSTNAME

Restart the agent and verify the configuration.

Next steps

Explore our module options and install the Next-Gen WAF module.