Quick Start

Scan a Directory

# Scan current directory
codescan .

# Scan a specific directory
codescan src/

# Scan multiple paths
codescan src/ tests/ scripts/

Example Output

error[SECRET001]: Hardcoded password
  --> src/db/connection.py:14:12
   |
14 |   password = "hunter2"
   |              ^^^^^^^^^
   = help: Use environment variables or a secrets manager instead

warning[CRYPTO001]: Weak hashing algorithm
  --> src/auth/hash.py:8:5
   |
 8 |   hashlib.md5(data).hexdigest()
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   = help: Use SHA-256 or better

found 1 error, 1 warning, 0 notes

Common Options

Filter by Severity

# Show only errors
codescan --severity error .

# Show warnings and above
codescan --severity warning .

Exclude Paths

codescan --exclude "tests/**" --exclude "vendor/**" .

Only Check Specific Rules

codescan --only-rules SECRET001,SECRET002,CRYPTO001 .

Skip Specific Rules

codescan --skip-rules INFRA004 .

Output Formats

# Pretty (default when interactive)
codescan --format pretty .

# JSON (one object per line)
codescan --format json . > findings.jsonl

# Plain text (default in CI/pipes)
codescan --format text .

Show Suppressed Findings

codescan --show-suppressed .

List All Rules

codescan --list-rules

CI Integration

codescan exits with code 1 when any findings meet the --fail-on threshold (default: error).

# GitHub Actions example
- name: Security scan
  run: codescan --format text --fail-on error src/

# Fail on warnings too
codescan --fail-on warning src/

# Never fail (audit mode)
codescan --fail-on none src/

Using a Config File

Create codescan.toml in your project root:

[scanner]
max_file_size = 524288  # 512 KB

[exclude]
paths = ["vendor", "node_modules", "dist", ".git"]
extensions = ["min.js", "lock"]

[rules]
disabled = ["INFRA004"]

[rules.severity_overrides]
SECRET001 = "error"
CRYPTO001 = "warning"

See the Configuration page for all options.