Advanced Configuration in Java


Configuration variables

System property values override environment variables.

Sqreen agent can be configured using :

  • environment variables
  • Java system properties in JVM command line
  • a Java properties file

Here are the parameters that can be configured:

Variable name Description properties key name Default value
SQREEN_TOKEN Sqreen token. This identifies agent to Sqreen backend servers token Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location ${java.io.tmpdir}/sqreen.log
SQREEN_LOG_LEVEL Sqreen logging level log_level WARN
SQREEN_CONFIG_FILE Properties configuration config_file Empty
SQREEN_DISABLE Prevents Sqreen agent from starting. Any value in this environment variable will disable Sqreen. disable false (Sqreen is enabled)
SQREEN_PROXY A URI in the form http://host:port, socks://host:port or direct:///. Forces the usage of a different proxy server (or no proxy at all) from the JVM's defaults proxy Empty (no proxy)
SQREEN_STRIP_SENSITIVE_DATA Remove sensitive data before sending them to Sqreen strip_sensitive_data true
SQREEN_STRIP_SENSITIVE_KEYS Comma separated list of keys to strip, refer to dedicated section below for details strip_sensitive_keys see here for default values
SQREEN_STRIP_SENSITIVE_REGEX Regular expression used for value stripping, refer to dedicated section below for details strip_sentitive_regex see here for default values
SQREEN_IP_HEADER The request HTTP header to use to get client IP address. (eg. X_FORWARDED_FOR) ip_header Empty

Java properties configuration

In order to use a java properties file for configuration, you will have to provide the configuration file config.properties through:

  • Java system property -Dsqreen.config_file=config.properties in your JVM arguments.
  • Environment variable SQREEN_CONFIG_FILE=config.properties.

Using this configuration format is recommended if you want to configure multiple web applications running in the same application server. Applications are identified by their context path.

Here is a sample configuration with two applications:

# this will be the default token
token=my_secret_token

# configuration for application deployed on /app1 context
# all attributes that will start with app1. prefix will be used
app1.contextPath=/app1
app1.token=secret_token_for_app1

app2.contextPath=/app2
# no token, this app will use the default token
# also, this app has disabled sensitive data stripping
app2.strip_sensitive_data=false

System property sample configuration

Those parameters needs to be provided as JVM argument by using the -Dkey=value syntax. Also, please note that they have to use the sqreen prefix to prevent any conflict.

-Dsqreen.token=my_secret_token 
-Dsqreen.log_location=log/sqreen.log
-Dsqreen.log_level=WARN
-Dsqreen.disable=false

Using a Proxy

When using an HTTP Proxy, where proxy-host is your proxy hostname and 3128 your proxy port.

-Dsqreen.proxy=http://proxy-host:3128/

PII scrubbing

Default PII scrubbing values are listed in PII Scrubbing.

Changing sensitive keys configuration will override defaults, thus you will probably have to append your extra keys to the list of predefined keys. Same for sensitive regex, you will need to combine with existing value.

As an example, if we want to:

  • scrub parameters that are named user_id and user_private_token.
  • scrub values that contain a known pattern 0000-0000-0000 defined by regex [0-9]{4}-[0-9]{4}-[0-9]{4}

We will have to use this configuration:

# we just append our extra parameter names to the default list
-Dsqreen.strip_sensitive_keys=password,secret,passwd,authorization,api_key,apikey,access_token,user_id,user_private_token
# regex here is enclosed in single quotes to prevent shell interpolation.
# The default value here is a common pattern for credit cards
# our pattern is defined using the [0-9]{4}-[0-9]{4}-[0-9]{4} regular expression.
# we just have to combine it with | to the default value for credit cards (?:\d[ -]*?){13,16}
-Dsqreen.strip_sensitive_regex='(?:\d[ -]*?){13,16}|[0-9]{4}-[0-9]{4}-[0-9]{4}'

Custom truststore

Our certificate used for HTTPS/TLS communication between agent and our servers depends on a root Certificate Authority (CA) certificate to be trusted by JVMs.

The terms keystore and truststore both refer to the storage of keys and certificates, the only difference is that keystore is intended for (private) key storage, and truststore for trusted certificates. Those two variants can be split apart in distinct files but are both managed using the keytool command line utility.

Our root CA certificate is provided by DigiCert and is trusted by default by most OpenJDK/Oracle Hotspot JVMs. However, in few cases an explicit import in Java keystore is required :

  • some Docker images ship with a minimal keystore.
  • using a custom keystore where default CAs certificates are absent.
  • some containers (like Websphere) explicitly use a minimal keystore.

In those cases, you will have to import our root certificate into your truststore.

Root CA certificate can be downloaded here. You can use the following command snippet to import into your keystore.

curl https://dl.cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt -o /tmp/rootca.crt
keytool -import -alias sqreen_digicert_root_ca -file /tmp/rootca.crt -keystore /path/to/your/keystore

Where /path/to/your/keystore is the location of keystore. You will be prompted for a keystore password, by default changeit is used.

For Websphere:

  • the default truststore password is WebAS.
  • the truststore filename is trust.p12 and is set per-profile.
  • the truststore used PKCS12 format, thus you have to add -storetype PKCS12 to the keytool command.
  • If using IBM J9 JVM, you have to use the keytool version shipped with it, you can't use Oracle or OpenJDK version.

Security manager

Java provides an execution sandbox through the SecurityManager class. This feature is used to sandbox browser Applets, RMI and also some application servers like Websphere.

When used, this feature will require to explicitly grant rights to our agent.

Configuration of this feature is done through policy files.

Assuming that sqreen.jar is located in /path/to/sqreen, you will have to add those lines to your policy file.

// Allow Sqreen
grant codeBase "file:/path/to/sqreen/sqreen.jar" {
  permission java.security.AllPermission;
};

For Websphere:

  • the policy file is named server.policy and is set per-profile.

Limited cryptography

In some countries, usage of cryptography is limited, therefore some JVMs are shipped by default with restrictions on key lengths.

Our SSL/TLS certificate requires to be able to support 4096 bits keys, thus you will have to use the unrestricted policy. If you can't, please contact us.

Refer to your JVM vendor manual for reference on how to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.