# 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
| 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)
| 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