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.
Examples
The following example configuration hides data within a single class from the debugger:
blacklist:
- "com.sales.Ticket"
It is also possible to hide packages by specifying the package name:
blacklist:
- "com.sales"
In some cases, it can be useful create exceptions to blacklist rules.
This can be done with a blacklist_exception:
blacklist:
- "com.sales"
blacklist_exception:
- "com.sales.testing"
Finally, it's possible to specify an inverse pattern, where classes that do not match a pattern are blacklisted.
blacklist:
- "!com.sales"
Hidden data is reported by the debugger as "blocked by admin", as shown in the following screenshot:
Configuration File
The following configuration can be used as a starting point and provides inline documentation:
# Stackdriver 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
#blacklist:
# - "java.security" # Example package
# Uncomment The line below to add blacklist exceptions
#blacklist_exception:
# - "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" />
</jar>
</target>
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.
