🛡️ GuardScan

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

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

Privacy-First AI Code Review & Security Scanning
`

![License: MIT](https://opensource.org/licenses/MIT)
![Node.js Version](https://nodejs.org)

---

🎉 Completely Free - No Subscriptions, No Limits

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

$3

- ✅ 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

`bash


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

$3

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

$3

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)

$3

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)

$3

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

$3

AST Parsers for 7+ Languages:

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

$3

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!

$3

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

$3

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

$3

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

$3

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

$3

| Command | Description |
| --------------------------- | ------------------------------------ |
| guardscan explain | Explain how code works |
| guardscan review | Comprehensive AI code review |
| guardscan commit | Generate commit messages |
| guardscan docs | Auto-generate documentation |
| guardscan test-gen | Generate unit tests |
| guardscan refactor | 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:

$3

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

$3

- 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

$3

`bash
guardscan security
`

Runs 9 security scanners locally:

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

$3

`bash


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

$3

No credit system. No subscriptions. No paywalls.

$3

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 │
└──────────────────────────┘ └──────────────────────────┘
`

$3

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

$3

`bash
npm install -g guardscan
`

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

$3

`bash


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
`

$3

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:

`bash
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: (coming soon)

---