Scan Command

The scan command is RootCause's primary functionality. It analyses source code to find security and quality issues using custom rules.

Scan code for security vulnerabilities and quality issues

Usage: rootcause scan [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to scan (file or directory)

Options:
      --rules <RULES>
          Path to rules directory or ruleset [default: ~/.config/rootcause/rules]
      --semgrep-rules <SEMGREP_RULES>
          Path to Semgrep-compatible rules
      --format <FORMAT>
          Output format for scan results [default: text] [possible values: text, json, sarif]
      --fail-on <FAIL_ON>
          Exit with error code if findings of this severity or higher are found
      --threads <THREADS>
          Number of parallel threads to use for scanning [default: 16]
      --exclude <EXCLUDE>
          Exclude files matching these patterns (supports regex)
      --no-default-exclude
          Do not use default exclusion patterns
      --max-file-size <MAX_FILE_SIZE>
          Maximum file size to scan (in bytes) [default: 5242880]
      --timeout-file-ms <TIMEOUT_FILE_MS>
          Timeout per file in milliseconds
      --timeout-rule-ms <TIMEOUT_RULE_MS>
          Timeout per rule in milliseconds
      --metrics <METRICS>
          Write performance metrics to file
      --baseline <BASELINE>
          Path to baseline file for comparison
      --write-baseline <WRITE_BASELINE>
          Write baseline file with current findings
      --plugin <PLUGINS>
          Load plugins from specified paths
      --plugin-opt <PLUGIN_OPTS>
          Plugin options as key=value pairs
      --plugin-config <PLUGIN_CONFIG>
          Path to plugin configuration file
      --suppress-comment <SUPPRESS_COMMENT>
          Comment pattern to suppress findings [default: sast-ignore]
      --stream
          Enable streaming mode for large outputs
      --chunk-size <CHUNK_SIZE>
          Number of findings to process in each chunk [default: 100]
      --dump-taints
          Dump taint analysis data for debugging
      --debug
          Enable debug output
      --quiet
          Suppress non-essential output
      --apply-fixes
          Automatically apply suggested fixes
      --cache-dir <CACHE_DIR>
          Directory to store cache files
  -h, --help
          Print help

Exit codes

The scan command uses standard exit codes:

• 0: Success, no issues found or issues below the --fail-on threshold
• 1: General error (configuration problems, files not found, etc.)
• 2: Issues found at or above the --fail-on threshold

Most commonly used options

Basic configuration

• --rules <RULES>: Rules directory (default: ~/.config/rootcause/rules)
• --format <FORMAT>: Output format (text, json, sarif)
• --threads <THREADS>: Number of parallel threads (default: 16)

Quality control

• --fail-on <SEVERITY>: Fail if issues of this severity or higher are found
• --exclude <PATTERNS>: Exclude files matching these patterns (regex)
• --no-default-exclude: Do not use default exclusion patterns

Optimisation

• --max-file-size <BYTES>: Maximum file size to scan (default: 5MB)
• --timeout-file-ms <MS>: Timeout per file in milliseconds
• --timeout-rule-ms <MS>: Timeout per rule in milliseconds
• --stream: Streaming mode for large outputs
• --chunk-size <SIZE>: Process files in batches (default: 100)

Plugins

• --plugin <PATH>: Load plugins from specific paths
• --plugin-opt <KEY=VALUE>: Plugin options as key=value pairs
• --plugin-config <PATH>: Plugin configuration file

Special modes

• --debug: Enable debug output
• --quiet: Suppress non-essential output
• --apply-fixes: Automatically apply suggested fixes
• --dump-taints: Dump data-flow analysis data for debugging