Skip to content

CONFIGURATION.md

Latest commit

 

History

History
88 lines (63 loc) · 5.18 KB

CONFIGURATION.md

File metadata and controls

88 lines (63 loc) · 5.18 KB
Raw

Configuration

SessionScope reads an optional sessionscope.toml from the current directory. The file is safe to check in and contains no secrets.

Bootstrap

Run sessionscope init to generate a fresh config. The command is non-interactive, does not require network access, and refuses to overwrite an existing config unless --force is passed.

# SessionScope configuration
# Generated by `sessionscope init`. Safe to check in.
# Do not put token values, private keys, bearer strings, cookie values, or
# environment-specific secrets in this file.

# Scan roots are repository-relative. v0.1.0 uses the first path.
scan_paths = ["."]

# Include patterns form the allowlist for source/config discovery.
include = ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx", "**/*.py", "**/*.json", "**/*.yaml", "**/*.yml", "**/*.toml"]

# Exclude patterns are applied after includes and in addition to .gitignore
# and built-in dependency/vendor/build/sensitive-path skips.
exclude = ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"]

# v0.1.0 uses the first configured format unless --format is passed.
formats = ["markdown"]

# Policy defaults keep scans advisory. Use enforce mode in CI after reviewing reports.
mode = "advisory"
fail_severity = "high"
fail_categories = []
include_finding_ids = []
exclude_finding_ids = []
# baseline = "sessionscope-baseline.json"

max_file_size_bytes = 512000

# Hints are parsed for future detectors and have no runtime effect yet.
framework_hints = ["express", "nextjs", "fastapi", "django"]
provider_hints = ["authjs", "nextauth", "passport", "oauth", "oidc", "auth0", "okta", "cognito", "supabase", "clerk"]

Fields

Field Purpose
scan_paths Default roots to scan when no --path flag is supplied.
include Glob patterns to include. Replaced (not merged) by --include.
exclude Glob patterns to exclude. Appended to by --exclude.
formats Default output formats. The first value is used unless --format is passed.
mode Default policy mode. Overridden by --mode.
fail_severity Minimum severity that fails enforce mode. Overridden by --fail-severity.
fail_categories Finding categories that fail enforce mode. Empty means all categories. Overridden by --fail-category.
include_finding_ids Finding IDs that always fail in enforce mode unless excluded. Overridden by --include-finding-id.
exclude_finding_ids Finding IDs that never fail. Overridden by --exclude-finding-id.
baseline Optional JSON report/baseline path whose finding IDs are suppressed. Overridden by --baseline.
max_file_size_bytes Skip files larger than this; overridden by --max-file-size. Default 512000 (lowered from 1000000 in v0.1.0 to cap per-worker memory).
framework_hints Parsed for future framework-specific tuning. v0.1.0 built-in detectors infer frameworks from source patterns and do not use this value yet.
provider_hints Parsed for future provider-specific tuning. v0.1.0 built-in detectors infer provider evidence from source patterns and do not use this value yet.

Precedence

When resolving effective options for a scan, SessionScope applies sources in this order:

  1. CLI flags — --path, --include, --exclude, --format, --output-dir, --max-file-size, and policy options.
  2. sessionscope.toml — values from the loaded config.
  3. Built-in defaults — used when neither CLI flags nor config supply a value.

--include replaces configured include patterns; --exclude appends to configured excludes. This lets you tighten a scan without losing the project's safe baseline.

Built-in skips

In addition to user-supplied excludes, SessionScope:

  • Respects .gitignore where practical.
  • Applies built-in dependency, vendor, and build-output excludes (node_modules, target, dist, .venv, and similar).
  • Skips known-sensitive paths such as .env, .env.*, and obvious private-key material before source loading.

These defaults are protective — even with a permissive include, secret-bearing files are filtered before any detector touches their contents.

Per-file budgets

SessionScope enforces two budgets per file to keep the scan bounded:

  • Memory — max_file_size_bytes defaults to 512000 (512 KB). Files larger than this are skipped with reason too_large. The pipeline additionally caps simultaneous in-flight file bodies at min(available_parallelism(), 4) so a single scan never holds more than four file buffers in memory at once.
  • CPU — per_file_budget defaults to 2s. The detector registry checks the elapsed budget before and after each detector. When detectors collectively exceed this budget on a single file, the file is skipped with reason timeout and the rest of the scan continues. Files that look minified (source.lines() < source.len() / 200) have their budget halved to keep one large bundle from blocking a worker.

These defaults are intended as safety rails, not knobs to tune for performance. Lower the size cap when scanning constrained CI runners; the CPU budget is currently fixed in code. Timeout enforcement is cooperative at detector boundaries; a detector that never returns cannot be preempted mid-call.