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

# Remote Rulesets

> Crypto Finder can automatically fetch curated rulesets from the SCANOSS  API, providing up-to-date cryptographic detection rules without requiring manual  management.

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

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

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

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

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

```bash theme={null}
   crypto-finder scan --max-stale-age 90d /path/to/code
```

3. **Use local rulesets** instead:

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