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 --source <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:
  -e, --exclusion string   Use provided exclusion yaml configuration
  -h, --help               help for secretSearch
      --json               Generate JSON output
      --sensitive-files    list all registered sensitive files and their description
  -s, --source             Provide source code evidence in the diagnostic results

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

Running CheckMate as an API Service

To run CheckMate as an API service, say on port 8080, simply run as follows

checkmate api --port=8080

This may be tested as follows

curl -X POST -H "Content-Type: application/json" localhost:8080/api/findsecrets -d @<(cat <<EOF
{
 "source": "String pwd = \"N!,.aQBd/538:uy7Tx#(jUe?t6ret!\";\n
\n
String passphrase = \"This is a secret passphrase. No one will find out\";",
"source_type": ".java"
}
EOF
)

This returns a result (formatted for presentation) as follows:

[
  {
    "Justification": {
      "Headline": {
        "Description": "Hard-coded secret assignment",
        "Confidence": "High"
      },
      "Reasons": [
        {
          "Description": "Variable name suggests it is a secret",
          "Confidence": "High"
        },
        {
          "Description": "Value has a high entropy, may be a secret",
          "Confidence": "Medium"
        }
      ]
    },
    "Range": {
      "Start": {
        "Line": 0,
        "Character": 7
      },
      "End": {
        "Line": 0,
        "Character": 45
      }
    },
    "Source": "pwd = \"N!,.aQBd/538:uy7Tx#(jUe?t6ret!\"",
    "ProviderID": "SecretAssignment"
  },
  {
    "Justification": {
      "Headline": {
        "Description": "Hard-coded secret assignment",
        "Confidence": "High"
      },
      "Reasons": [
        {
          "Description": "Variable name suggests it is a secret",
          "Confidence": "High"
        },
        {
          "Description": "Hard-coded secret",
          "Confidence": "High"
        }
      ]
    },
    "Range": {
      "Start": {
        "Line": 1,
        "Character": 8
      },
      "End": {
        "Line": 1,
        "Character": 72
      }
    },
    "Source": "passphrase = \"This is a secret passphrase. No one will find out\"",
    "ProviderID": "SecretAssignment"
  }
]

The /api/findsecrets endpoint accepts a POST request with a JSON payload of the form

{
  "source": "<string data to scan>",
  "source_type": ".yaml", //a hint to help with parsing the text in source
  "base64": true //an optional flag to indicate whether source is base64-encoded
}

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.