# KyberCheck Scanner

A Rust-based CLI tool for scanning codebases for quantum-vulnerable cryptography.

**Version:** 1.2.0

## Features

- 🚀 **Parallel scanning** - Multi-threaded file processing for fast scans
- 🌐 **Remote repository scanning** - Scan GitHub repos directly without cloning
- 🔍 **20 programming languages** supported
- 🎯 **Language filtering** - Scan only specific languages
- 📊 **Impact analysis** - Database schema and API payload impact detection

## Installation

### From Source

```bash
cargo install --path .
```

### From Crates.io (when published)

```bash
cargo install kybercheck
```

## Usage

### Basic Scan

```bash
kybercheck scan /path/to/project
```

### Remote Repository Scan

Scan a GitHub repository directly without manually cloning:

```bash
# Using GitHub shorthand
kybercheck remote owner/repo

# Using full URL
kybercheck remote https://github.com/owner/repo.git

# Scan specific branch
kybercheck remote owner/repo --branch main

# Keep the cloned repo after scan
kybercheck remote owner/repo --keep

# Filter languages in remote scan
kybercheck remote owner/repo -l rust,python
```

### Scan Only Specific Languages

```bash
# Scan only Rust and Python files
kybercheck scan --languages rust,python /path/to/project

# Short form
kybercheck scan -l php,ruby,javascript /path/to/project
```

### Output to File

```bash
kybercheck scan /path/to/project --output results.json --format json
```

### Submit to Dashboard

```bash
kybercheck submit results.json --api-key YOUR_API_KEY
```

### Initialize Config

```bash
kybercheck init
```

### Show Supported Patterns

```bash
kybercheck info
```

## Command Reference

### scan

Scan a local directory or file for quantum-vulnerable cryptography.

```
kybercheck scan [OPTIONS] [PATH]

Arguments:
  [PATH]  Path to scan (default: current directory)

Options:
  -o, --output <FILE>       Output file path
  -f, --format <FORMAT>     Output format (console, json) [default: console]
  -l, --languages <LANGS>   Only scan specific languages (comma-separated)
      --dependencies        Include dependency analysis [default: true]
      --db-impact           Analyze database impacts [default: true]
      --fail-on-vuln        Exit with error if vulnerabilities found
      --min-severity <SEV>  Minimum severity (low, medium, high, critical)
  -e, --exclude <PATTERN>   Exclude patterns (can be used multiple times)
  -v, --verbose             Enable verbose output
```

### remote

Clone and scan a remote Git repository.

```
kybercheck remote [OPTIONS] <URL>

Arguments:
  <URL>  Git repository URL or GitHub shorthand (e.g., owner/repo)

Options:
  -b, --branch <BRANCH>     Branch to scan (default: default branch)
  -o, --output <FILE>       Output file path
  -l, --languages <LANGS>   Only scan specific languages (comma-separated)
      --fail-on-vuln        Exit with error if vulnerabilities found
      --min-severity <SEV>  Minimum severity (low, medium, high, critical)
  -e, --exclude <PATTERN>   Exclude patterns (can be used multiple times)
      --keep                Keep cloned repository after scan (prints path)
```

### submit

Submit scan results to KyberCheck API.

```
kybercheck submit [OPTIONS] <RESULTS>

Arguments:
  <RESULTS>  Path to scan results JSON file

Options:
      --api-key <KEY>   API key (or set KYBERCHECK_API_KEY env var)
      --api-url <URL>   API endpoint [default: https://api.kybercheck.io]
      --repo-id <ID>    Repository identifier
```

### init

Create a configuration file.

```
kybercheck init [OPTIONS]

Options:
  -f, --force  Overwrite existing config
```

## Supported Languages

| Language | Filter Names | Extensions |
|----------|--------------|------------|
| JavaScript | `javascript`, `js` | .js, .jsx, .mjs, .cjs |
| TypeScript | `typescript`, `ts` | .ts, .tsx, .mts, .cts |
| Python | `python`, `py` | .py, .pyw, .pyi |
| Go | `go` | .go |
| Java | `java` | .java |
| Kotlin | `kotlin` | .kt, .kts |
| Scala | `scala` | .scala, .sc |
| Groovy | `groovy` | .groovy, .gvy |
| Rust | `rust` | .rs |
| C | `c` | .c, .h |
| C++ | `cpp`, `c++` | .cpp, .cc, .cxx, .hpp |
| C# | `csharp`, `c#`, `cs` | .cs, .csx |
| PHP | `php` | .php, .phtml |
| Ruby | `ruby`, `rb` | .rb, .rbw, .rake |
| Swift | `swift` | .swift |
| Objective-C | `objectivec`, `objc` | .m, .mm |
| Shell/Bash | `shell`, `sh`, `bash` | .sh, .bash, .zsh |
| Perl | `perl` | .pl, .pm |
| Lua | `lua` | .lua |
| Dart | `dart` | .dart |

## Configuration

Create `.kybercheck.toml` in your project root:

```toml
[scan]
analyze_dependencies = true
analyze_db_impact = true
min_severity = "low"

# Only scan specific languages (empty = scan all)
languages = ["rust", "python", "javascript"]

# Patterns to exclude from scanning
exclude = [
    "node_modules/**",
    "vendor/**",
    "target/**",
]

[api]
url = "https://api.kybercheck.io"

[repo]
id = "my-org/my-repo"
```

## Default Exclusions

The scanner automatically ignores common build artifacts and dependencies:

- **Version Control:** `.git`, `.svn`, `.hg`
- **Node.js:** `node_modules`, `dist`, `build`, `.next`, minified JS
- **Python:** `__pycache__`, `venv`, `.venv`, `site-packages`
- **Rust:** `target`
- **Go/PHP:** `vendor`
- **Java/JVM:** `.gradle`, `.m2`, `bin`, `out`, `.class`, `.jar`
- **C#/.NET:** `obj`, `packages`, `.nuget`
- **Ruby:** `bundle`, `.bundle`
- **Swift/iOS:** `Pods`, `DerivedData`
- **Dart/Flutter:** `.dart_tool`, `build`
- **IDE:** `.idea`, `.vscode`, `.vs`
- **Coverage:** `coverage`, `.nyc_output`, `htmlcov`

## Environment Variables

- `KYBERCHECK_API_KEY` - API key for submissions
- `KYBERCHECK_API_URL` - API endpoint URL
- `KYBERCHECK_REPO_ID` - Repository identifier

## Detected Vulnerabilities

### Quantum-Vulnerable (Critical)
- RSA (all key sizes)
- ECDSA / ECDH
- DSA
- Diffie-Hellman

### Weak Cryptography (High)
- SHA-1
- MD5
- Weak random number generators

### Deprecated (Medium)
- 3DES
- RC4
- DES

## Migration Impact Analysis

The scanner detects when vulnerabilities may cause:

1. **Database Schema Conflicts** - PQC keys are larger and may not fit existing columns
2. **API Payload Bloat** - Larger keys affect response sizes
3. **Architectural Refactoring** - RSA must be replaced with KEM pattern
4. **Certificate Infrastructure** - PKI changes required

## NIST PQC Standards (Target Migration)

| Algorithm | Purpose |
|-----------|---------|
| CRYSTALS-Kyber (ML-KEM) | Key Encapsulation Mechanism |
| CRYSTALS-Dilithium (ML-DSA) | Digital Signatures |
| SPHINCS+ | Hash-based Signatures |
| FALCON | Lattice-based Signatures |

## Examples

```bash
# Scan current directory
kybercheck scan

# Scan a specific project
kybercheck scan /path/to/project

# Scan only Python and JavaScript files
kybercheck scan -l python,javascript /path/to/project

# Output JSON results
kybercheck scan --output results.json --format json /path/to/project

# Fail CI if vulnerabilities found
kybercheck scan --fail-on-vuln --min-severity high /path/to/project

# Exclude test directories
kybercheck scan -e "**/*test*/**" -e "**/spec/**" /path/to/project

# Scan a GitHub repo directly
kybercheck remote microsoft/vscode -l typescript

# Scan a crypto library repo
kybercheck remote phpseclib/phpseclib -l php --output results.json
```

## Performance

KyberCheck v1.2.0 uses parallel processing for fast scanning:

- Multi-threaded file reading and analysis
- Shallow cloning for remote repositories
- Automatic CPU core detection for optimal thread count

## Exit Codes

- `0` - Success (no vulnerabilities, or vulnerabilities found but --fail-on-vuln not set)
- `1` - Vulnerabilities found (when --fail-on-vuln is set)
- `2` - Error during scanning

## License

MIT License
