🛡️ GuardScan

100% Free & Open Source • Privacy-First Security Scanning and AI Code Review CLI

  ____ _   _   _    ____  ____    ____   ____    _    _   _            ____ _     ___ 
 / ___| | | | / \  |  _ \|  _ \  / ___| / ___|  / \  | \ | |          / ___| |   |_ _|
| |  _| | | |/ _ \ | |_) | | | | \___ \| |     / _ \ |  \| |  _____  | |   | |    | |
| |_| | |_| / ___ \|  _ <| |_| |  ___) | |___ / ___ \| |\  | |_____| | |___| |___ | | 
 \____|\___/_/   \_\_| \_\____/  |____/ \____/_/   \_\_| \_|          \____|_____|___|

 Privacy-First AI Code Review & Security Scanning

🎉 Completely Free - No Subscriptions, No Limits

GuardScan is 100% free and open source! No credit system, no paywalls, no subscriptions.

What You Get (All FREE)

• ✅ Unlimited static analysis - 9 security scanners + code quality tools
• ✅ AI-enhanced code review - Bring your own API key (OpenAI, Claude, Gemini, Ollama)
• ✅ Works fully offline - No internet required for static analysis
• ✅ Privacy-first - Never uploads your source code
• ✅ No usage limits - Scan unlimited LOC, unlimited repositories

🚀 Quick Start

# Install globally via npm
npm install -g guardscan

# Initialize GuardScan
guardscan init

# Run comprehensive security scan (100% FREE, offline)
guardscan security

# Configure AI provider for enhanced review (optional, BYOK)
guardscan config

# Run AI-enhanced code review
guardscan run

# Check status
guardscan status

📋 Core Features

🔒 Security Scanning (FREE, Offline)

GuardScan includes comprehensive security scanners:

1. Secrets Detection - Find hardcoded API keys, passwords, tokens (20+ patterns)
2. Dependency Vulnerabilities - Scan npm, pip, Maven, Cargo dependencies
3. OWASP Top 10 - SQL injection, XSS, insecure configs, CSRF, XXE
4. Docker Security - Dockerfile and container scanning
5. Infrastructure as Code - Terraform, CloudFormation, Kubernetes security
6. API Security - REST and GraphQL endpoint analysis

📊 Code Quality & Analysis (FREE, Offline)

7. Code Metrics - Cyclomatic complexity, Halstead metrics, maintainability index
8. Code Smells - 30+ anti-patterns (god classes, long methods, magic numbers)
9. License Compliance - Check dependency licenses (MIT, GPL, Apache, etc.)
10. Compliance Checks - GDPR, HIPAA, PCI-DSS compliance scanning
11. Linter Integration - ESLint, Pylint, RuboCop, etc.
12. LOC Counter - Language-aware line counting (20+ languages)

🧪 Testing & Performance (FREE, Offline)

13. Test Runner - Execute and analyze Jest, pytest, JUnit tests
14. Mutation Testing - Validate test suite effectiveness
15. Performance Testing - Load testing and benchmarking
16. SBOM Generation - Software Bill of Materials (CycloneDX, SPDX)

🤖 AI-Enhanced Features (BYOK - Bring Your Own Key)

9 Advanced AI-Powered Features:

1. Code Explainer (guardscan explain) - Understand complex code
2. Code Review (guardscan review) - Comprehensive AI code review
3. Commit Generator (guardscan commit) - Generate commit messages
4. Docs Generator (guardscan docs) - Auto-generate documentation
5. Test Generator (guardscan test-gen) - Generate unit tests
6. Refactoring Suggestions (guardscan refactor) - Improve code quality
7. Threat Modeling (guardscan threat-model) - Security architecture analysis
8. Migration Assistant (guardscan migrate) - Framework/language migrations
9. Interactive Chat (guardscan chat) - RAG-powered codebase Q&A

🌍 Multi-Language Support

AST Parsers for 7+ Languages:

• TypeScript/JavaScript
• Python
• Java
• Go
• Rust
• Ruby
• PHP
• C#

🔌 AI Provider Integrations

Configure any AI provider you prefer:

• OpenAI (GPT-4, GPT-4 Turbo, GPT-3.5)
• Anthropic Claude (Claude 3 Opus, Sonnet, Haiku)
• Google Gemini (Gemini Pro)
• Ollama (Local, privacy-focused - llama2, codellama, mistral)
• LM Studio (Local models)
• OpenRouter (Access to multiple models)

You pay the AI provider directly - GuardScan charges nothing!

🛠️ Commands

All commands are 100% FREE with no limits!

Configuration Commands

Security & Analysis Commands

Testing & Quality Commands

Utility Commands

AI-Powered Commands (BYOK)

🔒 Privacy Guarantees

We take privacy seriously:

❌ Never Stored or Transmitted

• Your source code
• File paths or file names
• Code snippets
• API keys or secrets
• Proprietary information

✅ Optional Telemetry (Anonymized)

• Command usage (e.g., "security" command ran)
• Execution duration
• LOC count (aggregate number only)
• AI model used (e.g., "gpt-4")

Telemetry is:

• Optional (easily disabled: guardscan config --telemetry=false)
• Completely anonymized
• Only used to improve GuardScan
• Never sold or shared

🎯 How It Works

Static Analysis (Offline, No AI)

guardscan security

Runs 9 security scanners locally:

• Scans your codebase
• Generates markdown report
• 100% offline - no internet needed
• 100% free - no limits

AI-Enhanced Review (Your API Key)

# Step 1: Configure your AI provider (one-time)
guardscan config
# Choose provider: OpenAI, Claude, Gemini, Ollama
# Enter your API key

# Step 2: Run AI review
guardscan run

How it works:

1. GuardScan analyzes your code locally
2. Sends anonymized context to your AI provider (using your API key)
3. AI provides insights and suggestions
4. Report saved locally

You pay your AI provider directly - GuardScan is free!

💰 Pricing

GuardScan: $0 (100% Free)

No credit system. No subscriptions. No paywalls.

AI Providers (If You Use AI Features)

You pay them directly (not GuardScan):

• OpenAI GPT-4: ~$0.01-0.03 per 1K tokens
• Claude Sonnet: ~$0.003 per 1K tokens
• Gemini Pro: Free tier available
• Ollama: 100% free (runs locally)

Example costs for 10K LOC codebase:

• Static analysis only: $0
• With OpenAI GPT-4: ~$2-5 (paid to OpenAI)
• With Ollama (local): $0

🏗️ Architecture

GuardScan follows a privacy-first, client-side architecture where all code analysis happens locally.

┌─────────────────────────────────────────────────────────────┐
│                    USER'S MACHINE                            │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         GuardScan CLI (Node.js/TypeScript)          │   │
│  │                                                      │   │
│  │  • 21 Commands (security, run, test, explain...)    │   │
│  │  • 30 Core Modules (scanners, parsers, metrics)     │   │
│  │  • 9 AI Features (explain, review, test-gen, etc.)  │   │
│  │  • 7 Language Parsers (Python, Java, Go, Rust...)   │   │
│  │  • 6 AI Provider Integrations                       │   │
│  │                                                      │   │
│  │  Config: ~/.guardscan/config.yml                   │   │
│  │  Cache: ~/.guardscan/cache/                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                           │                                  │
│                           │ Optional telemetry only          │
│                           ▼                                  │
└───────────────────────────────────────────────────────────────┘
                            │
                ┌───────────┴──────────┐
                │                      │
                ▼                      ▼
┌──────────────────────────┐  ┌──────────────────────────┐
│  User's AI Provider      │  │  GuardScan Backend       │
│  (User pays directly)    │  │  (Optional telemetry)    │
│                          │  │                          │
│  • OpenAI (GPT-4)        │  │  Cloudflare Workers      │
│  • Anthropic (Claude)    │  │  + Supabase              │
│  • Google (Gemini)       │  │                          │
│  • Ollama (Local)        │  │  • Health checks         │
│                          │  │  • Anonymous telemetry   │
│  User's API Key →        │  │  • NO source code        │
│  User's billing →        │  │  • NO credit validation  │
└──────────────────────────┘  └──────────────────────────┘

Technology Stack

CLI (34,213 LOC):

• Language: TypeScript 5.3+ (strict mode)
• Runtime: Node.js 18+
• Framework: Commander.js
• Testing: Jest (70%+ coverage)
• Build: TypeScript Compiler (tsc)

Backend (913 LOC - Optional):

• Platform: Cloudflare Workers (serverless)
• Database: Supabase PostgreSQL (optional)
• Purpose: Anonymous telemetry only
• Cost: $0-5/month (Cloudflare free tier)

📦 Installation

Via NPM (Recommended)

npm install -g guardscan

This will automatically install all required runtime dependencies, including TypeScript which is needed for AST parsing.

Via Source

# Clone repository
git clone https://github.com/ntanwir10/GuardScan.git
cd GuardScan/cli

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

# Verify
guardscan --help

Runtime Dependencies

GuardScan requires the following runtime dependencies (automatically installed with npm):

• TypeScript (typescript) - Required for AST parsing of TypeScript/JavaScript files

  • Automatically included when installing via npm install -g guardscan

  • If you encounter "Cannot find module 'typescript'" errors, ensure it's installed:

    npm install typescript

All other dependencies are automatically managed by npm during installation.

🤝 Contributing

GuardScan is open source and we welcome contributions!

• Report bugs: GitHub Issues
• Request features: GitHub Issues
• Submit PRs: See CONTRIBUTING.md

📚 Documentation

• Installation Guide
• Configuration Guide
• API Documentation
• Security Scanners
• Contributing Guidelines

❓ FAQ

Q: Is GuardScan really free? A: Yes! 100% free, no credit system, no subscriptions, no limits.

Q: Do I need to create an account? A: No! Just npm install -g guardscan and run guardscan init.

Q: Do I need an AI API key? A: Only if you want AI-enhanced review. Static analysis (9 security scanners) works without any API key.

Q: Which AI provider should I use? A: Your choice! OpenAI (powerful), Claude (balanced), Gemini (affordable), Ollama (free, local).

Q: Does GuardScan upload my code? A: Never. GuardScan only uploads anonymized metadata for optional telemetry.

Q: Can I disable telemetry? A: Yes! Run guardscan config --telemetry=false or set telemetryEnabled: false in ~/.guardscan/config.yml.

Q: How do I support this project? A: Star the repo on GitHub, contribute code, report bugs, or sponsor the project!

📝 License

MIT License - see LICENSE

🙏 Acknowledgments

GuardScan is built with these amazing open-source tools:

• Commander.js - CLI framework
• Chalk - Terminal styling
• Axios - HTTP client
• Cloudflare Workers - Serverless backend
• Supabase - Open-source Firebase alternative

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@guardscan.com (coming soon)