100% Gratuito e Open Source • Scansione di sicurezza privacy-first e CLI di revisione del codice con IA
# 🛡️ GuardScan
**100% Gratuito e Open Source** • CLI Privacy-First per la Scansione della Sicurezza e la Revisione del Codice AI
```
____ _ _ _ ____ ____ ____ ____ _ _ _ ____ _ ___
/ ___| | | | / \ | _ \| _ \ / ___| / ___| / \ | \ | | / ___| | |_ _|
| | _| | | |/ _ \ | |_) | | | | \___ \| | / _ \ | \| | _____ | | | | | |
| |_| | |_| / ___ \| _ <| |_| | ___) | |___ / ___ \| |\ | |_____| | |___| |___ | |
\____|\___/_/ \_\_| \_\____/ |____/ \____/_/ \_\_| \_| \____|_____|___|
Privacy-First AI Code Review & Security Scanning
```
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
---
## 🎉 Completamente Gratuito - Nessun Abbonamento, Nessun Limite
GuardScan è **100% gratuito e open source**! Nessun sistema a crediti, nessun paywall, nessun abbonamento.
### Cosa Ottieni (Tutto GRATIS)
- ✅ **Analisi statica illimitata** - 9 scanner di sicurezza + strumenti di qualità del codice
- ✅ **Revisione del codice potenziata dall'AI** - Porta la tua API key (OpenAI, Claude, Gemini, Ollama)
- ✅ **Funziona completamente offline** - Nessuna connessione Internet richiesta per l'analisi statica
- ✅ **Privacy-first** - Non carica mai il tuo codice sorgente
- ✅ **Nessun limite di utilizzo** - Scansiona LOC illimitate, repository illimitati
---
## 🚀 Avvio Rapido
```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
```
### 🐳 Docker / Alpine Linux
Per gli ambienti Docker, in particolare Alpine Linux:
```bash
# Install dependencies first
apk add --no-cache python3 make g++ pkgconfig cairo-dev pango-dev \
libjpeg-turbo-dev giflib-dev pixman-dev freetype-dev build-base git
# Install GuardScan
npm install -g guardscan
# Set home directory (important for Docker)
export GUARDSCAN_HOME=/app/.guardscan
# Initialize
guardscan init
```
**Documentazione:**
- 📖 [Guida Docker Completa](https://github.com/ntanwir10/guardscan/blob/main/docs/DOCKER_GUIDE.md) - Guida completa per Linux, macOS e Windows
- 🐧 [Riferimento Rapido Docker & Alpine](https://github.com/ntanwir10/guardscan/blob/main/docs/DOCKER_ALPINE_GUIDE.md) - Riferimento rapido specifico per Alpine Linux
---
## 📋 Funzionalità Principali
### 🔒 Scansione della Sicurezza (GRATIS, Offline)
GuardScan include **scanner di sicurezza completi**:
1. **Rilevamento Segreti** - Trova API key, password e token hardcoded (20+ pattern)
2. **Vulnerabilità delle Dipendenze** - Scansiona le dipendenze npm, pip, Maven, Cargo
3. **OWASP Top 10** - SQL injection, XSS, configurazioni non sicure, CSRF, XXE
4. **Sicurezza Docker** - Scansione di Dockerfile e container
5. **Infrastructure as Code** - Sicurezza per Terraform, CloudFormation e Kubernetes
6. **Sicurezza API** - Analisi degli endpoint REST e GraphQL
### 📊 Qualità del Codice e Analisi (GRATIS, Offline)
7. **Metriche del Codice** - Complessità ciclomatica, metriche di Halstead, indice di manutenibilità
8. **Code Smells** - 30+ anti-pattern (god classes, metodi lunghi, magic numbers)
9. **Conformità delle Licenze** - Controlla le licenze delle dipendenze (MIT, GPL, Apache, ecc.)
10. **Verifiche di Conformità** - Scansione di conformità GDPR, HIPAA, PCI-DSS
11. **Integrazione Linter** - ESLint, Pylint, RuboCop, ecc.
12. **Contatore LOC** - Conteggio delle righe sensibile al linguaggio (20+ linguaggi)
### 🧪 Test e Prestazioni (GRATIS, Offline)
13. **Esecutore di Test** - Esegue e analizza i test Jest, pytest, JUnit
14. **Mutation Testing** - Valida l'efficacia della suite di test (richiede Stryker - opzionale)
15. **Test delle Prestazioni** - Load testing e benchmarking (richiede k6 - opzionale)
16. **Generazione SBOM** - Software Bill of Materials (CycloneDX, SPDX)
**Nota**: I test delle prestazioni e il mutation testing richiedono strumenti esterni opzionali.
### 🤖 Funzionalità Potenziate dall'AI (BYOK - Porta la Tua Chiave)
**9 Funzionalità Avanzate Basate sull'AI:**
1. **Spiegatore di Codice** (`guardscan explain`) - Comprendi il codice complesso
2. **Revisione del Codice** (`guardscan review`) - Revisione completa del codice con AI
3. **Generatore di Commit** (`guardscan commit`) - Genera messaggi di commit
4. **Generatore di Documentazione** (`guardscan docs`) - Genera automaticamente la documentazione
5. **Generatore di Test** (`guardscan test-gen`) - Genera test unitari
6. **Suggerimenti di Refactoring** (`guardscan refactor`) - Migliora la qualità del codice
7. **Modellazione delle Minacce** (`guardscan threat-model`) - Analisi dell'architettura di sicurezza
8. **Assistente di Migrazione** (`guardscan migrate`) - Migrazioni di framework/linguaggi
9. **Chat Interattiva** (`guardscan chat`) - Domande e risposte sul codebase basate su RAG
### 🌍 Supporto Multilingue
**Parser AST per 7+ Linguaggi:**
- TypeScript/JavaScript
- Python
- Java
- Go
- Rust
- Ruby
- PHP
- C#
### 🔌 Integrazioni con i Provider AI
Configura qualsiasi provider AI preferisci:
- **OpenAI** (GPT-4, GPT-4 Turbo, GPT-3.5)
- **Anthropic Claude** (Claude 3 Opus, Sonnet, Haiku)
- **Google Gemini** (Gemini Pro)
- **Ollama** (Locale, focalizzato sulla privacy - llama2, codellama, mistral)
- **LM Studio** (Modelli locali)
- **OpenRouter** (Accesso a più modelli)
**Paghi direttamente il provider AI** - GuardScan non addebita nulla!
---
## 🛠️ Comandi
Tutti i comandi sono **100% GRATUITI** senza limiti!
### Comandi di Configurazione
| Comando | Descrizione |
| ------------------- | ----------------------------------------------- |
| `guardscan init` | Inizializza la configurazione e genera client_id |
| `guardscan config` | Configura il provider AI e le impostazioni |
| `guardscan status` | Mostra la configurazione e le informazioni del repository |
| `guardscan reset` | Cancella la cache locale e la configurazione |
### Comandi di Sicurezza e Analisi
| Comando | Descrizione |
| -------------------- | ---------------------------------------------------- |
| `guardscan security` | Esegue una scansione di sicurezza completa (offline) |
| `guardscan scan` | Scansione di sicurezza rapida |
| `guardscan run` | Revisione completa del codice potenziata dall'AI (BYOK) |
### Comandi di Test e Qualità
| Comando | Descrizione |
| -------------------- | ------------------------------------------------------------------ |
| `guardscan test` | Esegue i test e l'analisi della qualità del codice |
| `guardscan perf` | Test delle prestazioni e load testing (richiede k6 - opzionale) |
| `guardscan mutation` | Mutation testing per la qualità dei test (richiede Stryker - opzionale) |
**Nota**: I comandi `perf` e `mutation` richiedono strumenti esterni opzionali. Consulta la [Guida agli Strumenti di Test](https://github.com/ntanwir10/guardscan/blob/main/cli/docs/TESTING_TOOLS.md) per i dettagli di installazione e utilizzo.
### Comandi di Utilità
| Comando | Descrizione |
| ------------------ | ---------------------------------------------- |
| `guardscan sbom` | Genera la Software Bill of Materials |
| `guardscan rules` | Motore di regole personalizzato basato su YAML |
### Comandi Basati sull'AI (BYOK)
| Comando | Descrizione |
| --------------------------- | -------------------------------------------------- |
| `guardscan explain <file>` | Spiega come funziona il codice |
| `guardscan review <file>` | Revisione completa del codice con AI |
| `guardscan commit` | Genera messaggi di commit |
| `guardscan docs <file>` | Genera automaticamente la documentazione |
| `guardscan test-gen <file>` | Genera test unitari |
| `guardscan refactor <file>` | Ottieni suggerimenti di refactoring |
| `guardscan threat-model` | Analisi dell'architettura di sicurezza |
| `guardscan migrate` | Assistenza per la migrazione di framework/linguaggi |
| `guardscan chat` | Domande e risposte interattive sul codebase (RAG) |
---
## 🔒 Garanzie sulla Privacy
Prendiamo la privacy molto sul serio:
### ❌ Mai Salvati o Trasmessi
- Il tuo codice sorgente
- Percorsi o nomi dei file
- Frammenti di codice
- API key o segreti
- Informazioni proprietarie
### ✅ Telemetria Opzionale (Anonimizzata)
- Utilizzo dei comandi (ad es., comando "security" eseguito)
- Durata dell'esecuzione
- Conteggio LOC (solo numero aggregato)
- Modello AI utilizzato (ad es., "gpt-4")
**La telemetria è:**
- Opzionale (facilmente disattivabile: `guardscan config --telemetry=false`)
- Completamente anonimizzata
- Utilizzata solo per migliorare GuardScan
- Mai venduta o condivisa
---
## 🎯 Come Funziona
### Analisi Statica (Offline, Senza AI)
```bash
guardscan security
```
Esegue **9 scanner di sicurezza** localmente:
- Scansiona il tuo codebase
- Genera un report in markdown
- **100% offline** - nessuna connessione Internet necessaria
- **100% gratuito** - nessun limite
### Revisione Potenziata dall'AI (La Tua API Key)
```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
```
Come funziona:
1. GuardScan analizza il tuo codice localmente
2. Invia il contesto anonimizzato al **tuo provider AI** (usando la **tua API key**)
3. L'AI fornisce approfondimenti e suggerimenti
4. Il report viene salvato localmente
**Paghi direttamente il tuo provider AI** - GuardScan è gratuito!
---
## 💰 Prezzi
### GuardScan: **$0** (100% Gratuito)
Nessun sistema a crediti. Nessun abbonamento. Nessun paywall.
### Provider AI (Se Usi le Funzionalità AI)
**Paghi loro direttamente (non GuardScan):**
- **OpenAI GPT-4**: ~$0,01-0,03 per 1K token
- **Claude Sonnet**: ~$0,003 per 1K token
- **Gemini Pro**: Livello gratuito disponibile
- **Ollama**: 100% gratuito (funziona localmente)
**Esempio di costi per un codebase di 10K LOC:**
- Solo analisi statica: **$0**
- Con OpenAI GPT-4: **~$2-5** (pagato a OpenAI)
- Con Ollama (locale): **$0**
---
## 🏗️ Architettura
GuardScan adotta un'**architettura client-side privacy-first** in cui tutta l'analisi del codice avviene localmente.
```
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└──────────────────────────┘ └──────────────────────────┘
```
### Stack Tecnologico
**CLI (34.213 LOC):**
- Linguaggio: TypeScript 5.3+ (strict mode)
- Runtime: Node.js 18+
- Framework: Commander.js
- Testing: Jest (70%+ di copertura)
- Build: TypeScript Compiler (tsc)
**Servizio di monitoraggio (repository separato, opzionale):**
- Si trova in [ntanwir10/GuardScan-Monitoring](https://github.com/ntanwir10/GuardScan-Monitoring)
- Piattaforma: Cloudflare Workers + Supabase PostgreSQL
- Scopo: telemetria anonima e analisi di errori/utilizzo
- La CLI comunica con esso solo via HTTP; sovrascrivi l'URL con `GUARDSCAN_API_URL`
---
## 📦 Installazione
### Tramite NPM (Consigliato)
```bash
npm install -g guardscan
```
### Tramite Sorgente
```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
```
---
## 🤝 Contributi
GuardScan è **open source** e accogliamo volentieri i contributi!
- **Segnala bug**: [GitHub Issues](https://github.com/ntanwir10/GuardScan/issues)
- **Richiedi funzionalità**: [GitHub Issues](https://github.com/ntanwir10/GuardScan/issues)
- **Invia PR**: Consulta [CONTRIBUTING.md](https://github.com/ntanwir10/guardscan/blob/main/docs/CONTRIBUTING.md)
---
## 📚 Documentazione
- [Guida all'Installazione](https://github.com/ntanwir10/guardscan/blob/main/docs/GETTING_STARTED.md)
- [Guida alla Configurazione](https://github.com/ntanwir10/guardscan/blob/main/docs/CONFIGURATION.md)
- [Guida alla Chat](https://github.com/ntanwir10/guardscan/blob/main/docs/CHAT_GUIDE.md)
- [Documentazione API](https://github.com/ntanwir10/guardscan/blob/main/docs/API.md)
- [Scanner di Sicurezza](https://github.com/ntanwir10/guardscan/blob/main/docs/SECURITY_SCANNERS.md)
- [Linee Guida per i Contributi](https://github.com/ntanwir10/guardscan/blob/main/docs/CONTRIBUTING.md)
---
## ❓ FAQ
**D: GuardScan è davvero gratuito?**
R: Sì! 100% gratuito, nessun sistema a crediti, nessun abbonamento, nessun limite.
**D: Devo creare un account?**
R: No! Basta `npm install -g guardscan` ed eseguire `guardscan init`.
**D: Mi serve una API key per l'AI?**
R: Solo se vuoi la revisione potenziata dall'AI. L'analisi statica (9 scanner di sicurezza) funziona senza alcuna API key.
**D: Quale provider AI dovrei usare?**
R: La scelta è tua! OpenAI (potente), Claude (equilibrato), Gemini (economico), Ollama (gratuito, locale).
**D: GuardScan carica il mio codice?**
R: **Mai**. GuardScan carica solo metadati anonimizzati per la telemetria opzionale.
**D: Posso disattivare la telemetria?**
R: Sì! Esegui `guardscan config --telemetry=false` oppure imposta `telemetryEnabled: false` in `~/.guardscan/config.yml`.
**D: Come posso supportare questo progetto?**
R: Metti una stella al repository su GitHub, contribuisci con codice, segnala bug oppure sponsorizza il progetto!
---
## 📝 Licenza
Licenza MIT - consulta [LICENSE](https://github.com/ntanwir10/guardscan/blob/main/LICENSE)
---
## 🙏 Riconoscimenti
GuardScan è costruito con questi fantastici strumenti open source:
- [Commander.js](https://github.com/tj/commander.js) - framework CLI
- [Chalk](https://github.com/chalk/chalk) - stile del terminale
- [Axios](https://github.com/axios/axios) - client HTTP
- [Cloudflare Workers](https://workers.cloudflare.com/) - backend serverless
- [Supabase](https://supabase.com/) - alternativa open source a Firebase
---
## 📞 Supporto
- **Issue**: [GitHub Issues](https://github.com/ntanwir10/GuardScan/issues)
- **Discussioni**: [GitHub Discussions](https://github.com/ntanwir10/GuardScan/discussions)
- **Email**: <[email protected]> (presto disponibile)
---
<div align="center">
**Realizzato con ❤️ da sviluppatori, per sviluppatori**
[⭐ Metti una stella su GitHub](https://github.com/ntanwir10/GuardScan) • [🐛 Segnala un Bug](https://github.com/ntanwir10/GuardScan/issues) • [💡 Richiedi una Funzionalità](https://github.com/ntanwir10/GuardScan/issues)
</div>