Quick Start

First Scan

Basic Scanning

Scan with remote rulesets (recommended — curated and maintained by SCANOSS):

crypto-finder scan /path/to/code

Scan with local rules only:

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

Generate a CycloneDX Cryptography Bill of Materials (CBOM):

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

Common Use Cases

CI/CD Integration:

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

Custom Rule Combination:

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

Force Fresh Ruleset Download:

# Bypass the cache and force a fresh download of remote rulesets
crypto-finder scan --no-cache /path/to/code

Post-Scan Format Conversion:

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

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

Re-annotation (rules changed, source didn’t): The call graph build (parsing + type inference) is the expensive part of a scan and is rules-independent. When only the detection ruleset changed, annotate re-runs detection only against a cached graph fragment instead of rebuilding it:

# One-time: full scan, cache the structural fragment
crypto-finder scan --export-graph-fragment fragment.json /path/to/code

# Every rules change afterwards: detection-only re-annotation
crypto-finder annotate --import-fragment fragment.json --source /path/to/code --output annotation.json

Use scan when the source code changed; use annotate when only the rules changed. On a large library this turns a multi-minute re-scan into a fraction of the time. annotate also accepts --scanner-jobs (and honors SCANOSS_SCANNER_JOBS) for its OpenGrep detection process.

Configuration

Crypto Finder can be configured via command-line flags, environment variables, or configuration files.

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

# Set a 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
export SCANOSS_SCANNER_JOBS=2   # optional: OpenGrep jobs for scan and annotate

Project-level configuration via scanoss.json:

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

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
--strict - Fail if the rules cache expired and the API is unreachable (no stale-cache fallback)
--max-stale-age <dur> - Maximum age for stale cache fallback (default 30d, max 90d)
--scanner <name> - Scanner to use: opengrep (default), semgrep
--scanner-jobs <n> - Parallel jobs for the primary scan’s OpenGrep process (default 0: OpenGrep’s own default, one per detected core; also via SCANOSS_SCANNER_JOBS, the flag wins). Lower it when several scans share a host — see Scanner Configuration
--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)
--include-tests - Include test sources in findings and dependency scans
--no-dedup - Disable per-line deduplication of findings
--no-default-exclusions - Disable built-in exclusions (vendor, node_modules, shaded/, generated protobuf stubs, …); combine with --exclude to re-add specific paths
--exclude <glob> - Gitignore-style pattern to skip (repeatable), added on top of the defaults
--detect-paths-from <file> - Scope detection to the files listed in <file> (one path per line, relative to the target; - reads stdin), without shrinking the call graph those files are traced against — see Scoping Detection to Changed Files
--scan-dependencies - Scan third-party dependencies for cryptographic usage (requires deps image or local toolchains)
--dep-ecosystem <eco> - Dependency ecosystem: auto (default), go, java, python, rust, node
--dep-workers <n> - Parallel dependency scan workers (default 0: half of CPU cores, max 8; Java max 2); concurrent dependency scans share the CPU cores
--include-dev-dependencies - Also scan npm development-only dependencies (packages marked dev in package-lock.json); by default dependency scans cover the production tree
--no-dependency-findings-api - Scan every dependency locally instead of taking the findings the SCANOSS API publishes for its package version (only applies when an API key is configured) — see Dependency Scanning
--findings-cache <backend> - Dependency findings cache backend: disk (default), none, postgres
--export-callgraph <file> - Write the finding-centric crypto call graph (reachability slices) to <file> — see Output Formats
--export-callgraph-max-chains <N> - Per-finding sampled route budget for --export-callgraph (default 8 since v0.28.0; pass 128 for a larger sample)
--export-callgraph-entry-points - Include the optional full crypto_entry_points reverse-reachability index in --export-callgraph (default false since v0.28.0)
--export-callgraph-interned-frames - Emit call graph schema 6.17, with frame identity in functions[] (default true since v0.28.0; set false for the inlined 6.14 schema)
--export-callgraph-format <fmt> - Call graph export format (currently only json)
--export-callgraph-project-reachability - Without --scan-dependencies (or when nothing was resolved), classify first-party reachability against the target’s own source packages instead of reporting not_applicable; leave this off when scanning a library on its own, where an uncalled function is public API rather than dead code — see Reachability Without Dependency Resolution
--export-graph-fragment <file> - Write a reusable structural graph fragment to <file>, for caching or annotate
--export-graph-fragment-format <fmt> - Graph fragment export format (currently only json)
--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)
--java-compiled-artifact <path> - Compiled Java artifact used for standalone call graph/type enrichment
--interfile - Enable cross-file analysis (Semgrep Pro only)
--error-format <fmt> - Terminal error rendering: text (default) or json
--progress - Write scan lifecycle JSONL to stderr; findings remain on stdout or --output
--verbose, -v - Enable verbose (info-level) logging
--quiet, -q - Error-level logging only
--help - Display help information

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

Checking Your Version

crypto-finder version

Advanced Topics

Scoping Detection to Changed Files

--exclude is one matcher shared by detection, call graph construction, and dependency root discovery, so excluding the files a change didn’t touch also prunes them from the call graph, and that can flip a changed file’s own findings from reachable to unreachable because their callers were excluded too. --detect-paths-from <file> scopes only the detection pass. The call graph, reachability, and dependency root discovery still read the whole target, so callers outside the list are still seen and reachability stays correct. <file> is a plain text file with one path per line, relative to the target; - reads the list from stdin:

git diff --name-only origin/main... > changed.txt
crypto-finder scan --detect-paths-from changed.txt --scan-dependencies --export-callgraph callgraph.json /path/to/repo

# or read the list from stdin
git diff --name-only origin/main... | crypto-finder scan --detect-paths-from - /path/to/repo

Named files still pass through --exclude, the default exclusions, and .gitignore, the same as a full scan, so the scope never reaches a file a full scan would skip. Limitations:

OpenGrep only. Semgrep doesn’t implement the scoping interface and returns invalid_arguments.
With --scan-dependencies, dependencies are still scanned in full; the path list scopes only the target’s own files.
A listed file that no longer exists (for example, one deleted in the diff) is skipped rather than erroring; a listed directory, or a path outside the target, is an error.
An empty or all-deleted list scans nothing. It never falls back to scanning the whole target.

Reachability Without Dependency Resolution

Without --scan-dependencies (or when it resolves no dependencies), crypto-finder has no “user package” universe to classify reachability against, so every finding, including your own first-party code, reports not_applicable instead of reachable or unreachable. This gets in the way of an incremental or CI re-scan that intentionally skips dependency resolution because no manifest or lockfile changed. --export-callgraph-project-reachability builds that universe from the target’s own source packages instead, so first-party findings get the same reachable/unreachable verdicts a full --scan-dependencies run would give them. It never classifies dependency-code findings, those still need --scan-dependencies, and every source file under the target is treated as first-party, so a vendored package not covered by the default exclusions is misclassified as project code rather than attributed to a dependency.

Leave this flag off when scanning a library on its own. A function with no caller in that case is public API, not dead code, and treating the library as a self-contained project would misclassify it as unreachable.

Features

Multi-Scanner Support — Supports OpenGrep (recommended) and Semgrep as configurable scan engines; Semgrep includes advanced taint analysis (inter-procedural data-flow tracking).
Dead Code Filtering (C/C++) — Automatically removes findings inside statically-dead preprocessor regions (e.g. #if 0, #ifdef, #ifndef) to eliminate false positives in C and C++ codebases. Applied automatically when C/C++ files are detected; no additional flags required.
Language Coverage — Call graph construction and --export-callgraph reachability cover C, C++, Go, Java, JavaScript/TypeScript, Python, and Rust. Recursive dependency scanning (--scan-dependencies) currently resolves third-party packages for Go, Java (Maven/Gradle), Python (pip), Rust (Cargo), and Node (npm) — see Dependency Scanning.
Remote Rulesets — Automatically fetches and caches SCANOSS-maintained rulesets from the SCANOSS API; the local cache is used as a fallback if the remote is unavailable.
Flexible Configuration — Combine remote rulesets with local custom rules; configure via CLI flags, environment variables, or a scanoss.json configuration file.
Multiple Output Formats — Supports JSON and CycloneDX 1.7 CBOM output formats.
CI/CD Integration — Official Docker images available for use with GitHub Actions, GitLab CI, Jenkins, and other CI/CD platforms.
TTL-Based Caching — Remote rulesets are cached with a configurable time-to-live (TTL); expired cache entries are used as a fallback when the remote is unavailable (disable with --strict).

Documentation

Links

First Scan

Basic Scanning

Common Use Cases

Configuration

Command Line Arguments

Checking Your Version

Advanced Topics

Scoping Detection to Changed Files

Reachability Without Dependency Resolution

Features

​First Scan

​Basic Scanning

​Common Use Cases

​Configuration

​Command Line Arguments

​Checking Your Version

​Advanced Topics

​Scoping Detection to Changed Files

​Reachability Without Dependency Resolution

​Features

First Scan

Basic Scanning

Common Use Cases

Configuration

Command Line Arguments

Checking Your Version

Advanced Topics

Scoping Detection to Changed Files

Reachability Without Dependency Resolution

Features