Class PropertiesMasker


  • public class PropertiesMasker
    extends java.lang.Object
    Rewrites a Properties so that it can be written to a log or a diagnostic report without disclosing the credentials configuration routinely carries. The policy it applies -- which names are sensitive, and how a URL-borne credential is concealed -- lives in MaskUtils, which is usable on its own where the thing to be masked is a single value rather than a whole Properties.

    Why this exists

    A dump of resolved configuration is the most useful diagnostic this library can offer and the most dangerous thing it can print. Asked why a setting is not taking effect, the honest answer is usually "here is every value in force and where each came from" -- and the same dump carries whatever was passed as -Dmyapp.db.password=..., every credential in a properties file, and the account and password embedded in a JDBC URL. Logs are shipped to aggregators, pasted into issue reports and mailed to vendors, so a dump that is safe only because nobody has raised the log level is not safe.

    c3p0 has long masked this where it knew exactly what it was holding: AuthMaskingProperties conceals two keys, user and password, because it is looking at a JDBC authentication map and nothing else. That approach does not survive generalization. A dump of System properties holds keys this library has never heard of, named by applications and libraries it will never see, so there is no list to consult. What is left is heuristics over names, plus inspection of values whose shape is known.

    That the tests are heuristics, and deliberately loose ones, is argued in MaskUtils -- as is what they retain on purpose, which is as much a part of the contract as what they mask.

    Two mechanisms, because neither subsumes the other

    • Key names. A key whose name contains one of MaskUtils.DEFAULT_MASKABLE_LOWERCASE_SUBSTRINGS has its whole value replaced. Matching ignores case and ignores separators, so one entry covers apiKey, api.key, api-key and api_key -- necessary rather than tidy, since properties conventionally use dots and a naive apikey would have matched only the camel-cased spelling.
    • Values. A PropertiesMasker.Transformer may rewrite a value the key name cannot judge. DANGEROUS_URL_VALUE_TRANSFORMER is the case that motivated the interface: a JDBC URL carries an account and password inside a value filed under a key called something like jdbcUrl, which is not sensitive by any name test. No key-name heuristic can reach it, and no value heuristic can replace key-name masking.

    Transformers get first refusal. They are consulted in turn, and the first to claim a value decides it outright -- key-name masking is then skipped for that key entirely. The ordering is deliberate, and it hands a transformer real discretion: one may claim a value whose key is sensitive by name, rescuing it from wholesale replacement in order to disclose the part that is safe. Showing the scheme, host and database of a connection URL while concealing only the credential is more useful than ****, and a transformer is entitled to make that call.

    The flip side is that a transformer can reveal what key-name masking would have hidden, so the judgement rests with whoever writes one. DANGEROUS_URL_VALUE_TRANSFORMER declines to exercise the liberty: asked about a value whose key is already sensitive, it returns false and lets whole-value masking proceed, on the grounds that a key named foo.password tells you nothing about what else its value might carry. That is its own policy, not a rule of this class.

    What it does not do

    This reduces exposure. It does not eliminate it, and should not be described as though it did.

    • Masking is not redaction of context. The output still shows which keys are set, and for a URL still shows the scheme, host, port and path. That is the point -- those answer the questions a dump is asked -- but it is disclosure, and a host name can itself be sensitive.
    • The name heuristics are a denylist, and a value can hide a secret where no test reaches. Both limits belong to the policy rather than to this class; they are set out in MaskUtils.

    The stronger control is therefore restrictToPrefix, which omits every key outside the prefix from the output rather than merely declining to mask within it. A dump restricted to one library's own keys cannot leak another application's properties at all, whatever they are named, and the heuristics above then serve as defence in depth over a surface small enough to reason about. Prefer it where the audience for the dump is known.

    Mechanics

    An instance is immutable once constructed: the transformer set is copied, and the prefix is final. The substring sets it consults are published on MaskUtils and are unmodifiable there, because a caller able to empty them could disable masking for the whole process. shouldMaskValue(java.lang.String) is public and overridable, and a PropertiesMasker.Transformer is handed the masker that is calling it, so a subclass that redefines what counts as sensitive redefines it for the transformers too -- though only for key names: a transformer consulting the URL parameter sets directly, as DANGEROUS_URL_VALUE_TRANSFORMER does through MaskUtils, is not reached by such an override.

    • Field Detail

      • DANGEROUS_URL_VALUE_TRANSFORMER

        public static final PropertiesMasker.Transformer DANGEROUS_URL_VALUE_TRANSFORMER
        Brings MaskUtils.maskUrlCredentials(java.lang.String) into a Properties dump, so that a connection URL filed under an innocuous key is not disclosed whole. What it conceals and what it retains are described there; what belongs here is when it declines.

        It claims a value only when masking actually changed it, so a URL carrying no credentials is left to the ordinary path rather than passing silently through a transformer. And it declines any key that is sensitive by name, forgoing the discretion described above: a key named foo.password says nothing about what else its value might carry, so partially revealing it is a worse answer than masking it entirely. That is this transformer's policy, not a rule of the class.

    • Constructor Detail

      • PropertiesMasker

        public PropertiesMasker​(java.util.Set<PropertiesMasker.Transformer> transformers,
                                java.lang.String restrictToPrefix)
      • PropertiesMasker

        public PropertiesMasker()
    • Method Detail

      • shouldMaskValue

        public boolean shouldMaskValue​(java.lang.String key)
      • masked

        public java.util.Properties masked​(java.util.Properties raw)