Pino + redact-pii

A collection of redaction solutions focused on Pino and redact-pii.

Usage

npm add @agiledigital/pino-redact-pii

This package contains an opinionated configuration of redact-pii, including regexes from https://github.com/nickdeis/eslint-plugin-no-secrets. To use it:

import { SyncRedactor } from "redact-pii";
import { defaultSyncRedactorOpts } from "@agiledigital/pino-redact-pii";

const redactor = new SyncRedactor(defaultSyncRedactorOpts);
const textToRedact = "";
const result = redactor.redact(textToRedact);

On top of that, this package contains a higher-level redactor that can be applied recursively to nested object/array structures. This redactor can also filter unsafe object properties entirely (e.g. x-api-key). To use it:

import { applyRedactor, defaultRedactor } from "@agiledigital/pino-redact-pii";

const redactor = defaultRedactor(<optional config>);
const objectToRedact = {...};
const result = applyRedactor(textToRedact, redactor);

It also contain a wrapper around redact-pii that makes it convenient to plug the above redactor into Pino.

To use it:

import { pino } from "pino";
import { pinoPiiRedactor } from "@agiledigital/pino-redact-pii";

// This uses the default redactor. You can specify your own as an argument to `pinoPiiRedactor`.
const redactor = pinoPiiRedactor();

const logger = pino({
  formatters: {
    log: redactor,
  },
});

This package also contains a safeStringify function that provides a few benefits over JSON.stringify. You can use it without Pino.

1. It supports circular structures (whereas JSON.stringify would throw). It replaces them with "[circular]", similar to Node's util.inspect (but with no Node dependency).
2. It doesn't throw - it returns a success/failure discriminated union.
3. It returns a failure if the result of stringification is not a string (e.g. if it is undefined)
4. It will return a failure if you try to stringify an object that contains a BigInt (as per JSON.stringify). The workarounds are the same as for JSON.stringify. See https://github.com/GoogleChromeLabs/jsbi/issues/30
5. It permits stringification only of record values that are less likely to contain "hidden" sensitive data buried deeply in e.g. nested object structures, either when initially logged or as the type being logged grows as a codebase evolves.

import { defaultRedactor, safeStringify } from "@agiledigital/pino-redact-pii";

const obj = { text: "I might contain PII" };

// No redaction
const result = safeStringify(obj);
if (result.success) {
  const str = result.value;
}

// With redaction
const reactor = defaultRedactor();
const result2 = safeStringify(obj, reactor);

The underlying redactor from the redact-pii package can take a few seconds to start up. This happens when the first redaction is performed.

You can preemptively initialise the redactor and get this startup out of the way by redacting a dummy string and throwing away the result.

// Using the underlying SyncRedactor directly.
import { SyncRedactor } from "redact-pii";
new SyncRedactor(defaultSyncRedactorOpts).redact("");

// Or using our own default redactor (which wraps SyncRedactor).
import { defaultRedactor } from "@agiledigital/pino-redact-pii";
defaultRedactor().redact("");

Finally, this package contains a SensitiveString class that can be used when your app must handle a sensitive value (e.g. an API key) that shouldn't ever be accidentally included in log output, serialised to string or included in the result of JSON.stringify(...). To use it:

const ss = new SensitiveString("a secret value");
// '{"a":"[redacted]"}'
JSON.stringify({ a: ss });
// "[redacted]"
ss.toString();

// Explicitly retrieve the underlying secret
makeApiCall(ss.unsafeSensitiveString);

Releases

Releases are automated using semantic-release. To make a release, merge a PR with commits that follow the configured Commit message format.

Contributor getting started

1. Make sure you have NVM installed.
2. Create a new repo using this template (big green "use this template" button).
3. Clone that repo.
4. Then run the following:

# make sure the right version of node is being used
# tip: it might be worth automating this (https://github.com/nvm-sh/nvm#bash)
nvm use
# install dependencies
npm install
# compile
npm run build
# run the compiled code
node dist/index.js

IDE Notes

If you are using VSCode, it should automatically recommend you some important plugins for this package (e.g. eslint) If not, check the .vscode/extensions.json because they will greatly improve your workflow.