# Sensitive data obfuscation

As any application monitoring system, the data collected by groundcover is by nature sensitive and contains payloads of full requests and queries. Raw traces can go a long way in a troubleshooting process, but you can choose to obfuscate their payload.

{% hint style="info" %}
By default groundcover does **not** obfuscate payloads. However, it will obfuscate sensitive HTTP and gRPC headers - see [below](#sensitive-headers-obfuscation) for more information.
{% endhint %}

### Configuration

Obfuscation is granularly defined separately for each protocol, using the following names:

* `httphandler`
* `grpchandler`
* `redishandler`
* `sqlhandler`
  * This applies both for MySQL and PostgreSQL
* `mongodbhandler`
* `amqphandler`

Data obfuscation can be configured in two ways: **key-value** and **unstructured.**

#### Key-Value obfuscation

This method will automatically identify key-value structures such as JSON and query params, and for those it will perform obfuscation based on a defined set of keys.

The configuration consists of the following fields:

* `enabled` - turns this obfuscator on and off. **Default:** false
* `mode` - What should be done with values matching the specified keys. Possible modes are:
  * `KeepSpecificValues` - Obfuscate all values **except** for keys specified in `specificKeys`
  * `ObfuscateSpecificValues` - Keep all values and obfuscate **only** values for keys specified in `specificKeys`
* `caseSensitive` - are the keys case sensitive. **Default:** False
* `specificKeys` - a list of comma separated strings. Example:

  ```yaml
          specificKeys: ["keep-me", "keep-me-too"]
  ```

{% hint style="info" %}
If mode is not specified, the default behavior of this obfuscator is to obfuscate all keys, equivalent to:

* mode: `KeepSpecificValues`
* specificKeys: \[]
  {% endhint %}

{% hint style="info" %}
Obfuscation for nested JSON structures is based on the inner keys within the nested JSON objects. An example can be found at [#obfuscation-examples](#obfuscation-examples "mention")
{% endhint %}

Below is an example of using the key-value configuration with different settings:

```yaml
agent:
  sensor:
    httphandler:
      obfuscationConfig:
        keyValueConfig: 
          enabled: true
          mode: "KeepSpecificValues"
          specificKeys: ["keep-me"]
    mongodbhandler:
      obfuscationConfig:
        keyValueConfig: 
          enabled: true
          mode: "ObfuscateSpecificValues"
          caseSensitive: true # keys will be case sensitive
          specificKeys: ["obfuscate-me"]
```

#### Unstructured obfuscation

This method will obfucsate "free text" without any predefined rules. It is meant as a way to make sure all data is obfuscated regardless of its contents.

The configuration exists of the following fields:

* `Enabled` - Turns this obfuscator on and off. **Default**: false

Below is an example of turning on the unstructured obfuscator:

```yaml
agent:
  sensor:
    httphandler:
      obfuscationConfig:
        unstructuredConfig: 
          enabled: true
```

#### Combining the obfuscators

It's perfectly fine to use both the key-value and unstructured obfuscators together! When this is set, the key-value method will be executed first, and only if the structure isn't key-value, it will proceed to the unstructured method.

For example, let's look at a configuration for turning both obfuscators on:

```yaml
agent:
  sensor:
    httphandler:
      obfuscationConfig:
        keyValueConfig: 
          enabled: true
          mode: "ObfuscateSpecificValues"
          specificKeys: ["key"]
        unstructuredConfig:
          enabled: true
```

#### Obfuscation Examples

* JSON, `{"key": "value"}`
  * `{"key": "?"}`
* JSON with array, `{"key": [1,2,3]}`
  * `{"key": ["?", "?", "?"]}`
* JSON with nested keys, `{"root": {"sub": {"key": "value"}}}`
  * `{"root": {"sub": {"key": "?"}}}`
* `key=value` maps:
  * `key=?`
* Plain text `plain text`:
  * `p**** ****`

{% hint style="warning" %}
Truncated data: if data has been truncated, it will not be obfuscated and will show `scrubbed` as the data. You can change the truncation size limits if you need to.\
Want to change your data truncation size limits? [Contact us on slack](https://www.groundcover.com/join-slack).
{% endhint %}

### Using CLI on New or Existing Installation

After you prepared your desired `values.yaml`, apply them using:

```bash
groundcover deploy --values values.yaml
```

### Using Helm

```bash
helm upgrade \
    groundcover \
    groundcover/groundcover \
    -n groundcover \
    -i \
    -f values.yaml
```

### Sensitive headers obfuscation

groundcover will obfuscate sensitive HTTP and gRPC headers by default so that they are not shown in traces. This behavior is customizable using the same key value config as above.

The default values for the headers obfuscation are:

```yaml
agent:
  sensor:
    sensitiveHeadersObfuscationConfig:
      enabled: true
      mode: "ObfuscateSpecificValues"
      specificKeys:
        [
          "Authorization",
          "Proxy-Authorization",
          "X-Amz-Security-Token",
          "X-Amz-Credential",
          "X-Amz-Firehose-Access-Key",
          "Cookie",
          "Set-Cookie",
          "Api-Key",
          "X-Api-Key",
          "X-Csrf-Token",
          "X-XSRF-TOKEN",
          "X-Google-Api-Key",
          "X-Firebase-Auth"
        ]
```

{% hint style="warning" %}
According to the HTTP RFC, headers are case insensitive by nature. Because of that, the headers obfuscation will always be case insensitive and can't be configured otherwise.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/customization/customize-usage/sensitive-data-obfuscation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.