> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> [Crypto Finder](https://github.com/scanoss/crypto-finder) is a CLI tool for detecting cryptographic algorithm usage in source code repositories. Crypto Finder scans codebases using multiple scanning engines and outputs results in standardised formats including JSON and CycloneDX.

## The Problem

**What cryptography is in your codebase?**

Algorithms, certificates, protocols, and keys — critical components that many teams struggle to inventory and assess with confidence.

Without clear visibility, organisations face serious challenges:

* **Compliance:** Standards such as **PCI-DSS** and frameworks published by **NIST** (e.g. SP 800-175B) require an accurate cryptographic inventory.
* **Security:** Outdated or weak cryptographic implementations introduce exploitable vulnerabilities.
* **Post-Quantum Readiness:** Emerging quantum computing capabilities will render many current encryption schemes obsolete.
* **Visibility:** Manual audits are slow, inconsistent, and do not scale across large or fast-changing codebases.

Crypto Finder addresses these challenges by automating cryptographic discovery, giving teams the visibility they need to secure and maintain their codebase.

## Key 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`)

## How It Works

1. **Scan**: Point `crypto-finder` at your source code repository
2. **Detect**: Automatically identifies programming languages and fetches the appropriate cryptographic detection rules
3. **Analyse**: OpenGrep or Semgrep scans the codebase for cryptographic patterns using rule-based detection
4. **Report**: Generates a CycloneDX CBOM or JSON output file

```mermaid theme={null}
graph LR
    SRC["Source Code<br>Repository"] --> CF

    subgraph CF["Crypto Finder"]
        LD["Language Detection"]
        SCN["Scanner Engine<br>(OpenGrep / Semgrep)"]
        RP["Result Processor"]

        LD --> SCN --> RP
    end

    CF --> OUT["Output"]
    OUT --> FINAL["JSON / CycloneDX CBOM"]

    %% --- Styles ---
    style SRC fill:#42A5F5,stroke:#1E88E5,stroke-width:2px,color:#fff
    style CF fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff
    style LD fill:#80CBC4,stroke:#00897B,stroke-width:1px,color:#212121
    style SCN fill:#FFCA28,stroke:#F57F17,stroke-width:1px,color:#212121
    style RP fill:#BA68C8,stroke:#6A1B9A,stroke-width:1px,color:#fff
    style OUT fill:#42A5F5,stroke:#1E88E5,stroke-width:2px,color:#fff
    style FINAL fill:#8E24AA,stroke:#6A1B9A,stroke-width:2px,color:#fff
```

## Dead Code Filtering (C/C++)

When scanning C or C++ codebases, Crypto Finder automatically detects and excludes cryptographic findings located inside statically-dead preprocessor regions, code that the compiler will never include in the final binary.

### Supported Preprocessor Patterns

Dead code regions are identified by evaluating common preprocessor directives:

| Pattern        | Example                      | Behaviour                                   |
| -------------- | ---------------------------- | ------------------------------------------- |
| `#if 0`        | `#if 0 ... #endif`           | Always-false, entire block is excluded      |
| `#ifdef`       | `#ifdef UNDEFINED_MACRO`     | Excluded when macro is not defined          |
| `#ifndef`      | `#ifndef DEFINED_MACRO`      | Excluded when macro is defined              |
| `#elif 0`      | `#elif 0`                    | Subsequent branch treated as dead           |
| `#else`        | Paired with a live `#if`     | Excluded when the preceding branch is live  |
| Nested regions | `#if 0 { #if 1 ... } #endif` | Nested conditions are evaluated recursively |

### Why This Matters

Without dead code filtering, findings inside `#if 0` guards or platform-specific blocks that are never compiled could generate false positives, flags for cryptographic algorithms that are never actually used at runtime.

Filtering is applied automatically when C or C++ files are detected in the target directory. No additional configuration is required.

## Use Cases

### Security Auditing

Identify all cryptographic implementations in a codebase to verify they meet security standards and compliance requirements.

### Cryptography Bill of Materials (CBOM)

Generate a comprehensive inventory of cryptographic assets for regulatory compliance (e.g. NIST SP 800-175B, FIPS 140) and security assessments.

### Vulnerability Management

Detect deprecated or weak cryptographic algorithms — such as MD5, SHA-1, and DES — that may introduce security risk.

### Supply Chain Security

Track cryptographic dependencies and implementations across the software supply chain.

### Compliance Reporting

Generate reports in standardised formats (CycloneDX CBOM) for consumption by compliance teams and auditors.

## Cryptography Service

The **Cryptography Service** provides access to remote cryptographic rulesets via the **SCANOSS API**.

### Automatic Rule Fetching

During each scan, Crypto Finder:

* Detects the programming languages present in the target project
* Retrieves the appropriate cryptographic detection rules from the **SCANOSS API**
* Caches these rules locally for up to **7 days** (Time-to-Live) to reduce network dependency and improve performance

### Offline Mode

When the SCANOSS API is unavailable or the environment is air-gapped, Crypto Finder automatically falls back to **offline mode**, using the most recently cached rules to continue scanning without interruption.

### Flow

```mermaid theme={null}
graph TD
    A["Crypto Finder<br>Scan Engine"] -->|Online| B["SCANOSS<br>Cryptography API"]
    B --> C["Local Cache<br>(7-day TTL)"]
    A -->|Offline / Air-Gapped| C

    style A fill:#42A5F5,stroke:#1E88E5,stroke-width:3px,color:#fff
    style B fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff
    style C fill:#8E24AA,stroke:#6A1B9A,stroke-width:2px,color:#fff
```