Configuration priority
Crypto Finder applies settings in this order, from highest to lowest priority:- 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.jsonin target directory) - Default values
Application configuration
Config file location
Setting up configuration
Use theconfigure command to set persistent application settings:
Config file format
Environment variables
Plain-HTTP API URLs
Crypto Finder talks to the SCANOSS API over HTTPS only. Plain HTTP would send the API key and the downloaded rules unencrypted. Since 0.48.0:- A plain-HTTP API URL on another host is refused, whether it comes from
--api-url,SCANOSS_API_URL, or the config file. The command fails with aninvalid_argumentserror before it sends any request. - A redirect from HTTPS to plain HTTP is refused.
- HTTP to
localhostor a loopback address (127.0.0.1,::1) is always accepted, since the traffic never leaves the machine. - A scan with
--no-remote-rulesand no API key never contacts the API, so the API URL does not matter.
crypto-finder configure --allow-http=false clears the saved opt-in. Every run that uses plain HTTP logs a warning that the API key is not encrypted.
Java runtime selection
For Java dependency scans and call graph export, Crypto Finder can use a specific JDK major version for each scan. The supported majors are8, 11, 17, and 21.
On the command line, use --java-jdk-major and the repeatable --java-jdk-home <major>=<path>. In the environment or the config file, use SCANOSS_JAVA_JDK_MAJOR, SCANOSS_JAVA_JDK_HOMES, or the matching config file keys. The standalone CLI defaults to auto, which uses the ambient JAVA_HOME when it is available.
Example:
FindingsCache backend
Crypto Finder caches each dependency’s scan results in aFindingsCache, so a warm scan skips the OpenGrep work for dependencies it has already analysed. There are two backends:
Select the backend in any of these ways:
With
postgres, you MUST provide the connection string in SCANOSS_FINDINGS_CACHE_DSN. If it is missing, the scan exits with a clear error. It never falls back to disk silently, because a misconfigured fleet would then lose cache sharing and nobody would notice.
Crypto Finder creates the table on first use with an idempotent CREATE TABLE IF NOT EXISTS, so there is no separate migration step. The default table name is findings_cache. If you run several deployments in the same database, override it with SCANOSS_FINDINGS_CACHE_TABLE.
Example:
- The cache key includes the rules hash, so changing the rules invalidates entries automatically. You never need to evict entries by hand.
- A disk backend failure isn’t fatal. Crypto Finder logs a warning and the scan continues without caching. A postgres backend failure, such as a missing DSN, an unreachable database, or a schema bootstrap error, is fatal.
- Each
crypto-finder scaninvocation opens its own Postgres pool and closes it when the scan finishes. For long-lived workers, reuse a single binary process where you can, so the pool setup cost is spread over more scans.
Project configuration (scanoss.json)
Thescanoss.json file in your project directory configures scan behavior and skip patterns.
File location
Placescanoss.json in the root of the directory you’re scanning:
Configuration schema
Crypto Finder follows the SCANOSS Settings Schema.Basic example
Skip patterns
Skip patterns control which files and directories Crypto Finder leaves out of a scan.Default skip patterns
Crypto Finder excludes these patterns automatically:
Since 0.46.0, these patterns match only below the root being scanned: the project, or a dependency’s own package directory. A directory above that root with one of these names excludes nothing. A checkout under a
build/ or dist/ directory, an npm dependency installed under node_modules/, and a virtualenv named venv are therefore scanned and enter the call graph. A node_modules/ or venv/ inside the scanned project is still skipped. Before 0.46.0, such a parent directory removed those files from the call graph, and their findings reported reachability not_applicable, including a project’s own findings when it was checked out under build/.
The scan also honours .gitignore. Since 0.46.0, when the scan target is itself a directory its enclosing Git repository ignores (for example a project copied under an ignored tmp/ or bin/), the target is scanned as its own work tree: its own .gitignore files apply and the enclosing repository’s do not. Before 0.46.0 such a target lost all of its findings. A target that its repository does not ignore is unchanged: the repository’s .gitignore rules still apply inside it.
For the complete list, see the default skip patterns.
Custom skip patterns
Pattern types
-
Directory patterns (end with
/): -
File extension patterns:
-
Specific file patterns:
-
Path patterns:
Size limits
Set the maximum size of a file to scan:Advanced configuration examples
Monorepo configuration
For large monorepos with several subprojects:Frontend project configuration
For JavaScript and TypeScript projects:Backend project configuration
For Java, Python, and Go projects:CI/CD configuration
This configuration scans as little as possible, to keep CI/CD pipelines fast:Scanner configuration
Choosing a scanner
Crypto Finder supports more than one scanner. Select one with a command-line flag:Cross-file analysis (Semgrep Pro)
With the Semgrep scanner, you can turn on cross-file (interfile) analysis with the--interfile flag. The flag adds --pro to the underlying Semgrep command, which turns on Semgrep Pro features such as cross-file taint tracking and type inference.
Note:--interfileworks only with--scanner semgrep, and using it with any other scanner is an error. It requires a valid Semgrep Pro license.
OpenGrep execution mode
By default,scan and annotate run OpenGrep in core mode: Crypto Finder runs opengrep-core directly, for the project scan and every dependency batch, instead of the Python opengrep CLI. This skips the wrapper’s startup and rule loading. Findings are the same as with the CLI.
Core mode is verified against OpenGrep 1.30.2, the version the Docker images ship. Crypto Finder runs the opengrep CLI instead whenever core mode cannot run:
- the installed OpenGrep is another version,
- no matching
opengrep-corebinary is found, - extra scanner arguments are set, or
- the core run fails, including over a rule
opengrep-corecannot load. The CLI then rejects the rules file as it always has.
opengrep-core binary that the opengrep CLI unpacks into its cache directory (~/.cache/opengrep/v<version>/), and beside the opengrep executable. To name the binary yourself, set SCANOSS_OPENGREP_CORE. The core-ready rules file is cached under the Crypto Finder cache directory, in opengrep-core-rules/.
To always run the CLI, opt out of core mode:
--opengrep-mode applies only to the OpenGrep scanner, and is ignored with a warning for --scanner semgrep.
Rule prefilter
--rule-prefilter imports drops, for each scanned unit (the project and each dependency batch), the rules whose library that unit’s sources never import. It covers Go, Java, Python, JavaScript/TypeScript, Rust, and C/C++ sources. Crypto Finder judges a rule’s import requirement from the import guards and qualified names in its patterns, or from an explicit metadata.imports list in the rule. Rules whose requirement is unknown are always kept.
off, which runs every rule. The flag wins over the environment variable, and the prefilter applies only to the OpenGrep scanner. The OpenGrep mode and the prefilter are both part of the dependency findings cache key.
Language detection
Automatic detection
By default, crypto-finder uses go-enry to detect a project’s languages. When an extension belongs to several languages, such as.rs (Rust, RenderScript, and XML), the file is classified by its content rather than its name alone.
Manual override
You can override the detected languages:Supported languages
The scanner has rules for these languages, among others:- C/C++
- C#
- Go
- Java
- JavaScript/TypeScript
- Kotlin
- PHP
- Python
- Ruby
- Rust
- Swift
Timeout configuration
Default timeout
The default scan timeout is 10 minutes.Custom timeout
Per-file rule time limits and retries
--timeout bounds the whole scan. OpenGrep also limits the time each rule may spend on each file: 5 s in the project scan and 30 s in dependency scans. On a busy host, a large file can reach that limit and lose its findings, so Crypto Finder retries those files:
- A rule that timed out on a file runs again on that file with four times the limit, at least 30 s.
- A file OpenGrep gave up on, after three timed-out rules or because the time limit interrupted its parsing, runs every rule again.
- A file the retry still cannot finish runs once more with a longer limit. Project scans retry at 30 s and then 120 s, and dependency scans at 120 s and then 255 s.
incompleteFiles in the report. If the scan’s --timeout expires, or you press Ctrl-C, while retries are running, the scan fails with the timeout or cancellation error instead of reporting the findings from before the retry.