Basic Usage

Learn how to effectively scan files and directories for sensitive data using Vypher’s core scanning features.

Basic Scanning Commands

Scan a Directory

The most common usage is scanning a directory recursively:


# Scan current directory
vypher scan .
 
# Scan specific directory
vypher scan /path/to/project
 
# Scan with progress information
vypher scan ./src --verbose

Scan a Single File

Target specific files for focused analysis:


# Scan a single file
vypher scan config.py
 
# Scan multiple specific files
vypher scan config.py secrets.json database.sql

Scan from Standard Input

Process data from pipes or redirected input:


# Scan clipboard content
pbpaste | vypher scan -
 
# Scan command output
cat config.json | vypher scan -
 
# Scan git diff
git diff | vypher scan -

File Filtering

Include Patterns

Specify which files to scan using glob patterns:


# Scan only Python files
vypher scan . --include-patterns "*.py"
 
# Scan multiple file types
vypher scan . --include-patterns "*.py,*.js,*.json"
 
# Scan configuration files
vypher scan . --include-patterns "*.config.*,*.env*,*rc"
 
# Complex patterns
vypher scan . --include-patterns "src/**/*.js,config/**/*.yaml"

Exclude Patterns

Skip files and directories to improve performance:


# Exclude common build directories
vypher scan . --exclude-patterns "node_modules/**,build/**,dist/**"
 
# Exclude minified files and logs
vypher scan . --exclude-patterns "*.min.*,*.log,temp/**"
 
# Exclude test files
vypher scan . --exclude-patterns "test/**,tests/**,*test.py,*spec.js"
 
# Multiple exclusions
vypher scan . \
  --exclude-patterns "node_modules/**,vendor/**,.git/**,*.min.*"

Pattern Examples

Common pattern combinations for different project types:

Web Applications:


vypher scan . \
  --include-patterns "*.js,*.ts,*.jsx,*.tsx,*.json,*.env*" \
  --exclude-patterns "node_modules/**,build/**,dist/**,*.min.*"

Python Projects:


vypher scan . \
  --include-patterns "*.py,*.yaml,*.yml,*.ini,*.cfg" \
  --exclude-patterns "venv/**,__pycache__/**,*.pyc,build/**"

Detector Configuration

Select Specific Detectors

Choose which types of sensitive data to look for:


# Scan for PII only
vypher scan . --detectors pii
 
# Multiple detectors
vypher scan . --detectors pii,secrets,phi
 
# All built-in detectors
vypher scan . --detectors all
 
# Include custom detectors
vypher scan . --detectors pii,secrets --include-custom

Detector Sensitivity

Adjust detection sensitivity to balance thoroughness vs false positives:


# High sensitivity (more matches, potential false positives)
vypher scan . --sensitivity high
 
# Medium sensitivity (balanced)
vypher scan . --sensitivity medium
 
# Low sensitivity (fewer false positives, might miss some matches)
vypher scan . --sensitivity low

Output Options

Console Output

Control what’s displayed during scanning:


# Quiet mode (errors only)
vypher scan . --quiet
 
# Verbose output with details
vypher scan . --verbose
 
# Show progress bar
vypher scan . --progress
 
# Summary only
vypher scan . --summary-only

File Output

Save results to files:


# Save to JSON file
vypher scan . --output results.json
 
# Save to CSV
vypher scan . --output results.csv --format csv
 
# Save to XML
vypher scan . --output results.xml --format xml
 
# Multiple output formats
vypher scan . --output results.json --output summary.txt --format txt

Advanced Options

Performance Tuning

Optimize scanning for different scenarios:


# Increase thread count for large repositories
vypher scan . --threads 8
 
# Limit file size to avoid huge files
vypher scan . --max-file-size 10MB
 
# Set memory limit
vypher scan . --max-memory 1GB
 
# Timeout for large scans
vypher scan . --timeout 30m

Incremental Scanning

Scan only changed files for better performance:


# Only scan files modified in last 24 hours
vypher scan . --since 24h
 
# Scan files modified since specific date
vypher scan . --since 2024-01-01
 
# Scan only Git-tracked files
vypher scan . --git-only
 
# Scan only modified files in Git
vypher scan . --git-diff

Context and Metadata

Include additional information in results:


# Include file metadata
vypher scan . --include-metadata
 
# Show context around matches
vypher scan . --context 3
 
# Include line numbers
vypher scan . --line-numbers
 
# Show file hashes
vypher scan . --include-hashes

Error Handling

Skip Problematic Files

Handle files that can’t be processed:


# Skip binary files automatically
vypher scan . --skip-binary
 
# Skip files that cause errors
vypher scan . --skip-errors
 
# Continue on permission denied
vypher scan . --ignore-permission-errors
 
# Set timeout for individual files
vypher scan . --file-timeout 30s

Logging and Debugging

Get detailed information about scan process:


# Enable debug logging
vypher scan . --debug
 
# Log to file
vypher scan . --log-file scan.log
 
# Set log level
vypher scan . --log-level info

Exit Codes

Vypher returns different exit codes based on scan results:

0: No sensitive data found
1: Sensitive data detected
2: Scan completed with warnings
3: Scan failed due to errors

Using Exit Codes in Scripts


#!/bin/bash
 
vypher scan /path/to/code
 
case $? in
  0)
    echo "✓ No sensitive data found"
    ;;
  1)
    echo "⚠ Sensitive data detected - review required"
    exit 1
    ;;
  2)
    echo "⚠ Scan completed with warnings"
    ;;
  3)
    echo "✗ Scan failed"
    exit 1
    ;;
esac

Configuration File Usage

Instead of command-line options, use a configuration file:


# vypher.yaml
scan:
  paths: ["src/", "config/"]
  include_patterns: ["*.py", "*.js", "*.json"]
  exclude_patterns: ["node_modules/**", "*.min.*"]
  
detectors: ["pii", "secrets"]
sensitivity: medium
 
output:
  format: json
  file: scan_results.json
  
options:
  verbose: true
  threads: 4
  max_file_size: "10MB"

Then run:


vypher scan --config vypher.yaml

Common Use Cases

Pre-commit Hook


# Check staged files only
vypher scan --git-staged
 
# Fail if sensitive data found
vypher scan --git-staged --fail-on-match

CI/CD Pipeline


# Scan entire codebase
vypher scan . --output ci_results.json --quiet
 
# Only fail on high-severity findings
vypher scan . --fail-level high

Code Review


# Scan diff between branches
git diff main..feature-branch | vypher scan -
 
# Scan specific PR files
vypher scan $(git diff --name-only main..HEAD)

Next Steps

Git History Scanning - Scan repository history
Output Formats - Customize result formats
Configuration - Advanced configuration options