Skip to main content

​
Features

  • Automatic Downloads: The default dca (deep code analysis) ruleset is automatically fetched on the first scan
  • Local Caching: Downloaded rulesets are cached at ~/.scanoss/crypto-finder/cache/
  • Time-to-Live (TTL)-Based Expiration:
    • Pinned versions (e.g., v1.0.0): cache TTL of 7 days
    • Latest versions: cache TTL of 24 hours
  • Stale Cache Fallback: When the API is unreachable and the cache has expired, crypto-finder automatically falls back to the expired cache if it is within the maximum stale age (default: 30 days). Use --strict to disable this behaviour.
  • Checksum Verification: SHA256 verification ensures ruleset integrity
  • Retry Logic: Automatic retry with exponential backoff on network failures
  • Combined Rulesets: Remote and local rulesets can be used together in a single scan

​
Configuration

​
1. API Key Setup

You can configure your API key using one of three methods (in priority order): 
# Method 1: CLI flag (highest priority)
crypto-finder scan --api-key YOUR_KEY /path/to/code

# Method 2: Environment variable
export SCANOSS_API_KEY=YOUR_KEY
crypto-finder scan /path/to/code

# Method 3: Config file (recommended for persistent use)
crypto-finder configure --api-key YOUR_KEY
crypto-finder scan /path/to/code

​
2. API URL (Optional)

The default API URL is https://api.scanoss.com. To use a custom instance: 
# Via configure command
crypto-finder configure --api-url https://custom.scanoss.com

# Via environment variable
export SCANOSS_API_URL=https://custom.scanoss.com

# Via CLI flag
crypto-finder scan --api-url https://custom.scanoss.com /path/to/code

​
Usage Examples

# Use remote rulesets (default behaviour, with stale cache fallback)
crypto-finder scan /path/to/code

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

# Disable remote rulesets
crypto-finder scan --no-remote-rules --rules-dir ./local-rules /path/to/code

# Force a fresh download (bypass cache)
crypto-finder scan --no-cache /path/to/code

# Strict mode: fail if cache has expired and API is unreachable (no stale cache
# fallback)
crypto-finder scan --strict /path/to/code

# Set the maximum age for stale cache fallback (default: 30 days, maximum: 90 days)
crypto-finder scan --max-stale-age 60d /path/to/code

​
Cache Management

​
Cache Location

~/.scanoss/crypto-finder/cache/rulesets/{name}/{version}/
  ├── manifest.json              # Ruleset metadata
  ├── .cache-meta.json           # Cache metadata (timestamps, checksum, TTL)
  └── [language dirs]/           # Rule files organised by language

​
Cache Behaviour

  • First scan: Downloads and caches the default dca ruleset
  • Subsequent scans: Uses the cached version if it has not expired
  • Expired cache: Automatically re-downloads on the next scan
  • API unreachable with expired cache: Falls back to stale cache if within the maximum stale age limit
  • Manual cleanup: Delete ~/.scanoss/crypto-finder/cache/ to clear the cache

​
Stale Cache Fallback (Default Behaviour)

When the cache expires and the API is unreachable, crypto-finder automatically falls back to the expired cache, provided it is within the maximum stale age (default: 30 days). Flow:
  1. Check whether the cache is valid (not expired)
    • ✅ Valid → Use cached rulesets
  2. Cache expired → Attempt to download fresh rulesets from the API
    • ✅ API reachable → Download and update cache
    • ❌ API unreachable → Check stale cache fallback:
      • If cache age ≤ max stale age (30 days) → Use stale cache with warning
      • If cache age > max stale age → Fail with error
      • If --strict flag is set → Fail with error
Rationale:
  • Resilience: Transient API outages do not interrupt scans
  • CI/CD reliability: Pipeline failures caused by infrastructure issues are avoided
  • Offline capability: Scanning can continue with slightly outdated rulesets
When to use --strict:
  • Compliance audits that require fresh rulesets
  • Security-critical scans where stale rulesets are not acceptable
  • Environments where a scan failure is preferable to using outdated rulesets

​
Troubleshooting

​
No API Key Error

Error: API key required for remote rules

Configure your API key using one of:
  1. CLI flag:    crypto-finder scan --api-key <key> [target]
  2. Environment: export SCANOSS_API_KEY=<key>
  3. Config file: crypto-finder configure --api-key <key>

Or disable remote rules: crypto-finder scan --no-remote-rules [target]
Solution: Configure your API key using any of the methods shown above.

​
Cache Not Available / Air-Gapped Environments

If you are working in an air-gapped environment and need to use cached rulesets: Solution:
  1. Run a scan whilst connected to the internet to download and cache the rulesets
  2. Transfer the cache directory (~/.scanoss/crypto-finder/cache/) to the air-gapped environment (for example, via removable media)
  3. Crypto-finder will automatically use the cache within the TTL period (24 hours for latest versions; 7 days for pinned versions)
  4. After the TTL expires, scans will use the stale cache fallback (up to 30 days) and emit a warning
  5. For long-term offline use, consider switching to --no-remote-rules --rules-dir with local rulesets

​
API Unreachable / Network Timeout

When the API is unreachable and an expired cache exists, crypto-finder automatically falls back to the stale cache and logs a warning. Example warning: 
WARN: Failed to download remote rules (timeout). Using stale cache
(age: 5d, cached-at: 2025-01-10 10:30:00 UTC)
Behaviour:
  • The scan completes successfully using the stale cache
  • A warning is written to stderr
  • The process exits with code 0 (success)
To disable fallback and fail instead: 
crypto-finder scan --strict /path/to/code

​
Cache Too Stale

If the cached rulesets exceed the maximum stale age (default: 30 days), the scan will fail.
⚠️ Note: Verify that the error message below reflects the actual output emitted by crypto-finder in this scenario.
Error: 
Error: failed to download ruleset: server error: please try again later:
500 Internal Server Error
Solutions:
  1. Wait for the API to recover and retry
  2. Increase the maximum stale age (up to 90 days):
   crypto-finder scan --max-stale-age 90d /path/to/code
  1. Use local rulesets instead:
   crypto-finder scan --no-remote-rules --rules-dir ./local-rules /path/to/code

​
Best Practices

  1. Initial setup: Configure your API key once using crypto-finder configure --api-key <key>
  2. Hybrid approach: Combine remote rulesets with project-specific local rules for additional customisation
  3. CI/CD pipelines:
    • Use the SCANOSS_API_KEY environment variable for secure key management
    • The default behaviour (with stale cache fallback) is recommended for most pipelines, as it prevents failures caused by transient API issues
    • Use --strict for compliance-critical pipelines where fresh rulesets are required
    • Use --max-stale-age to tune the acceptable staleness window (e.g., --max-stale-age 7d)
  4. Offline/air-gapped environments:
    • Pre-cache rulesets before going offline
    • Stale cache fallback provides up to 30 days of coverage (configurable up to 90 days)
    • For longer offline periods, use --no-remote-rules --rules-dir with local rulesets