purpleteam logger

Logging component of PurpleTeam

PurpleTeam logger wraps winston for PurpleTeam components, provides a custom signale transport, and is open to be extended with additional transports.

purpleteam-logger is used heavily throughout most of the PurpleTeam projects.

Contents

• Install
• Usage
  • Create a Reusable Logger
  • Use the Logger
  • Specify Transports
  • Use the Logger
  • Add more Loggers
• API
  • init(options)
  • get(['default'])
  • add(catagory, [options])
  • Custom Transport Details
  • Examples
  • Contribution
  • License

Install

npm install purpleteam-logger

Usage

Create a Reusable Logger

Where ever you need a logger:

import { init as initLogger } from 'purpleteam-logger';

const log = initLogger({ level: 'debug' });

 

This will return an existing logger (with a default Console transport) if one was already created. Otherwise a winston logger will be created. As part of creating a logger, the passed options object will be validated that the level is one of the syslog levels.

a combined format (format.combine) will be created. in which we:

• colorize the output
• Create a custom format (called tagger) by passing the bespoke (tagger) transform which consumes any tags from the log event and formats them into the printed message, along with the event message
• If NODE_ENV is production
  • Include a winston.format.timestamp
  • Bespoke format the messages with a function (prodFormatter) that utilises winston.format.printf to format the printed message as timestamp level message (message includes any tags from the tagger)
• If NODE_ENV is development
  • format.simple instead of including a timestamp

and finally a winston.transport.console transport is added to the transports array property of the options object used to create the logger. This could be made more extensible.

Use the Logger

log.info('Server registered.', {tags: ['startup']});
log.info('Server started.', {tags: ['startup']});
// ...
log.info('running testJob', {tags: ['app']});
// ...
log.notice(`Constructing the cucumber world for session with id "${id}".\n`, {tags: ['world']});
// ...
log.notice(`Located element using id="${attackField.name}", and sent keys.`, {tags: ['browser']});
// ...

In development:

In production:

The available log levels are listed here;

Specify Transport(s)

By default the winston.transports.Console will be used.

import { init as initLogger } from 'purpleteam-logger';

const log = initLogger({ level: 'debug', transports: ['Console'] });

You can specify the name of one or more transport constructors.

Using the SignaleTransport alone for example looks like the following:

import { init as initLogger } from 'purpleteam-logger';

const log = initLogger({ level: 'debug', transports: ['SignaleTransport'] });

Using the File alone for example looks like the following:

import { init as initLogger } from 'purpleteam-logger';

const log = initLogger({ level: 'debug', transports: ['File'], filename: '/path/to/your/logfile' });

Use the Logger

log.emerg('This is what an emergency looks like.', { tags: ['emerg-tag'] });
log.alert('This is what an alert looks like.', { tags: ['alert-tag'] });
log.crit('This is what a critical event looks like.', { tags: ['crit-tag'] });
log.error('This is what an error looks like.', { tags: ['error-tag'] });
log.warning('This is what a warning looks like.', { tags: ['warning-tag'] });
log.notice('This is what a notice looks like.', { tags: ['notice-tag'] }); 
log.info('This is what an info event looks like.', { tags: ['info-tag'] });
log.debug('This is what a debug event looks like.', { tags: ['debug-tag'] });

In development:

In production:

Add more Loggers

If you want to add extra loggers after the default logger has been initialised. See the Winston docs for more details.

import { init as initLogger } from 'purpleteam-logger';

const log = initLogger({ level: 'debug' });

log.add('nameForYourNewLogger', { transports: ['File'], filename: '/path/to/your/logfile' })

 

API

init(options)

Creates and returns a configured logger. If one already exists, it will be returned without creating another.

• options: Configuration object for the logger instance
  • level: Can be one of the syslog levels: 'emerg', 'alert', 'crit', 'error', 'warning', 'notice', 'info', 'debug'
  • transports: An array of strings of any of the names of transport constructors. You can specify multiple transports in the transports array. These can be any combination of the winston core transports, and/or the custom transports (Any transport inside the src/transports/ directory will be available for selection once added to the index.js), SignaleTransport for example

get(['default'])

Returns the already instantiated logger object, unless one hasn't been instantiated yet by init, in which case an informative Error will be thrown.
If an argument of 'default' or no argument is passed to get, the 'default' logger will be returned if it has been initialised.
If you supply an argument that is the name of a logger you have created previously, then that logger will be returned to you.

add(catagory, [options])

If no options are supplied to add, a new options object will be created using a transport of Console, and the same level that the default logger has.

Custom Transport Details

Currently signale is the only custom transport in the project, feel free to add additional transports.
The signale types can be seen at:

• docs
• source

Which utilise figures for icons.

Examples

There are many examples of how purpleteam-logger is being used in the purpleteam-labs projects in both development and production environments. In particular the following projects would be a good place to start:

• purpleteam (the CLI)
• purpleteam-orchestrator
• purpleteam-app-scanner
• purpleteam-tls-scanner

There are also videos of purpleteam-logger in action.

Contribution

Please open an issue to discus the proposed change before submitting a pull request.

License

Copyright Kim Carter and other contributors, Licensed under MIT.