Using the debugger might expose sensitive data within the application such as e-mail addresses, account numbers, and so-on. You can configure blocklists and blocklist exceptions to block the debugger agent from accessing this sensitive data.
Hidden data is reported by the debugger as "blocked by admin", as shown in the following screenshot:
Recommendations
As you configure or update your blocklist files, note the following recommendations:
Use the Java agent version 2.27 or newer. For installation information, see Setting up Cloud Debugger for Java.
Note that the configuration file naming and keywords have been updated to
blocklist. Update your files accordingly.
Configure your file
The following configuration can be used as a starting point and provides inline documentation:
# Cloud Debugger Blocklist Configuration File
#
# == Format ==
#
# This configuration file accepts the following keywords:
#
# - blocklist
# - blocklist_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 `blocklist` | Matches `blocklist_exception` | Data is |
# |---------------------|-------------------------------|---------|
# | no | no | shown |
# | no | yes | shown |
# | yes | no | hidden |
# | yes | yes | shown |
#
# Patterns listed under "blocklist" and "blocklist_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_blocklist_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_blocklist_checker.py debugger-blocklist.yaml
#
# You can also use the tool to check if symbols will be blocklisted
#
# echo com.java.Integer | \
# debugger_blocklist_checker.py debugger-blocklist.yaml --check
# Uncomment The line below to add blocklists
#blocklist:
# - "java.security" # Example package
# Uncomment The line below to add blocklist exceptions
#blocklist_exception:
# - "java.security.Timestamp" # Example class
Examples
The following example configuration hides data within a single class from the debugger:
blocklist:
- "com.sales.Ticket"
It is also possible to hide packages by specifying the package name:
blocklist:
- "com.sales"
In some cases, it can be useful create exceptions to blocklist rules.
This can be done with a blocklist_exception:
blocklist:
- "com.sales"
blocklist_exception:
- "com.sales.testing"
Finally, it's possible to specify an inverse pattern, where classes that do not match a pattern are blocklisted.
blocklist:
- "!com.sales"
Configuration file location
The configuration file must be named debugger-blocklist.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.
Use 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-blocklist.yaml to the
archive TicketTracker.jar, use the following command:
jar uvf TicketTracker.jar debugger-blocklist.yaml
Use 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-blocklist.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-blocklist.yaml" />
</jar>
</target>
Use Maven
To insert the configuration file into a package managed by the Maven build
system, place the debugger-blocklist.yaml file inside the
src/main/resources directory, which you may need to create. Build the project
and confirm that debugger-blocklist.yaml was copied to target/classes.