scry

A security-focused CLI that reveals hidden risks in JavaScript and Node.js codebases.

In fantasy, to scry means to reveal hidden truths. scry applies the same idea to code.

What is scry?

scry is a command-line security scanner that detects common but dangerous security mistakes in JavaScript/TypeScript projects and provides:

• Clear explanations of why each issue is risky
• Actionable fixes with code examples
• Educational context to build security awareness
• Fast, focused scanning without overwhelming noise

Quick Start

Install globally from npm:

# Install globally
npm install -g @johsam-f/scry

# Or use with npx (no installation required)
npx @johsam-f/scry scan .

Install locally from npm:

#install locally
npm install @johsam-f/scry

Basic usage:

# Scan current directory
scry scan .

# Scan specific path
scry scan ./src

# Strict mode (exit code 1 if issues found)
scry scan . --strict

#output as compact
scry scan . --output compact

# Output as JSON
scry scan . --output json

# Show explanations and fixes
scry scan . --explain --fix

See commands.md for a comprehensive list of all available commands and options.

Command Reference

See commands.md for a comprehensive list of all available commands and options, including:

• Single file and directory scans
• All output formats (table, json, markdown, compact)
• Severity filtering
• Strict mode
• Explanations and fixes
• Configuration file usage
• And much more!

What scry Detects

Security Rules

1. Hardcoded Secrets - API keys, tokens, passwords, AWS credentials
2. JWT in Client Storage - JWT tokens in localStorage/sessionStorage
3. Insecure Cookies - Missing httpOnly, secure, sameSite flags
4. eval() Usage - Dangerous code execution
5. CORS Misconfiguration - Overly permissive CORS settings
6. .env Exposure - Environment files in version control or public directories
7. Weak Cryptography - MD5, SHA1, DES, unsalted hashing, low iterations
8. Password Security - Plaintext storage, weak validation, insecure transmission

Example Output

Table format (default):

Severity | Rule               | File          | Line | Message
---------|--------------------| --------------|------|---------------------
HIGH     | hardcoded-secrets  | src/config.ts | 14   | Hardcoded API key
HIGH     | jwt-storage        | src/auth.ts   | 28   | JWT in localStorage
MEDIUM   | cors-config        | src/server.ts | 45   | Permissive CORS

Summary:
Files scanned: 847
Duration: 2.3s

Results:
HIGH:    3
MEDIUM:  6
LOW:     3
Total:   12

Installation

For End Users

# Install globally
npm install -g @johsam-f/scry

# Or use with npx (no installation required)
npx @johsam-f/scry scan .

For Development

# Clone and run from source
git clone https://github.com/johsam-f/scry.git
cd scry
bun install
bun run dev scan .

See DEVELOPMENT.md for development commands and testing instructions.

Usage

Basic Scanning

# Current directory
scry scan

# Specific path
scry scan ./src

Output Formats

# Table (default) - Clean summary with findings table
scry scan . --output table

# Add detailed explanations for each finding
scry scan . --explain

# Add suggested fixes for each finding
scry scan . --fix

# Show both explanations and fixes
scry scan . --explain --fix

# Compact - Minimal, file-grouped output
scry scan . --output compact

# JSON - For CI/CD integration
scry scan . --output json > results.json

# Markdown - For reports and documentation
scry scan . --output markdown > SECURITY.md

Supported formats: table (default), compact, json, markdown

See Output Formats Guide for detailed examples and use cases.

Filter by Severity

# Only show high severity issues
scry scan . --min-severity high

# Show medium and high severity issues
scry scan . --min-severity medium

# Show all issues (default)
scry scan . --min-severity low

Severity levels: high (critical), medium (significant), low (minor)

Strict Mode

# Fail with exit code 1 if any issues found
scry scan . --strict

Configuration

Create .scryrc.json in your project root:

{
  "rules": {
    "hardcoded-secrets": "error",
    "eval-usage": "error",
    "jwt-storage": "error",
    "cookie-security": "warn",
    "cors-config": "warn",
    "env-exposure": "error",
    "weak-crypto": "error",
    "password-security": "error"
  },
  "ignore": ["**/tests/**", "**/fixtures/**", "**/mocks/**"],
  "extensions": [".js", ".ts", ".jsx", ".tsx"],
  "strict": false,
  "minSeverity": "low",
  "showFixes": true,
  "showExplanations": true
}

Why scry?

Modern developers ship code fast, often faster than they can think about security.

While powerful tools like linters exist, many:

• Focus on rules without context
• Assume prior security knowledge
• Overwhelm with noise

scry is different:

• Opinionated, not exhaustive
• Educational, not noisy
• Focused on real-world security footguns

Documentation

For more detailed information, see:

• Installation Guide - Setup and configuration
• Security Rules Guide - Detailed rule documentation
• Configuration Reference - Configuration file options

Contributing

Contributions welcome! Areas to help:

• [ ] Add more security rules
• [ ] Framework-specific rules (React, Vue, Angular)
• [ ] VS Code extension
• [ ] CI/CD integrations
• [ ] Better regex patterns
• [ ] Documentation improvements

License

MIT

Built for the GitHub Copilot CLI Challenge

This project was created for the GitHub Copilot CLI Challenge and demonstrates how GitHub Copilot CLI can accelerate development.

Key Achievement Highlights:

• 8 security rules implemented with Copilot-assisted pattern generation
• Comprehensive test coverage with AI-generated test cases
• Multiple output formatters for different workflows
• Full configuration file support for flexible deployments

For detailed information on how Copilot CLI enhanced the development process, see Copilot Impact Documentation.

Technology Stack

• Bun - Fast JavaScript runtime
• TypeScript - Type-safe development
• Commander.js - CLI framework
• Chalk - Terminal colors
• Glob - File pattern matching

Support

For questions or issues, please check the documentation or create an issue on GitHub.