🛡️ Guardian - Secrets Scanner for VS Code

SECURITY FIRST · PRIVACY PROTECTED · ZERO TRUST

Advanced security extension that detects passwords, API keys, tokens, and sensitive data in code, configuration, and text files with entropy analysis and custom pattern detection.

🔒 Our Core Principles

SECURITY FIRST

Guardian was built from the ground up with a security-first philosophy. We don't just detect secrets—we prevent them from ever reaching your repository through multiple layers of defense:

🛡️ Multi-Layer Defense: Real-time scanning → IDE diagnostics → Pre-commit blocking (with hook installed)
🚨 Zero-Tolerance for Critical Secrets (when pre-commit hook enabled): AWS keys, private keys, and database passwords automatically block commits
⚡ Shift-Left Security: Catch secrets before they're committed, not after they're exposed
🎯 Proactive, Not Reactive: Built-in prevention mechanisms, not just detection

PRIVACY BY DESIGN

Your code and data privacy is non-negotiable:

🔐 100% Local Processing: All scanning happens on your machine—nothing is ever sent to external servers
🚫 Zero Telemetry: We don't collect, transmit, or store any of your code or findings
🎭 Secret Masking: All detected secrets are automatically masked in UI and logs (e.g., AKIA****MPLE)
📜 Open Source: Complete transparency—audit our code yourself
🏠 Your Data Stays Yours: No cloud dependencies, no API calls, no data leakage

RESPONSIBILITY & COMPLIANCE

We take our responsibility seriously:

✅ Compliance Support: Helps support SOC 2, PCI DSS, GDPR, and HIPAA requirements (see Compliance Support section for details)
📊 Audit Trail: Detailed reports and logs for security audits
👥 Team Protection: Shared security standards across your organization
📚 Security Education: Comprehensive documentation and best practices

🚀 Key Features

What Makes Guardian Different?

Entropy Analysis - Uses Shannon entropy calculation to detect high-randomness strings that traditional pattern matching might miss
Multi-Language Support - Scans code files (.js, .ts, .py, .go, etc.), config files (.env, .yaml, etc.), and text files
Context Preservation - Includes surrounding code context with each finding for manual review
Real-Time Scanning - Automatically scans files on save (enabled by default); on-open scanning available (disabled by default)
Comprehensive Pattern Library - Detects 36 types of secrets including:
- Cloud credentials (AWS, Azure, GCP)
- API keys and tokens
- Database connection strings
- Private cryptographic keys
- Payment service credentials
- Source control tokens
- And many more...
Custom Pattern Support - Add your own regex patterns for organization-specific secrets
False Positive Suppression - Mark findings as false positives with justification; manage suppressions easily
Security Dashboard - Visual dashboard showing security overview and findings summary
Export to Markdown or CSV - Export reports for external analysis and compliance
Severity-Based Filtering - Focus on critical issues first
Git Commit Blocking - Pre-commit hooks (when installed) to prevent secrets from being committed

📦 Installation

From VSIX

Download the .vsix file
Open VS Code
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Type "Install from VSIX"
Select the downloaded file

From Source

git clone https://github.com/Maneesh-Relanto/VSCE-Guardian-Secrets-Scanner.git
cd VSCE-Guardian-Secrets-Scanner
npm install
npm run compile
# Press F5 in VS Code to debug

🎯 Usage

Commands

Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) and search for:

Guardian: Scan Entire Workspace - Scan all files in your workspace
Guardian: Scan Current File - Scan only the active file
Guardian: Show Security Dashboard - Open the visual security dashboard
Guardian: Clear All Findings - Clear all detected findings
Guardian: Export Security Report - Export findings as Markdown or CSV
Guardian: Add Custom Pattern - Add organization-specific detection patterns
Guardian: Install Pre-commit Hook - Block commits containing secrets
Guardian: Scan Staged Files - Check files before committing
Guardian: View Suppression Report - See audit of all suppressions
Guardian: Open Settings - Configure Guardian options

Activity Bar

Click the Guardian Shield icon in the Activity Bar to see:

Security findings grouped by severity
Statistics and overview
Quick navigation to issues

Status Bar

The bottom status bar shows real-time security status:

🛡️ Guardian: Clean - No issues detected
⚠️ Guardian: X Critical - Critical issues found
ℹ️ Guardian: X - Lower severity issues

⚙️ Configuration

Guardian provides an intuitive settings UI for easy configuration.

Opening Settings

Option 1: Via Command Palette

Ctrl+Shift+P (or Cmd+Shift+P on Mac)
→ "Guardian: Show Settings"

Option 2: Via Dashboard

Click the Settings button on the Guardian Security Dashboard

Option 3: Via Standard Settings

Ctrl+, (or Cmd+, on Mac)
→ Search for "Guardian"

Settings Categories

🔍 Detection Settings

Entropy Analysis - Detect secrets by analyzing character randomness (enabled by default)
Entropy Threshold - Configure sensitivity (3.0 = catch more, 6.0 = strict, default 4.5)
Minimum Severity Level - Only report Critical, High, Medium, or Low severity findings

📁 Scanning Settings

Exclude Patterns - Folders to skip (node_modules, dist, build, .git by default)
Scan On Save - Enable automatic scanning when files are saved (default: true)
Scan On Open - Enable automatic scanning when files are opened (default: false)

🎯 Custom Patterns

Add your own regex patterns for organization-specific secrets
Useful for detecting company-specific API key formats or internal tokens

🔐 Git Security Settings

Block Critical Secrets - Prevent commits with critical secrets (default: enabled when hook is installed)
Block High Severity - Optionally block high severity secrets too
Auto-scan Staged - Automatically scan staged files before each commit

Advanced Configuration (settings.json)

You can also edit settings directly in settings.json:

{
  // Detection
  "guardian.enableEntropyAnalysis": true,
  "guardian.entropyThreshold": 4.5,
  "guardian.severityLevel": "medium",
  
  // Scanning
  "guardian.scanOnSave": true,
  "guardian.scanOnOpen": false,
  "guardian.excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**"
  ],
  
  // Custom patterns
  "guardian.customPatterns": [],
  
  // Git integration
  "guardian.git.blockOnCritical": true,
  "guardian.git.blockOnHigh": false,
  "guardian.git.autoScanStaged": false
}

🔍 Detection Categories

Guardian detects secrets in the following categories:

Cloud Credentials

AWS Access Keys, Secret Keys, Session Tokens
Google Cloud API Keys, Service Accounts, OAuth
Azure Storage Keys, Client Secrets

API Keys & Tokens

Generic API keys
Bearer tokens
Authorization headers
JSON Web Tokens (JWT)

Source Control

GitHub Personal Access Tokens, OAuth, App Tokens
GitLab Personal Access Tokens

Database

Connection strings (MongoDB, MySQL, PostgreSQL)
Database passwords

Cryptographic Keys

RSA Private Keys
SSH Private Keys
PGP Private Keys

Payment Services

Stripe API Keys
PayPal/Braintree Tokens

Communication

Slack Tokens and Webhooks
Twilio API Keys

Email Services

SendGrid API Keys
Mailgun API Keys
Mailchimp API Keys

Package Managers

NPM Tokens
PyPI API Tokens

Generic Secrets

Passwords in code
Secret keys
High-entropy strings near sensitive keywords

🧮 Entropy Analysis

Guardian uses Shannon entropy to detect potential secrets that don't match known patterns:

Entropy = -Σ(p(x) * log₂(p(x)))

Low entropy (~2.0): "aaaaaaa" or "1111111"
Medium entropy (~3.5): "password123"
High entropy (~4.5+): "K7x9Mq2Wp5Nz8Rt3" ← Likely a secret!

Strings with high entropy (randomness) + variety of character types are flagged as potential secrets.

📊 Security Dashboard

The visual dashboard provides:

Statistics: Count of findings by severity and category
Overview: Quick view of security status
Navigation: Click findings to jump to exact locations in code
Filtering: Focus on specific severity levels or types

🛡️ Best Practices

Git Commit Protection

Install Pre-commit Hook:

# Via Command Palette
Ctrl+Shift+P → "Guardian: Install Pre-commit Hook"

This automatically blocks commits containing secrets:

✅ Critical secrets → Commit blocked
⚠️ High secrets → Warning (configurable)
ℹ️ Medium/Low → Info only

Manual Verification:

# Before committing
Ctrl+Shift+P → "Guardian: Scan Staged Files"

For detailed git configuration, see the Settings section above.

Prevention

Use Environment Variables: Store secrets in .env files (add to .gitignore)
Secret Management: Use AWS Secrets Manager, HashiCorp Vault, or similar
Pre-commit Hooks: Add Guardian to pre-commit to prevent secrets from being committed
Regular Scans: Schedule periodic workspace scans

Remediation

If Guardian finds secrets:

Critical/High Severity:
- ✅ Immediately rotate the credential
- ✅ Review access logs for unauthorized use
- ✅ Remove from repository history (use git-filter-repo)
- ✅ Update all systems using the credential
Medium/Low Severity:
- ✅ Review if it's a real secret or false positive
- ✅ Move to environment variables or secret manager
- ✅ Update .gitignore to prevent future commits

Managing False Positives

Guardian provides a comprehensive suppression system with audit tracking:

Suppress a Finding:

# Via Tree View (Recommended)
Right-click finding in Guardian Security sidebar 
→ "Suppress Finding (Mark as False Positive)"

# Via Command Palette
Ctrl+Shift+P → "Guardian: Suppress Finding"

Provide a reason (e.g., "Mock AWS key for unit tests")
Suppression is stored with your username and timestamp
Automatically logged to audit trail

View All Suppressions:

Ctrl+Shift+P → "Guardian: View Suppressed Findings"

See all suppressed findings with reasons
Option to view the file
Option to unsuppress findings

Audit & Compliance:

# View suppression statistics and history
Ctrl+Shift+P → "Guardian: View Suppression Report"

# Review suppressions pending >30 days
Ctrl+Shift+P → "Guardian: Review Pending Suppressions"

# Export findings for external tools
Ctrl+Shift+P → "Guardian: Export Security Report"

Storage & Audit Trail:

✅ Working storage: .vscode/guardian-suppressions.json (workspace-local)
✅ Audit log: SUPPRESSIONS_AUDIT.md (git-trackable)
✅ Metadata: File path, line number, pattern, reason, timestamp, username
✅ History: Complete record of all suppress/unsuppress/review actions

For Team & Compliance:

Commit SUPPRESSIONS_AUDIT.md to enable team visibility
All suppressions tied to username for accountability
Historical audit trail for security reviews See SUPPRESSION_AUDIT_GUIDE.md for full details on audit logging.

🎨 Custom Patterns

Add organization-specific patterns:

// Example: Detect custom API key format
{
  "name": "Acme Corp API Key",
  "pattern": "ACME_[A-Z]{4}_[0-9a-f]{32}",
  "severity": "critical",
  "description": "Acme Corp API key detected",
  "flags": "gi"
}

📈 Performance

Fast Scanning: Uses optimized regex patterns
Smart Exclusions: Automatically skips node_modules, dist, etc.
Incremental: Scan-on-save only checks modified files
Configurable: Control what gets scanned

🤝 Contributing

Contributions welcome! Please submit PRs for:

New secret patterns
Performance improvements
UI/UX enhancements
Documentation

📄 License

MIT License - See LICENSE file for details

🧪 Testing

Guardian includes comprehensive unit tests covering:

Pattern detection accuracy
Entropy calculation
Scanner functionality
False positive filtering

# Run tests
npm install
npm test

Tests are located in src/test/ directory.

🔒 Security & Privacy Guarantees

What We Protect

Your Code:

✅ Never leaves your machine
✅ Never sent to external servers
✅ Never logged or stored remotely
✅ Never used for training or analysis

Your Secrets:

✅ Masked in all UI displays
✅ Masked in all log files
✅ Masked in exported reports
✅ Never exposed in error messages

Your Privacy:

✅ No user tracking
✅ No analytics collection
✅ No phone-home functionality
✅ No internet connectivity required

Security Architecture

┌─────────────────────────────────────────┐
│  Your VS Code (Local Environment)      │
│                                         │
│  ┌───────────────────────────────┐    │
│  │ Guardian Extension            │    │
│  │                               │    │
│  │ • Scans locally               │    │
│  │ • Processes in-memory         │    │
│  │ • No network calls            │    │
│  │ • No external dependencies    │    │
│  └───────────────────────────────┘    │
│                                         │
│  ┌───────────────────────────────┐    │
│  │ Your Files                    │    │
│  │ (Never sent externally)       │    │
│  └───────────────────────────────┘    │
└─────────────────────────────────────────┘
         ↓
    Results stay local
         ↓
    You control everything

Compliance Support

Guardian can support your compliance efforts for security frameworks:

SOC 2 Type II:

✅ Provides evidence of secret detection controls (36+ patterns)
✅ Generates audit trails of security scans and suppressions
✅ Supports documented remediation with suggested fixes
Note: Guardian is ONE control among many required for SOC 2 certification

PCI DSS:

✅ Protects payment service credentials (Stripe, PayPal, Twilio keys)
✅ Supports secure development practices with pre-commit hooks
✅ Provides audit logging for compliance documentation
Note: Guardian detects payment API keys, not credit card numbers. Use additional tools for card data detection.

GDPR:

✅ Supports privacy by design (100% local processing, no data transfer)
✅ No telemetry or data collection
⚠️ Guardian detects API credentials, NOT personal data patterns (email, phone, SSN)
Note: For PII detection, combine with dedicated PII scanning tools

HIPAA:

✅ Supports secure credential management for healthcare integrations
✅ Provides audit trail documentation for compliance reviews
⚠️ Guardian detects credentials to health systems, NOT health data/PHI patterns
Note: HIPAA requires comprehensive controls beyond secret detection

Important: Use Guardian as part of a comprehensive compliance strategy. Guardian alone does NOT guarantee compliance - consult with your compliance/security teams for full requirements.

Security Certifications

✅ No external API dependencies
✅ No telemetry or tracking
✅ Completely offline operation
✅ Open source for security audits
✅ No third-party data sharing

Trust Model

Zero Trust Architecture:

Trust nothing by default
Verify everything locally
Assume breach (multi-layer defense)
Minimize blast radius (block before commit)
Continuous verification (real-time scanning)

Guardian helps you find secrets, but never becomes a vulnerability itself.

🛡️ Security Best Practices

Guardian is a security tool, not a security risk. Use it to:

✅ Prevent credential exposure
✅ Meet compliance requirements
✅ Educate developers on security
✅ Build security-first culture

Always combine Guardian with:

Secret management tools (AWS Secrets Manager, Vault)
Code review processes
Security training
Incident response plans

Remember: No tool is perfect. Use Guardian as part of a comprehensive security strategy.

⚠️ Disclaimer

While Guardian is comprehensive, no automated tool catches 100% of secrets. Always:

Review code manually for sensitive data
Use proper secret management practices
Follow your organization's security policies

📞 Support

Getting Help

Documentation:
- README - Feature overview (this file)
- Security Policy - Security vulnerabilities & reporting
- Suppression Guide - Audit logging and suppressions
- Changelog - Version history and updates
Report Bugs: GitHub Issues
- Include Guardian version, VS Code version, file type
- Provide minimal reproduction steps
- Do NOT include actual secrets in bug reports
Feature Requests: GitHub Issues with enhancement label
- Describe the use case
- Explain how it improves security
Questions & Discussions: GitHub Discussions
- Ask questions about usage
- Share tips and best practices

Security Reporting

IMPORTANT: If you discover a vulnerability IN Guardian itself:

Do NOT open a public GitHub issue
Email security details to: maneeshkumar.thakur@outlook.com
Include description, reproduction steps, and potential impact
Allow 48 hours for acknowledgment
Alternative: Use GitHub Security Advisory

Quick Troubleshooting

Guardian not detecting secrets?

Verify guardian.scanOnSave is enabled in settings
Check file type is supported (JavaScript, Python, Go, Java, TypeScript, etc.)
Try manual scan: Ctrl+Shift+P → "Guardian: Scan Entire Workspace"
Review entropy threshold setting

Too many false positives?

Increase guardian.entropyThreshold (higher = stricter detection)
Suppress findings with reasons for team visibility
Add patterns to guardian.excludePatterns for false positive categories

Pre-commit hook issues?

Verify Git is initialized in workspace
Run: Ctrl+Shift+P → "Guardian: Install Pre-commit Hook"
Check .git/hooks/pre-commit file permissions
Verify hook is executable: chmod +x .git/hooks/pre-commit

Performance concerns?

Disable guardian.scanOnOpen (only scans on save by default)
Expand guardian.excludePatterns for large folders
Use guardian.severityLevel to focus on critical issues

Made with 🛡️ for developers who care about security

"Security First. Privacy Always. Trust Never." - The Guardian Way

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
docs		docs
resources		resources
src		src
.gitignore		.gitignore
.vscodeignore		.vscodeignore
CODEOWNERS		CODEOWNERS
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Folders and files

Latest commit

History

Repository files navigation

🛡️ Guardian - Secrets Scanner for VS Code

🔒 Our Core Principles

SECURITY FIRST

PRIVACY BY DESIGN

RESPONSIBILITY & COMPLIANCE

🚀 Key Features

What Makes Guardian Different?

📦 Installation

From VSIX

From Source

🎯 Usage

Commands

Activity Bar

Status Bar

⚙️ Configuration

Opening Settings

Settings Categories

🔍 Detection Settings

📁 Scanning Settings

🎯 Custom Patterns

🔐 Git Security Settings

Advanced Configuration (settings.json)

🔍 Detection Categories

Cloud Credentials

API Keys & Tokens

Source Control

Database

Cryptographic Keys

Payment Services

Communication

Email Services

Package Managers

Generic Secrets

🧮 Entropy Analysis

📊 Security Dashboard

🛡️ Best Practices

Git Commit Protection

Prevention

Remediation

Managing False Positives

🎨 Custom Patterns

📈 Performance

🤝 Contributing

📄 License

🧪 Testing

🔒 Security & Privacy Guarantees

What We Protect

Security Architecture

Compliance Support

Security Certifications

Trust Model

🛡️ Security Best Practices

⚠️ Disclaimer

📞 Support

Getting Help

Security Reporting

Quick Troubleshooting

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages