Quick Start

​

First Scan

​

Basic Scanning

crypto-finder scan /path/to/code

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

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

​

Common Use Cases

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

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

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

# 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

# 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

​

Configuration

# 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

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

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

​

Command Line Arguments

crypto-finder scan [flags] <target>

• --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
• --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
• --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
• --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 emitted route budget for --export-callgraph (default 128; 0 keeps the default)
• --export-callgraph-entry-points - Include the full crypto_entry_points reverse-reachability index in --export-callgraph (default true; disable to shrink the export when you don’t consume that index)
• --export-callgraph-format <fmt> - Call graph export format (currently only json)
• --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 — see Error Codes
• --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

​

Checking Your Version

crypto-finder version

​

Advanced Topics

​

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) is narrower and currently resolves third-party packages for Go, Java (Maven/Gradle), Python (pip), and Rust (Cargo) only — 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.6 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).