Configure the Go microagent¶

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

environment variables
sqreen.yml file
default configuration options

Configuration variables¶

The table below lists the variables you can use to customize the Sqreen microagent's configuration.

Environment variable name	Role	YAML key name	Default value	Allowed values
`SQREEN_DISABLE`	Prevents the Sqreen agent from starting. Any value in this environment variable disables Sqreen.	`disable`	`false` (Sqreen is enabled)	boolean
`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`	empty	string
`SQREEN_CONFIG_FILE`	Specifies a custom location for the YAML-based config file		empty	string
`SQREEN_LOG_LEVEL`	Sets the microagent logging level.	`log_level`	INFO	FATAL ERROR WARN INFO DEBUG
`SQREEN_PROXY`	Specifies an HTTP proxy server for the microagent's connection to the Sqreen Platform.	`proxy`	empty	proxy URI (`http://proxy:port`)
`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_IP_HEADER_FORMAT`	Specifies the value format of the configured header `SQREEN_IP_HEADER` to find the real IP address of a client. It only supports `%{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid`.	`ip_header_format`	empty	`%{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid`
`SQREEN_STRIP_HTTP_REFERER`	Disables sending the HTTP header `Referer` to Sqreen when not empty.	`strip_http_referer`	empty	boolean
`SQREEN_STRIP_SENSITIVE_KEY_REGEX`	Regular expression that removes specific sensitive key information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details.	`strip_sentitive_key_regex`	`(?i)(passw(((or)?d))\|(phrase))\|(secret)\|(authorization)\|(api_?key)\|((access_?)?token)`	(arbitrary)
`SQREEN_STRIP_SENSITIVE_VALUE_REGEX`	Regular expression that removes specific sensitive value information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details.	`strip_sentitive_value_regex`	`(?:\d[ -]*?){13,16}`	(arbitrary)

YAML file¶

The Sqreen Microagent stores configurations in the sqreen.yml file. The microagent detects the application root based on its installation folder. Save the sqreen.yml file in the top level folder in your application.

If you wish, you can customize a location for the YAML file. Use the SQREEN_CONFIG_FILE environment variable to specify a custom location in your application's directory.

export SQREEN_CONFIG_FILE=/custom/path/sqreen.yml

When you edit the sqreen.yaml configuration file, be sure to indent with two spaces. If you do not indent correctly, the Sqreen microagent throws an error at startup: Unable to parse configuration file.

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 sqreen.yml file, set disable to true.

Customize PII scrubbing¶

You can customize the sensitive information that the microagent redacts.

In the sqreen.yml file, use strip_sensitive_key_regexp and strip_sensitive_value_regexpto replace the default values (case insensitive) that the microagent redacts. Refer to the Go regular expression syntax RE2 documentation for more details.

When a key matches the key regular expression strip_sensitive_key_regexp, the microagent recursively redacts its associated value, no matter the value and regardless of the value regular expression strip_sensitive_value_regexp. The default regular expression matches case-insensitive keys passwd, password, passphrase, secret, authorization, api_key, apikey, accesstoken, access_token and token.
When a value matches the value regular expression strip_sensitive_value_regexp, the microagent redacts it. The microagent ignores this regular expression when the associated key matches the key regular expression strip_sensitive_key_regexp. The default regular expression matches credit card numbers.

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

Example 1: You can scrub values whose keys match the case-insensitive string email or passport_id by setting strip_sensitive_key_regexp to (?i)^(email)|(passport_id)$. See Regex documentation.

{
  "uid": "foo",
-   "email": "user@email.com",
+   "email": "<Redacted by Sqreen>",
-   "passport_id": "abcd"
+   "passport_id": "<Redacted by Sqreen>"
}

{
  "uid": "bar",
  "email": {
-   "primary": "user@email1.com"
+   "primary": "<Redacted by Sqreen>"
-   "secondary": "user@email2.com"
+   "secondary": "<Redacted by Sqreen>"
  }
}

Example 2: You can scrub values matching emails by setting strip_sensitive_value_regexpto(?i)^.+\@.+..+$` See Regex documentation.

{
  "uid": "foo",
- "email": "user@email.com",
+ "email": "<Redacted by Sqreen>",
  "passport_id": "abcd"
}

{
  "uid": "bar",
  "email": {
-   "primary": "user@email1.com"
+   "primary": "<Redacted by Sqreen>"
-   "secondary": "user@email2.com"
+   "secondary": "<Redacted by Sqreen>"
  }
}

Configure Go handler¶

A Go application uses the context of a request to properly abort sub-operations and goroutines. When the Sqreen microagent detects an attack and cancels the context of a request, the application's handler sub-operations, such as SQL queries, must use the context of the request to properly abort.

The middleware function also uses the context of a request to store everything that the microagent requires to protect your app. If the microagent cancels the context of a request, the middleware functions become disabled.

The following is an example of a handler that properly uses the request context resulting in proper functionality of the Sqreen microagent.

func handler(w http.ResponseWrite, r *http.Request) {
  unsafe := r.FormValue("id")
  rows, err := db.QueryContext(r.Context(), "select id, name from users where id=" + unsafe)
  if err != nil {
    log.Error(err)
    return
  }
  defer rows.Close()
  // ...
}