Configuration - SCANOSS documentation

Configuration Priority

Settings are applied in the following priority order (highest to lowest):

Command-line flags (e.g., --api-key, --scanner)
Environment variables (e.g., SCANOSS_API_KEY)
Config file (~/.scanoss/crypto-finder/config.json)
Project settings (scanoss.json in target directory)
Default values

Application Configuration

Config File Location

~/.scanoss/crypto-finder/config.json

Setting Up Configuration

Use the configure command to set persistent application settings:

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

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

# Configure both
crypto-finder configure --api-key YOUR_KEY --api-url https://custom.scanoss.com

Config File Format

{
  "api_key": "your-scanoss-api-key",
  "api_url": "https://api.scanoss.com",
  "java_jdk_major": "auto",
  "java_jdk_homes": {
    "8": "/opt/jdks/jdk8",
    "11": "/opt/jdks/jdk11",
    "17": "/opt/jdks/jdk17",
    "21": "/opt/jdks/jdk21"
  }
}

Environment Variables

Variable	Description	Example
`SCANOSS_API_KEY`	SCANOSS API key for remote rulesets	`export SCANOSS_API_KEY=abc123`
`SCANOSS_API_URL`	Custom API base URL	`export SCANOSS_API_URL=https://custom.com`
`SCANOSS_JAVA_JDK_MAJOR`	Java JDK major for Java dependency resolution and type enrichment (`auto`, `8`, `11`, `17`, `21`)	`export SCANOSS_JAVA_JDK_MAJOR=21`
`SCANOSS_JAVA_JDK_HOMES`	Comma-separated Java home mappings used for explicit JDK selection	`export SCANOSS_JAVA_JDK_HOMES=17=/opt/jdks/jdk17,21=/opt/jdks/jdk21`
`SCANOSS_FINDINGS_CACHE_BACKEND`	FindingsCache backend (`disk` or `postgres`); default `disk`	`export SCANOSS_FINDINGS_CACHE_BACKEND=postgres`
`SCANOSS_FINDINGS_CACHE_DSN`	Postgres connection string used when backend is `postgres` (required)	`export SCANOSS_FINDINGS_CACHE_DSN=postgres://user:pass@host:5432/db?sslmode=require`
`SCANOSS_FINDINGS_CACHE_TABLE`	Optional table name override; default `findings_cache`	`export SCANOSS_FINDINGS_CACHE_TABLE=cf_findings_cache`

Java Runtime Selection

For Java dependency scans and call graph export, Crypto Finder can select a specific JDK major per scan:

CLI: --java-jdk-major and repeatable --java-jdk-home <major>=<path>
Environment/config: SCANOSS_JAVA_JDK_MAJOR, SCANOSS_JAVA_JDK_HOMES, or the matching config file keys
Supported majors: 8, 11, 17, 21
Standalone CLI default: auto (use ambient JAVA_HOME when available)

Example:

crypto-finder scan \
  --scan-dependencies \
  --java-jdk-major 21 \
  --java-jdk-home 17=/opt/jdks/jdk17 \
  --java-jdk-home 21=/opt/jdks/jdk21 \
  /path/to/java-project

FindingsCache Backend

Crypto Finder caches per-dependency scan results in a FindingsCache so warm scans skip the OpenGrep work for already-analysed dependencies. Two backends are supported:

Backend	Storage	When to use
`disk` (default)	`~/.scanoss/crypto-finder/cache/findings/`	Local development, single-machine repeated scans
`postgres`	a Postgres database (`findings_cache` table)	Multi-worker fleet deployments where the cache must be shared across machines

Selecting the backend:

CLI: --findings-cache=disk or --findings-cache=postgres
Environment: SCANOSS_FINDINGS_CACHE_BACKEND=postgres
Config file: findings_cache_backend: postgres

When postgres is selected, the connection string MUST be provided via SCANOSS_FINDINGS_CACHE_DSN. The scan exits with a clear error if it is missing — there is no silent fallback to disk, because a misconfigured fleet would otherwise lose cache sharing without surfacing the bug. The table is bootstrapped on first use (idempotent CREATE TABLE IF NOT EXISTS); no separate migration step is required. The default table name is findings_cache; override with SCANOSS_FINDINGS_CACHE_TABLE if you run multiple deployments in the same database. Example:

export SCANOSS_FINDINGS_CACHE_DSN="postgres://cf:cf@db.internal:5432/scanoss?sslmode=require"

crypto-finder scan \
  --scan-dependencies \
  --findings-cache=postgres \
  --export-callgraph callgraph.json \
  /path/to/project

Behaviour notes:

The cache key includes the rules hash, so changing rules invalidates entries automatically — no manual eviction needed.
Failures of the disk backend are non-fatal (a warning is logged and the scan continues without caching). Failures of the postgres backend (missing DSN, unreachable database, schema bootstrap error) are fatal.
The Postgres pool is opened per crypto-finder scan invocation and closed when the scan finishes. For long-lived workers, reuse a single binary process where possible to amortise pool setup.

Project Configuration (scanoss.json)

The scanoss.json file in your project directory configures scan behaviour and skip patterns.

File Location

Place scanoss.json in the root of the directory you are scanning:

your-project/
├── scanoss.json
├── src/
└── ...

Configuration Schema

Crypto Finder follows the SCANOSS Settings Schema.

Basic Example

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["node_modules/", "target/", "venv/", "*.min.js"]
      },
      "sizes": {
        "max_file_size": 10485760
      }
    }
  }
}

Skip Patterns

Skip patterns control which files and directories are excluded from scanning.

Default Skip Patterns

The following patterns are excluded automatically: Version control:

.git/
.svn/
.hg/
.bzr/

Dependencies:

node_modules/
vendor/
venv/
virtualenv/
__pycache__/

Build artefacts:

dist/
build/
target/
*.min.js
*.min.css

Archives:

*.zip
*.tar
*.tar.gz
*.tar.bz2
*.jar
*.war
*.ear

Binaries:

*.exe
*.dll
*.so
*.dylib
*.bin

Default skip patterns are defined in the source code. See the current implementation.

Custom Skip Patterns

Pattern Types

Directory patterns (end with /):

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["custom-dir/", "temp/"]
      }
    }
  }
}

File extension patterns:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["*.log", "*.tmp", "*.cache"]
      }
    }
  }
}

Specific file patterns:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["package-lock.json", "yarn.lock"]
      }
    }
  }
}

Path patterns:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["src/generated/", "test/fixtures/"]
      }
    }
  }
}

Size Limits

Configure the maximum file size to scan:

{
  "settings": {
    "skip": {
      "sizes": {
        "max_file_size": 10485760
      }
    }
  }
}

Advanced Configuration Examples

Monorepo Configuration

For large monorepos with multiple subprojects:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "*/node_modules/",
          "*/dist/",
          "*/build/",
          "*/target/",
          "docs/",
          "scripts/",
          "*.test.js",
          "*.spec.ts"
        ]
      }
    }
  }
}

JavaScript/TypeScript Project Configuration

For projects using Node.js-based tooling:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "node_modules/",
          "dist/",
          "build/",
          ".next/",
          ".nuxt/",
          "coverage/",
          "*.min.js",
          "*.bundle.js",
          "*.map"
        ]
      }
    }
  }
}

Java/Python/Go Project Configuration

For compiled or interpreted backend projects:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "target/",
          "venv/",
          "vendor/",
          "__pycache__/",
          "*.pyc",
          "*.class",
          "*.jar"
        ]
      }
    }
  }
}

CI/CD Configuration

Excludes tests and generated artefacts to reduce scan scope in automated pipelines:

{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": [
          "node_modules/",
          "vendor/",
          "venv/",
          "target/",
          "dist/",
          "build/",
          "test/",
          "tests/",
          "*.test.*",
          "*.spec.*",
          "*.min.*"
        ]
      }
    }
  }
}

Scanner Configuration

Choosing a Scanner

Crypto Finder supports multiple scanners. Select a scanner using the --scanner flag:

# Use OpenGrep (default)
crypto-finder scan /path/to/code

# Use Semgrep
crypto-finder scan --scanner semgrep /path/to/code

Valid values for --scanner: opengrep, semgrep.

Cross-File Analysis (Semgrep Pro)

When using the Semgrep scanner, you can enable cross-file (interfile) analysis with the --interfile flag. This adds the --pro flag to the underlying Semgrep command, enabling Semgrep Pro features such as cross-file taint tracking and type inference.

# Enable cross-file analysis with Semgrep Pro
crypto-finder scan --scanner semgrep --interfile /path/to/code

The --interfile flag is only supported with --scanner semgrep. Using it with other scanners will result in an error. A valid Semgrep Pro license is required.

Language Detection

Automatic Detection

By default, Crypto Finder uses go-enry to detect the programming languages present in a project automatically.

Manual Override

Override detected languages when needed:

# Scan only Java and Python files
crypto-finder scan --languages java,python /path/to/code

# Scan a single language
crypto-finder scan --languages go /path/to/code

Supported Languages

The scanner includes rules for:

C/C++
C#
Go
Java
JavaScript/TypeScript
Kotlin
PHP
Python
Ruby
Rust
Swift
And more…

Additional languages may be supported. See the rules repository for the current list. Language detection ensures that only relevant rules are loaded, which improves scan performance.

Timeout Configuration

Default Timeout

Default scan timeout: 10 minutes

Custom Timeout

# 30-minute timeout
crypto-finder scan --timeout 30m /path/to/code

# 2-hour timeout
crypto-finder scan --timeout 2h /path/to/code

# 90-second timeout
crypto-finder scan --timeout 90s /path/to/code

Recommended Timeouts

Project size	Recommended timeout
Small (<1,000 files)	5m
Medium (1,000–10,000 files)	15m
Large (10,000–50,000 files)	30m
Very large (>50,000 files)	1h+

Output Configuration

Output Destination

# Write to file
crypto-finder scan --output results.json /path/to/code

# Write to stdout (default)
crypto-finder scan /path/to/code

# Pipe to another tool
crypto-finder scan /path/to/code | jq '.findings | length'

Output Format

# SCANOSS Interim JSON format (default)
crypto-finder scan --format json /path/to/code

# CycloneDX CBOM format
crypto-finder scan --format cyclonedx /path/to/code

Logging Configuration

Verbosity Levels

# Default output
crypto-finder scan /path/to/code

# Verbose logging (info level)
crypto-finder scan -v /path/to/code
crypto-finder scan --verbose /path/to/code

# Debug logging (debug-level output)
crypto-finder scan -d /path/to/code
crypto-finder scan --debug /path/to/code

​Configuration Priority

​Application Configuration

​Config File Location

​Setting Up Configuration

​Config File Format

​Environment Variables

​Java Runtime Selection

​FindingsCache Backend

​Project Configuration (scanoss.json)

​File Location

​Configuration Schema

​Basic Example

​Skip Patterns

​Default Skip Patterns

​Custom Skip Patterns

​Pattern Types

​Size Limits

​Advanced Configuration Examples

​Monorepo Configuration

​JavaScript/TypeScript Project Configuration

​Java/Python/Go Project Configuration

​CI/CD Configuration

​Scanner Configuration

​Choosing a Scanner

​Cross-File Analysis (Semgrep Pro)

​Language Detection

​Automatic Detection

​Manual Override

​Supported Languages

​Timeout Configuration

​Default Timeout

​Custom Timeout

​Recommended Timeouts

​Output Configuration

​Output Destination

​Output Format

​Logging Configuration

​Verbosity Levels