🛡️ 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
From PyPI (Recommended)
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.txtif 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.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
📄 License
MIT License - see LICENSE file.
🔗 Links
- Website: https://guardrails.dev
- Documentation: https://docs.guardrails.dev
- GitHub: https://github.com/guardrails/guardrails-security
- PyPI: https://pypi.org/project/guardrails-security/
- Support: support@guardrails.dev
🆘 Support
- Documentation: https://docs.guardrails.dev
- Issues: https://github.com/guardrails/guardrails-security/issues
- Email: support@guardrails.dev
- Discord: https://discord.gg/guardrails
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.