Skip to main content

🛡️ GuardRails Security Scanner (Python)

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 from PyPI
pip install guardrails-security

# Or install from source
pip install git+https://github.com/guardrails/guardrails-security.git

# Scan your code
guardrails scan .

# Initialize in your project
guardrails init

📋 Features

  • ✅ AI-Powered Analysis - Uses Gemini AI for intelligent vulnerability detection
  • ✅ Multi-Language Support - Python, JavaScript, TypeScript, 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

pip install guardrails-security

From Source

git clone https://github.com/guardrails/guardrails-security.git
cd guardrails-security
pip install -e .

Development Installation

git clone https://github.com/guardrails/guardrails-security.git
cd guardrails-security
pip install -e ".[dev]"

📖 Usage

Basic Scanning

# Scan current directory
guardrails scan .

# Scan specific file
guardrails scan app.py

# 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
  • .guardrailsignore - Ignore patterns
  • Updates requirements.txt if it exists

⚙️ Configuration

Create a guardrails.config.json file:

{
  "version": "1.0.0",
  "scan": {
    "extensions": [".py", ".js", ".ts", ".jsx", ".tsx", ".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 Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Install GuardRails
        run: pip install guardrails-security
      - name: Run Security Scan
        run: guardrails scan . --fail-on-critical

GitLab CI

security_scan:
  stage: test
  image: python:3.9
  script:
    - pip install guardrails-security
    - guardrails scan . --format json --output guardrails-report.json
  artifacts:
    reports:
      junit: guardrails-report.json

Makefile Integration

.PHONY: security-scan
security-scan:
	guardrails scan . --fail-on-critical

.PHONY: security-report
security-report:
	guardrails scan . --format json --output security-report.json

🎯 Supported Languages

  • Python - .py
  • JavaScript/TypeScript - .js, .ts, .jsx, .tsx
  • 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.py:25
   ⚠️  Potential SQL injection detected
   💡 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.py",
      "line": 25,
      "message": "Potential SQL injection detected",
      "fix": "Use parameterized queries...",
      "analysis": "Detailed AI analysis..."
    }
  ]
}

🛠️ API Usage

from guardrails import GuardRailsScanner

# Initialize scanner
scanner = GuardRailsScanner(
    api_key="your-api-key",  # Optional for local server
    base_url="https://api.guardrails.dev"  # Or local server
)

# Scan directory
results = scanner.scan("./src")

# Check for critical issues
if scanner.has_critical_issues(results):
    print("Critical security issues found!")
    exit(1)

# Get formatted report
report = scanner.format_report(results, "text")
print(report)

# Check server status
status = scanner.check_server_status()
print(f"Server status: {status['status']}")

🔧 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
  --timeout <seconds>       Request timeout
  -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
pip install -r requirements.txt

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

# Start the server
python -m guardrails.server

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

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

📄 License

MIT License - see LICENSE file.

🆘 Support


Made with ❤️ by the GuardRails team

Metadata

Release files for guardrails-security 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for guardrails-security 1.0.1
File Size Uploaded Provenance Actions
guardrails_security-1.0.1.tar.gz 13.6 kB Without provenance Details for guardrails_security-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for guardrails-security 1.0.1
File Interpreter ABI Platform Actions
guardrails_security-1.0.1-py3-none-any.whl Python 3 none any Details for guardrails_security-1.0.1-py3-none-any.whl

Total release size: 25.5 kB

Release files / guardrails_security-1.0.1.tar.gz

Download URL guardrails_security-1.0.1.tar.gz
Size 13.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3cb8fbbe93623caa46e8ac9ddb5b2af067593c29c43b95e507d6ffe42f0fc15f
BLAKE2b-256 checksum
How to use checksums
bb9c4f1b4dc1d6d09522217bad95c1e728f53ecc4193ccbd3ca2d76668df25f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Release files / guardrails_security-1.0.1-py3-none-any.whl

Download URL guardrails_security-1.0.1-py3-none-any.whl
Size 11.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a3ccb3f3e1bcbb6657c9e2b21ea69c0bfbc02a2205b7b4e1ee71c84e7b3e3593
BLAKE2b-256 checksum
How to use checksums
83a671754d9288269ae082c9232bd5c82c6d0d18317eac70494c4f2d6cf2977e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Security for guardrails-security 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page