Remote Rulesets

​

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

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

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

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

• 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

• 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]

​

Cache Not Available / Air-Gapped Environments

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

WARN: Failed to download remote rules (timeout). Using stale cache
(age: 5d, cached-at: 2025-01-10 10:30:00 UTC)

• The scan completes successfully using the stale cache
• A warning is written to stderr
• The process exits with code 0 (success)

crypto-finder scan --strict /path/to/code

​

Cache Too Stale

⚠️ Note: Verify that the error message below reflects the actual output emitted by crypto-finder in this scenario.

Error: failed to download ruleset: server error: please try again later:
500 Internal Server Error

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

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