> ## 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.

# Configuration

> Crypto Finder supports flexible configuration through multiple mechanisms: `scanoss.json` files, command-line flags, and environment variables.

## Configuration Priority

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

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

## Application Configuration

### Config File Location

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

### Setting Up Configuration

Use the `configure` command to set persistent application settings:

```bash theme={null}
# 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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](scanoss-settings).

### Basic Example

```json theme={null}
{
  "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](https://github.com/scanoss/crypto-finder/blob/main/internal/skip/source_defaults.go).

### Custom Skip Patterns

#### Pattern Types

1. **Directory patterns** (end with `/`):

```json theme={null}
{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["custom-dir/", "temp/"]
      }
    }
  }
}
```

2. **File extension patterns**:

```json theme={null}
{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["*.log", "*.tmp", "*.cache"]
      }
    }
  }
}
```

3. **Specific file patterns**:

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

4. **Path patterns**:

```json theme={null}
{
  "settings": {
    "skip": {
      "patterns": {
        "scanning": ["src/generated/", "test/fixtures/"]
      }
    }
  }
}
```

### Size Limits

Configure the maximum file size to scan:

```json theme={null}
{
  "settings": {
    "skip": {
      "sizes": {
        "max_file_size": 10485760
      }
    }
  }
}
```

## Advanced Configuration Examples

### Monorepo Configuration

For large monorepos with multiple subprojects:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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.

```bash theme={null}
# 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](https://github.com/go-enry/go-enry) to detect the programming languages present in a project automatically.

### Manual Override

Override detected languages when needed:

```bash theme={null}
# 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](https://github.com/scanoss/crypto-finder) 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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
```