canary - dies when blacklisted content appears


canary [scan [<path>]] [-b|--blacklist=<comma,separated,regexes>] [-x|--exclude=<comma,separated,globs>] [-z|--exclude_content=<comma,separated,globs>] [-L|--line] [-l|--short_line]


canary dies when strings are detected that match regexes provided either via the --blacklist option or in a Canaryfile (placed in the directory where canary is executed).

canary will exit 100 if it detects any matches, otherwise it will exit 0.


  • -b, --blacklist=<comma,separated,regexes>: Any matches to provided regexes will cause canary to exit 100. This option overrides the Canaryfile. Regexes are assumed to be case indifferent.

  • -x, --exclude=<comma,separated,globs>: Files matching the provided globs will not be evaluated against the blacklist. Note that 'Canaryfile' is automatically added to this list.

  • -z, --exclude_content=<comma,separated,globs>: Files matching the provided globs will not have their content matched against the blacklist. Note that filenames will still be checked for files matching these globs.

  • -L, --line: Print the line (or filename) that matches the provided blacklist under the output asserting the match.

  • -l, --short_line: Print the line (or filename) like --line, but with the line snipped to 30 characters on either side of the first match in the line.


gem install build_canary

or in a Gemfile:

gem 'build_canary'


  • Scan a directory structure for regexes provided in a Canaryfile: canary

  • Scan a directory structure other than the current directory, but with the Canaryfile in the current directory: canary scan /path/to/directory

  • Declare the blacklist via option instead of using a Canaryfile: canary --blacklist='regexA,regexB,regexC'


The Canaryfile is the default way to configure which regexes are included on the blacklist. This file is a newline separated list of regexes. Regexes are automatically set to match case indifferent on Canaryfile evaluation.