Configure the Java microagent

The Sqreen Microagent reads four sources for its configuration. It follows the configurations from these sources in sequence. The order of precedence is as follows:

  1. environment variables
  2. Java system properties in the JVM command line
  3. a Java config.properties file
  4. default configuration options

Use environment variables or system property values (-D parameter) to set up your application.

  • environment variables
    export SQREEN_TOKEN=env_org_xxxxx
    export SQREEN_APP_NAME='My Awesome app'
    
  • system property values
    -Dsqreen.token=my_secret_token
    -Dsqreen.app_name=My Awesome App
    

Configuration variables

Use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables to configure the microagent's behavior.

Environment variable name Role config.properties key name Default value Allowed values
SQREEN_TOKEN The token is the identifier the Sqreen Platform uses to identify the microagent. Access your token in Account Settings > Environments & Tokens. token empty string
SQREEN_APP_NAME The application name as displayed on the Sqreen Dashboard. app_name webapp context path string
SQREEN_CONFIG_FILE Specifies a custom location for the config file. config_file empty string
SQREEN_LOG_LOCATION Specifies a custom file to which the microagent writes logs. log_location log/sqreen.log string
SQREEN_LOG_LEVEL Sets the microagent logging level. log_level WARN FATAL ERROR WARN INFO DEBUG
SQREEN_PROXY Specifies an HTTP proxy server for the microagent's connection to the Sqreen Platform. proxy empty See below for syntax.
SQREEN_IP_HEADER Specifies the header to use to extract the real IP address of a client. ip_header empty header name (case insensitive)
SQREEN_STRIP_SENSITIVE_DATA Removes personally identifiable information (PII) before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_data 1 (enabled) 1 (enabled), 0 (disabled)
SQREEN_STRIP_SENSITIVE_KEYS Comma-separated list of keys that removes specific sensitive information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_keys empty (uses default values) (arbitrary)
SQREEN_STRIP_SENSITIVE_REGEX Regular expression that removes specific sensitive information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_regex empty (uses default values) (arbitrary)
SQREEN_DISABLE Prevents the Sqreen microagent from starting. Any value in this environment variable disables Sqreen. disable false (Sqreen is enabled) boolean
SQREEN_IGNORED_PACKAGES_PREFIXES Comma-separated list of class/packages prefixes that Sqreen ignores. See Ignore packages and classes below. ignored_packages_prefixes empty a comma-separated list of class names and packages

Java system properties and properties file

If you wish, you can customize a location for the config.properties file. Customize the location if you want to configure more than one web applications running in the same application server.

Specify the location where the Sqreen microagent can find the config.properties file using one of the following methods.

  • Add system properties as JVM arguments using the -Dkey=value syntax. Always use the sqreen prefix to avoid conflicts. For example, -Dsqreen.config_file=config.properties.
  • Use the SQREEN_CONFIG_FILE environment variable to specify a custom location in your application's directory.
export SQREEN_CONFIG_FILE=/custom/path/config.properties

Sqreen identifies applications by their context path. Here is a sample configuration with two applications. :

# This is the default token
token=my_secret_token
# This will be the default application name, all web-applications deployed
# will be grouped in this application unless explicitly set
app_name=Default app

# --- App 1

# Configuration for an application deployed on /app1 context
# All attributes that start with the app1. prefix are used
app1.contextPath=/app1
app1.token=secret_token_for_app1
app1.app_name=App1

# --- App 2

app2.contextPath=/app2
# No token, so this app uses the default token
# This app has disabled sensitive data stripping
app2.strip_sensitive_data=false
# No app_name, thus this app will use the default app name

Here is a sample configuration of Java system properties:

-Dsqreen.token=my_secret_token
-Dsqreen.app_name=My Awesome App
-Dsqreen.log_location=log/sqreen.log
-Dsqreen.log_level=WARN
-Dsqreen.disable=false

Using a proxy

If you use an HTTP Proxy, use the following syntax where proxy-host is the hostname and 3128 the is the proxy port.

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

If your proxy uses authentication, provide user credentials in the proxy URI. For example, where bob is the username and secret123 is the password.

-Dsqreen.proxy=http://bob:secret123@proxy-host:3128/

PII scrubbing

The microagent does not send Personally Identifiable Information (PII) to the Sqreen Platform. With each heartbeat, the microagent scrubs the metadata to remove PII and replace it with Redacted by Sqreen. By default, the microagent scrubs the following values from the metadata it sends:

  • Values that look like they contain credit card numbers, according to a basic regular expression: ^(?:\d[ -]*?){13,16}$
  • Values associated with any of the following keys:
    • password
    • secret
    • passwd
    • authorization
    • api_key
    • apikey
    • Access_token

Turn off PII scrubbing

To turn off PII scrubbing, in the config.properties file, set strip_sensitive_data to 0 (disabled).

Customize PII scrubbing

You can customize the sensitive information that the microagent redacts.

  1. In the config.properties file, use strip_sensitive_keys to replace the default values (case insensitive) that the microagent redacts.

  2. In the config.properties file, use strip_sensitive_regex to replace the default values, including arrays, that match a regular expression. Be aware that adding a large number of regular expressions to this configuration may affect the application's performance.

For example, to scrub two parameters (user_id and user_private_token), and scrub values that contain the known pattern 0000-0000-0000, use the following configuration.

# append the 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.
# 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}'

Replace, not add

Be aware that the values you set in strip_sensitive_keys and strip_sensitive_regex replace the default values that the microagent redacts. In other words, the values you configure here are not added to the default values the microagent redacts, they override them

Set a custom truststore

Java microagent versions before 1.4.0

This section applies only to versions earlier than Sqreen Java Microagent 1.4.0. Update to the latest version of the Java microagent that uses an embedded keystore with known root Certificate Authority certificates as a transparent fallback.

The Sqreen Microagent communicates with the Sqreen Platform using HTTPS/TLS and the microagent's certificate. Successful communication depends on a root Certificate Authority (CA) certificate that the JVMs can trust. DigiCert provides the Sqreen root CA certificate. Most OpenJDK/Oracle Hotspot JVMs trust it by default, but in the following cases you must explicitly import the Sqreen root CA certificate in the Java keystore:

  • using a Docker image that ships with a minimal keystore
  • using a custom keystore where default CA certificates are absent
  • using a web app server, such as Websphere, that explicitly uses a minimal keystore

The terms keystore and truststore refer to the storage of keys and certificates. Keystore stores private keys, and truststore stores trusted certificates. You can split these two variants into distinct files but are both managed using the keytool command line utility.

  1. Download the root CA certificate and use the following command snippet to import it into your keystore. (/path/to/your/keystore = the location of 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
    
  2. Follow the prompt to enter a keystore password. The default password is changeit.

Websphere

  • The default truststore password is WebAS.
  • The truststore filename is trust.p12 and is set per-profile.
  • The truststore uses PKCS12 format, so you must add -storetype PKCS12 to the keytool command.
  • If using IBM J9 JVM, you must use the keytool version that shipped with it; you cannot use the Oracle or OpenJDK versions.

Use SecurityManager class

Java provides an execution sandbox through the SecurityManager class. This feature can sandbox browser Applets, RMI, and some application servers like Websphere. If you use this feature, you must explicitly grant rights to the Sqreen Microagent.

Assuming that sqreen.jar is in /path/to/sqreen, add these lines to your policy file:

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

Websphere

The policy file is server.policy and is set per-profile.

Use the JCE unrestricted policy

In countries that limit the use of cryptography, some JVMs ship with restrictions on key lengths by default. The Sqreen SSL/TLS certificate requires 4096 bits keys, so you must use the unlimited strength jurisdiction policy. Refer to your JVM vendor manual for reference on how to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

Please contact Sqreen support if you are unable to use the policy.

Ignore packages and classes

The Sqreen microagent builds a list of all the relevant classes that it must instrument in your app. While this process is usually very fast, there are some known cases where it can cause performance issues, such as when the app uses large libraries with signed packages.

If the instrumentation is slow, use the ignored_packages_prefixes property to get the Sqreen microagent to ignore specific classes. This property must contain a comma-separated list of class names and packages to ignore.