checkmate

README

CheckMate: Hard-Coded Secrets Detection

Overview

Exposed secrets in source code, logs, or configuration files can lead to security breaches. Attackers scan repositories for credentials that grant unauthorized access to critical systems. Even a single leaked API key or password can cause data breaches, service disruptions, and compliance violations. Detecting and removing these risks early is essential for security.

CheckMate is an advanced tool for detecting hard-coded secrets in source code, logs, and configuration files. It employs heuristics such as entropy analysis, structural context, and pattern recognition to identify sensitive information, including:

• Passwords
• API keys
• Encryption keys
• Other security tokens

Supported file types include configuration formats like YAML and XML, as well as source code in languages such as Java, C/C++, C#, Ruby, Scala, and more.

Installation

Pre-built Binaries

Download the latest pre-built binaries for your operating system from the releases page.

macOS Installation (via Homebrew)

brew tap adedayo/tap
brew install checkmate

Desktop Application

A graphical desktop version of CheckMate is available: CheckMate Desktop Application.

Usage

Command-Line Interface (CLI)

To scan files and directories for secrets, run:

checkmate search <paths to directories and files to scan>

CLI Help

View available options with:

checkmate search --help

Key Command-Line Flags

Flag	Description
--calculate-checksums	Compute checksums of detected secrets (default: true)
--exclude-tests	Skip test files during scanning
-e, --exclusion <file>	Use an exclusion YAML configuration file
--json	Generate output in JSON format (default: true)
--pdf	Generate a PDF report (requires asciidoctor-pdf)
--report-ignored	Include ignored files and values in reports
--sensitive-files-only	Only search for sensitive files (e.g., certificates, key stores)
-s, --source	Include source code evidence in diagnostic results (default: true)
--verbose	Enable verbose output (e.g., current file being scanned)

Running CheckMate with Docker

CheckMate can also be run as a Docker container:

Pull the Docker Image

docker pull ghcr.io/adedayo/checkmate

Scan a Local Directory

docker run --rm -v $(pwd):/data adedayo/checkmate search /data

Scan a Git Repository

docker run --rm adedayo/checkmate search https://github.com/example/repository.git

Generating Reports

CheckMate can produce a detailed PDF report. To enable this feature, install Asciidoctor PDF and ensure it's in your $PATH.

Run CheckMate with the --pdf flag:

checkmate search <path> --pdf

A sample report is available 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.