🛡️ GuardRails Scanner

AI-powered security scanner for modern development workflows

GuardRails uses advanced AI (Gemini) to detect security vulnerabilities in your code, providing detailed explanations and fix suggestions.

🚀 Quick Start

# Install globally
npm install -g @guardrails/scanner

# Or use with npx
npx @guardrails/scanner scan .

# Initialize in your project
guardrails init

📋 Features

• ✅ AI-Powered Analysis - Uses Gemini AI for intelligent vulnerability detection
• ✅ Multi-Language Support - JavaScript, TypeScript, Python, Java, Go, PHP, Ruby, C#
• ✅ Detailed Fix Suggestions - Get specific code fixes for each vulnerability
• ✅ CI/CD Integration - Easy integration with GitHub Actions, GitLab CI, etc.
• ✅ Git Hooks - Automatic scanning before commits
• ✅ Multiple Output Formats - Text, JSON, table formats
• ✅ Configurable - Customize scan rules and ignore patterns

🔧 Installation

Global Installation

npm install -g @guardrails/scanner

Project Installation

npm install --save-dev @guardrails/scanner

Using npx (No Installation)

npx @guardrails/scanner scan .

📖 Usage

Basic Scanning

# Scan current directory
guardrails scan .

# Scan specific file
guardrails scan src/app.js

# Scan with JSON output
guardrails scan . --format json

# Save report to file
guardrails scan . --output security-report.json

CI/CD Integration

# Fail build on critical issues
guardrails scan . --fail-on-critical

# Generate JSON report for CI
guardrails scan . --format json --output guardrails-report.json

Git Hooks

# Install pre-commit hook
guardrails install-hook

# Install hook that blocks commits on critical issues
guardrails install-hook --fail-on-critical

Project Initialization

# Initialize GuardRails in your project
guardrails init

This creates:

• guardrails.config.json - Configuration file
• Adds scripts to package.json
• Sets up recommended settings

⚙️ Configuration

Create a guardrails.config.json file:

{
  "version": "1.0.0",
  "scan": {
    "extensions": [".js", ".ts", ".jsx", ".tsx", ".py", ".java", ".go"],
    "ignore": ["node_modules/**", ".git/**", "dist/**", "build/**"],
    "failOnCritical": true
  },
  "ci": {
    "enabled": true,
    "output": "guardrails-report.json"
  }
}

🔗 CI/CD Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18'
      - name: Install GuardRails
        run: npm install -g @guardrails/scanner
      - name: Run Security Scan
        run: guardrails scan . --fail-on-critical

GitLab CI

security_scan:
  stage: test
  image: node:18
  script:
    - npm install -g @guardrails/scanner
    - guardrails scan . --format json --output guardrails-report.json
  artifacts:
    reports:
      junit: guardrails-report.json

Package.json Scripts

{
  "scripts": {
    "guardrails:scan": "guardrails scan .",
    "guardrails:ci": "guardrails scan . --format json --output guardrails-report.json --fail-on-critical",
    "precommit": "guardrails scan . --fail-on-critical"
  }
}

🎯 Supported Languages

• JavaScript/TypeScript - .js, .ts, .jsx, .tsx
• Python - .py
• Java - .java
• Go - .go
• PHP - .php
• Ruby - .rb
• C# - .cs

🔍 Vulnerability Types

GuardRails detects:

• SQL Injection - Database query vulnerabilities
• XSS (Cross-Site Scripting) - Web application vulnerabilities
• Hardcoded Credentials - Exposed passwords and API keys
• Insecure Dependencies - Vulnerable third-party packages
• Authentication Issues - Weak authentication mechanisms
• Authorization Flaws - Access control problems
• Data Exposure - Sensitive data leaks
• Cryptographic Issues - Weak encryption and hashing

📊 Output Formats

Text Format (Default)

🛡️  GuardRails Security Report
═══════════════════════════════════════

📊 Security Score: 75/100
📁 Files Scanned: 15
🚨 Total Issues: 3

📋 Issues by Severity:
   🔴 Critical: 1
   🟡 High: 1
   🔵 Medium: 1
   🟢 Low: 0

🔍 Detailed Findings:

1. SQL INJECTION
   📁 File: src/database.js:25
   ⚠️  Potential SQL injection detected - string concatenation in query
   💡 Fix: Use parameterized queries to prevent SQL injection...

JSON Format

{
  "securityScore": 75,
  "summary": {
    "totalFiles": 15,
    "vulnerabilities": 3,
    "critical": 1,
    "high": 1,
    "medium": 1,
    "low": 0
  },
  "findings": [
    {
      "id": "sql-injection-123",
      "type": "SQL_INJECTION",
      "severity": "CRITICAL",
      "file": "src/database.js",
      "line": 25,
      "message": "Potential SQL injection detected",
      "fix": "Use parameterized queries...",
      "analysis": "Detailed AI analysis..."
    }
  ]
}

🛠️ API Usage

const GuardRailsScanner = require('@guardrails/scanner');

const scanner = new GuardRailsScanner({
  apiKey: process.env.GUARDRAILS_API_KEY,
  baseUrl: 'https://api.guardrails.dev'
});

// Scan directory
const results = await scanner.scan('./src');

// Check for critical issues
if (scanner.hasCriticalIssues(results)) {
  console.log('Critical security issues found!');
  process.exit(1);
}

// Get formatted report
const report = scanner.formatReport(results, 'text');
console.log(report);

🔧 Command Line Options

guardrails scan <target> [options]

Options:
  -f, --format <format>     Output format (text, json, table)
  -o, --output <file>       Output file path
  --fail-on-critical        Exit with error code if critical issues found
  --ignore <patterns>       Ignore patterns (comma-separated)
  --extensions <exts>       File extensions to scan (comma-separated)
  --api-key <key>           GuardRails API key
  --server <url>            GuardRails server URL
  -h, --help                Display help
  -V, --version             Display version

🌐 Server Setup

GuardRails requires a backend server for AI analysis:

# Clone the repository
git clone https://github.com/guardrails/guardrails.git
cd guardrails

# Install dependencies
npm install

# Set up environment
cp env.example .env
# Edit .env with your Gemini API key

# Start the server
npm run dev

📈 Business Model

GuardRails offers multiple pricing tiers:

🆓 Free Tier

• Individual developers
• Public repositories
• 100 scans/month
• Basic vulnerability detection

💼 Team ($49/month)

• Up to 5 developers
• Private repositories
• 1,000 scans/month
• AI-powered fix suggestions
• CI/CD integration

🏢 Enterprise ($299/month)

• Unlimited developers
• Unlimited scans
• Advanced reporting
• Priority support
• Custom rules

🏛️ Enterprise+ ($999/month)

• On-premise deployment
• SLA guarantee
• Dedicated support
• Custom integrations

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

MIT License - see LICENSE file.

🔗 Links

• Website: https://guardrails.dev
• Documentation: https://docs.guardrails.dev
• GitHub: https://github.com/guardrails/guardrails
• Support: [email protected]

🆘 Support

• Documentation: https://docs.guardrails.dev
• Issues: https://github.com/guardrails/guardrails/issues
• Email: [email protected]
• Discord: https://discord.gg/guardrails

Made with ❤️ by the GuardRails team