guardscan

v1.0.5

Published

2 months ago

GuardScan - Privacy-first AI Code Review CLI with comprehensive security scanning

0High
0Medium
0Low

guardscan code-review security-scanner sast vulnerability-scanner ai-code-review static-analysis code-analysis openai claude gemini ollama privacy-first open-source

🛡️ 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:

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

📊 Code Quality & Analysis (FREE, Offline)

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

🧪 Testing & Performance (FREE, Offline)

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

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

9 Advanced AI-Powered Features:

Code Explainer (guardscan explain) - Understand complex code
Code Review (guardscan review) - Comprehensive AI code review
Commit Generator (guardscan commit) - Generate commit messages
Docs Generator (guardscan docs) - Auto-generate documentation
Test Generator (guardscan test-gen) - Generate unit tests
Refactoring Suggestions (guardscan refactor) - Improve code quality
Threat Modeling (guardscan threat-model) - Security architecture analysis
Migration Assistant (guardscan migrate) - Framework/language migrations
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

| Command | Description | | ------------------ | ------------------------------------- | | guardscan init | Initialize config, generate client_id | | guardscan config | Configure AI provider & settings | | guardscan status | Show configuration and repo info | | guardscan reset | Clear local cache & config |

Security & Analysis Commands

| Command | Description | | -------------------- | ----------------------------------------- | | guardscan security | Run comprehensive security scan (offline) | | guardscan scan | Quick security scan | | guardscan run | AI-enhanced full code review (BYOK) |

Testing & Quality Commands

| Command | Description | | -------------------- | ---------------------------------- | | guardscan test | Run tests & code quality analysis | | guardscan perf | Performance testing & load testing | | guardscan mutation | Mutation testing for test quality |

Utility Commands

| Command | Description | | ----------------- | ----------------------------------- | | guardscan sbom | Generate Software Bill of Materials | | guardscan rules | Custom YAML-based rule engine |

AI-Powered Commands (BYOK)

| Command | Description | | --------------------------- | ------------------------------------ | | guardscan explain <file> | Explain how code works | | guardscan review <file> | Comprehensive AI code review | | guardscan commit | Generate commit messages | | guardscan docs <file> | Auto-generate documentation | | guardscan test-gen <file> | Generate unit tests | | guardscan refactor <file> | Get refactoring suggestions | | guardscan threat-model | Security architecture analysis | | guardscan migrate | Framework/language migration help | | guardscan chat | Interactive Q&A about codebase (RAG) |

🔒 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:

GuardScan analyzes your code locally
Sends anonymized context to your AI provider (using your API key)
AI provides insights and suggestions
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

❓ 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: [email protected] (coming soon)

Made with ❤️ by developers, for developers

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature