Hiding Sensitive Data

Using the debugger might expose sensitive data within the application such as e-mail addresses, account numbers, and so-on. This sensitive data can be blocked by the debugger agent with a simple configuration file.


The following example configuration hides data within a single class from the debugger:

- "com.sales.Ticket"

It is also possible to hide packages by specifying the package name:

- "com.sales"

In some cases, it can be useful create exceptions to blacklist rules. This can be done with a blacklist_exception:

- "com.sales"
- "com.sales.testing"

Finally, it's possible to specify an inverse pattern, where classes that do not match a pattern are blacklisted.

- "!com.sales"

Hidden data is reported by the debugger as "blocked by admin", as shown in the following screenshot:

Debugger reports hidden text as "blocked by admin"

Configuration File

The following configuration can be used as a starting point and provides inline documentation:

# Cloud Debugger Blacklist Configuration File
# == Format ==
#   This configuration file accepts the following keywords:
#    - blacklist
#    - blacklist_exception
#   The debugger uses the following rules to determine if a variable's data
#   should be hidden, using the variable's type as the match criteria.
#   | Matches `blacklist` | Matches `blacklist_exception` | Data is |
#   |---------------------|-------------------------------|---------|
#   | no                  | no                            | shown   |
#   | no                  | yes                           | shown   |
#   | yes                 | no                            | hidden  |
#   | yes                 | yes                           | shown   |
#   Patterns listed under "blacklist" and "blacklist_exception" have the
#   following format:
#   [!]<type>
#   - `type` is a type prefix (such as a class or package name). Any
#      nested types will also match the pattern. For example, if you
#      specify a package name, the package and all of it's subtypes will
#      match. Note that glob patterns such as `*` can be used anywhere in
#      the type name.
#   -  By prefixing a pattern with an exclamation point, `!`, the pattern
#      is considered an "inverse match" which evaluates to true for any
#      type that does not match the provided pattern.
#   -  The debugger makes no attempt to verify that specified patterns
#      will actually match anything. If you have a misspelling in your
#      pattern, then there will be no reported errors but the pattern will
#      not work as intended.
# == Verification ==
#   A verification tool is available and can be downloaded with the
#   following command:
#   wget https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/debugger_blacklist_checker.py
#   This tool can be used to check the configuration file for syntax errors.
#   It can also be used to experiment with configuration files locally
#   without having to deploy a real application.
#   A basic usage example:
#       debugger_blacklist_checker.py debugger-blacklist.yaml
#   You can also use the tool to check if symbols will be blacklisted
#     echo com.java.Integer | \
#       debugger_blacklist_checker.py debugger-blacklist.yaml --check

# Uncomment The line below to add blacklists
#  - "java.security"  # Example package

# Uncomment The line below to add blacklist exceptions
#  - "java.security.Timestamp"  # Example class

Where to Place the Configuration File

The configuration file must be named debugger-blacklist.yaml and can be placed anywhere in the class path. A reasonable place is at the root of the .jar file. The following sections discuss how to accomplish this.

Using the jar command

To insert or update a configuration file in a .jar file, the jar command can be used. To add the configuration file debugger-blacklist.yaml to the archive TicketTracker.jar, use the following command:

jar uvf TicketTracker.jar debugger-blacklist.yaml

Using Ant

To insert the configuration file into a JAR using the Ant build system, use Ant's built-in jar task. For example, the following distribute target uses the jar task to add the configuration file debugger-blacklist.yaml to the archive TicketTracker.jar.

<target name="distribute" depends="compile">
  <jar destfile="${distributionDir}/TicketTracker.jar" >
    <fileset dir="${outputDir}"/>
    <fileset dir="${sourceDir}"/>
    <fileset file="debugger-blacklist.yaml" />

Using Maven

To insert the configuration file into a package managed by the Maven build system, place the debugger-blacklist.yaml file inside the src/main/resources directory, which you may need to create. Build the project and confirm that debugger-blacklist.yaml was copied to target/classes.