crypto-finder

module

v0.4.2 Latest Latest Go to latest Published: May 12, 2026 License: GPL-2.0, GPL-2.0-only

README ¶

Crypto Finder

GitHub release (latest by date)

A powerful CLI tool for detecting cryptographic algorithm usage in source code repositories. Crypto Finder scans codebases using multiple scanning engines (OpenGrep, Semgrep) and outputs results in standardized formats including JSON and CycloneDX CBOM (Cryptography Bill of Materials).

TL;DR

# Configure your API key (one-time setup)
crypto-finder configure --api-key YOUR_API_KEY

# Scan a project using remote rulesets
crypto-finder scan /path/to/code

# Generate CycloneDX CBOM
crypto-finder scan --format cyclonedx --output cbom.json /path/to/code

Installation

Prerequisites

Before you begin, ensure you have the following installed:

Go - version 1.25 or higher (for building from source)

# macOS
brew install go

# Linux
# Download from https://go.dev/dl/

OpenGrep or Semgrep - for running scans (included in Docker images)

# OpenGrep (recommended)
# Download from https://github.com/opengrep/opengrep

# Semgrep
pip install semgrep

Setup

Option 1: Build from Source

git clone https://github.com/scanoss/crypto-finder.git
cd crypto-finder
make build
sudo make install

Option 2: Go Install

go install github.com/scanoss/crypto-finder/cmd/crypto-finder@latest

Option 3: Docker

# Full image with scanners included (recommended)
docker pull ghcr.io/scanoss/crypto-finder:latest

# Slim image (bring your own scanner)
docker pull ghcr.io/scanoss/crypto-finder:latest-slim

# Deps image (all language toolchains for dependency scanning)
docker pull ghcr.io/scanoss/crypto-finder:latest-deps

Usage

Basic Scanning

Scan with remote rulesets (recommended):

crypto-finder scan /path/to/code

Scan with local rules:

crypto-finder scan --no-remote-rules --rules-dir ./rules /path/to/code

Generate CycloneDX CBOM:

crypto-finder scan --format cyclonedx --output cbom.json /path/to/code

Common Use Cases

CI/CD Integration:

# Fail build if cryptographic assets are detected
crypto-finder scan --fail-on-findings /path/to/code

Custom Rule Combination:

# Combine remote rules with local custom rules
crypto-finder scan --rules-dir ./custom-rules /path/to/code

Force Fresh Rules:

# Bypass cache and force fresh download
crypto-finder scan --no-cache /path/to/code

Format Conversion:

# Convert existing results to CycloneDX
crypto-finder convert results.json --output cbom.json

# Or pipe from scan
crypto-finder scan /path/to/code | crypto-finder convert --output cbom.json

Configuration

The application can be configured via command-line flags, environment variables, or configuration files.

# Set API key
crypto-finder configure --api-key YOUR_API_KEY

# Set custom API URL
crypto-finder configure --api-url https://custom.scanoss.com

Environment Variables:

export SCANOSS_API_KEY=your-key
export SCANOSS_API_URL=https://custom.scanoss.com

Project-level configuration via scanoss.json:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["node_modules/", "target/", "venv/"]
      }
    }
  }
}

For detailed configuration options, see Configuration Documentation.

Command Line Arguments

crypto-finder scan [flags] <target>

Common options:

--rules <file> - Custom rule file (repeatable)
--rules-dir <dir> - Rule directory (repeatable)
--no-remote-rules - Disable remote ruleset fetching
--no-cache - Force fresh download, bypass cache
--scanner <name> - Scanner to use: opengrep (default), semgrep
--format <format> - Output format: json (default), cyclonedx
--output <file> - Output file path (default: stdout)
--languages <langs> - Override language detection (comma-separated)
--fail-on-findings - Exit with error if findings detected
--timeout <duration> - Scan timeout (default: 10m)
--scan-dependencies - Scan third-party dependencies for cryptographic usage (requires deps image or local toolchains)
--export-callgraph - Export call graph to JSON for debugging
--java-jdk-major <major> - Java JDK major for Java dependency resolution/type enrichment: auto, 8, 11, 17, 21
--java-jdk-home <major=path> - Java JDK home mapping for explicit Java runtime selection (repeatable)
--interfile - Enable cross-file analysis (Semgrep Pro only)
--verbose, -v - Enable verbose logging
--help - Display help information

For a complete list of commands and options, run crypto-finder --help.

Advanced Topics

Features

Multi-Scanner Support - OpenGrep (default) and Semgrep with advanced taint analysis
Remote Rulesets - Automatically fetch curated rules from SCANOSS API with local caching
Flexible Configuration - Combine remote and local rules, configure via CLI, env vars, or config files
Multiple Output Formats - Interim JSON and CycloneDX 1.6 CBOM formats
CI/CD Ready - Docker images for GitHub Actions, GitLab CI, Jenkins, and more
Dependency Scanning - Detect cryptographic usage in third-party dependencies with call chain tracing (Go, Java via Maven/Gradle, Python, Rust)
Smart Caching - TTL-based cache with automatic stale cache fallback (opt-out with --strict)

Documentation

Remote Rulesets - API configuration, caching strategies, and troubleshooting
Output Formats - Interim JSON and CycloneDX CBOM format specifications
Docker Usage - Container usage and CI/CD integration examples
Dependency Scanning - Scanning third-party dependencies for cryptographic usage
Configuration - Detailed configuration guide and skip patterns

Contributing

We welcome contributions! For more details, see CONTRIBUTING.md and our Code of Conduct.

Quick Start

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make test)
Install pinned linter (make lint-install)
Run linter (make lint)
Commit your changes (git commit -m 'feat: add an amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Changelog

See CHANGELOG.md for a detailed history of changes.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for the full license text.

SPDX-License-Identifier: GPL-2.0-only

Links

Support

For questions, issues, or feature requests, please use the GitHub Issues page.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
crypto-finder command Package main is the entry point for the crypto-finder CLI tool.	Package main is the entry point for the crypto-finder CLI tool.
internal
api Package apiclient provides an HTTP client for the SCANOSS REST API.	Package apiclient provides an HTTP client for the SCANOSS REST API.
cache Package cache manages the local cache of downloaded rulesets.	Package cache manages the local cache of downloaded rulesets.
callgraph Package callgraph provides function-level call graph construction and backward tracing for linking cryptographic findings in dependencies back to user code entry points.	Package callgraph provides function-level call graph construction and backward tracing for linking cryptographic findings in dependencies back to user code entry points.
callgraph/contracts Package contracts provides the JCA/JCE knowledge base (KB) loader and types for the callgraph inference engine.	Package contracts provides the JCA/JCE knowledge base (KB) loader and types for the callgraph inference engine.
cli Package cli provides the command-line interface implementation for crypto-finder.	Package cli provides the command-line interface implementation for crypto-finder.
config Package config provides configuration management for the application.	Package config provides configuration management for the application.
converter Package converter transforms crypto-finder interim format to CycloneDX CBOM format.	Package converter transforms crypto-finder interim format to CycloneDX CBOM format.
deadcode Package deadcode detects and filters cryptographic findings that fall inside C/C++ preprocessor dead code blocks (e.g., #if 0 ...	Package deadcode detects and filters cryptographic findings that fall inside C/C++ preprocessor dead code blocks (e.g., #if 0 ...
deduplicator Package deduplicator provides functionality to deduplicate cryptographic assets based on their identity in the source code.	Package deduplicator provides functionality to deduplicate cryptographic assets based on their identity in the source code.
dependency Package dependency provides interfaces and implementations for resolving project dependencies to their source code locations on disk.	Package dependency provides interfaces and implementations for resolving project dependencies to their source code locations on disk.
engine Package engine coordinates the scanning workflow by managing language detection, rule loading, scanner execution, and result processing.	Package engine coordinates the scanning workflow by managing language detection, rule loading, scanner execution, and result processing.
enricher Package enricher provides functionality to enrich cryptographic findings with additional metadata such as OIDs (Object Identifiers).	Package enricher provides functionality to enrich cryptographic findings with additional metadata such as OIDs (Object Identifiers).
entities Package entities defines the domain data structures for SCANOSS crypto-finder.	Package entities defines the domain data structures for SCANOSS crypto-finder.
failure Package failure defines structured machine-readable terminal errors.	Package failure defines structured machine-readable terminal errors.
javaruntime Package javaruntime manages Java runtime selection for Java dependency resolution and platform signature indexing.	Package javaruntime manages Java runtime selection for Java dependency resolution and platform signature indexing.
language Package language provides automatic programming language detection for source code.	Package language provides automatic programming language detection for source code.
output Package output handles formatting and writing scan results to various output formats.	Package output handles formatting and writing scan results to various output formats.
rules Package rules manages cryptographic detection rules, including loading, validation, and filtering of both local and remote rule sets.	Package rules manages cryptographic detection rules, including loading, validation, and filtering of both local and remote rule sets.
scan Package scan contains reusable scan utilities shared by CLI commands.	Package scan contains reusable scan utilities shared by CLI commands.
scanner Package scanner provides the core abstraction for cryptographic scanner implementations.	Package scanner provides the core abstraction for cryptographic scanner implementations.
scanner/opengrep Package opengrep provides the OpenGrep scanner adapter implementation.	Package opengrep provides the OpenGrep scanner adapter implementation.
scanner/semgrep Package semgrep provides the Semgrep scanner adapter implementation.	Package semgrep provides the Semgrep scanner adapter implementation.
skip Package skip provides utilities for determining which files and directories should be excluded from scanning.	Package skip provides utilities for determining which files and directories should be excluded from scanning.
utils Package utils provides general utility functions used across the application.	Package utils provides general utility functions used across the application.
version Package version provides version information for the crypto-finder tool.	Package version provides version information for the crypto-finder tool.
pkg
stitch Package stitch produces the merged findings + callgraph that `crypto-finder scan --scan-dependencies --export-callgraph` would emit, from inputs that have already been computed per-component.	Package stitch produces the merged findings + callgraph that `crypto-finder scan --scan-dependencies --export-callgraph` would emit, from inputs that have already been computed per-component.