checkmate

README

CheckMate Code Security Analysis

CheckMate is designed to be a pluggable code security analysis tool with features to be added over time. Currently it supports

1. Detecting hard-coded secrets in code, configuration, logs and other textual files

Installation

Pre-built binaries may be found for your operating system here: https://github.com/adedayo/checkmate/releases

For macOS X, you could install via brew as follows:

brew tap adedayo/tap
brew install checkmate

Finding Hard-coded Secrets

Secrets such as passwords, encryption keys and other security tokens should never be embedded in the clear in code, logs or configuration files. The secrets-finding feature of CheckMate packs in a bunch of clever heuristics for determining whether a piece of string in a file is a secret. The heuristics include entropy of the string, the structural context such as variable names and properties the string is assigned to in different file types such as YAML, XML and other configuration file formats as well as source code such as Java, C/C++, C#, Ruby, Scala etc.

CheckMate could be used/embedded in the following ways at the moment:

• As a command-line tool providing file paths and directories to scan for secrets. This is great for searching local file system for secrets
• As a standalone API service that could receive the textual content of a piece of data to check for secrets returning a JSON response containing all results that look suspiciously like secrets, along with justification of why it may be a secret and a confidence level of that determination
• As a Language Server Protocol (LSP) back-end, using the LSP protocol to drive the analysis in LSP compatible text editors such as Visual Studio Code or Atom.

Running CheckMate as a command-line tool

checkmate secretSearch <paths to directories and files to scan>

The command line options may be obtained from the "help menu". For example:

checkmate secretSearch --help
Search for secrets in a textual data source

Usage:
  checkmate secretSearch [flags]

Flags:
      --calculate-checksums    Calculate checksums of secrets (default true)
      --exclude-tests          Skip test files during scan
  -e, --exclusion string       Use provided exclusion yaml configuration
  -h, --help                   help for secretSearch
      --json                   Generate JSON output
      --report-ignored         Include ignored files and values in the reports
      --running-commentary     Generate a running commentary of results. Useful for analysis of large input data
      --sample-exclusion       Generates a sample exclusion YAML file content with descriptions
      --sensitive-files        List all registered sensitive files and their description
      --sensitive-files-only   Only search for sensitive files (e.g. certificates, key stores etc.)
  -s, --source                 Provide source code evidence in the diagnostic results (default true)
      --verbose                Generate verbose output such as current file being scanned as well as report about ignored files

Global Flags:
      --config string   config file (default is $HOME/.checkmate.yaml)

The secretSearch command will generate a nice-looking PDF report by default, using asciidoctor-pdf, so it needs to be installed and should be on your system $PATH. Details for installing the free asciidoctor-pdf tool is here: Asciidoctor PDF documentation. If CheckMate could not find asciidoctor-pdf, it will generate a JSON output of your scan result instead, just as if you ran secretSearch with a --json command-line option.

A sample PDF report may be found here: bad-code-audit.pdf

Documentation

Overview

Copyright © 2019 Adedayo Adetoye (aka Dayo) All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.