# 🛡️ 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
```bash
# 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)
```bash
pip install guardrails-security
```
### From Source
```bash
git clone https://github.com/guardrails/guardrails-security.git
cd guardrails-security
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/guardrails/guardrails-security.git
cd guardrails-security
pip install -e ".[dev]"
```
## 📖 Usage
### Basic Scanning
```bash
# 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
```bash
# 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
```bash
# Install pre-commit hook
guardrails install-hook
# Install hook that blocks commits on critical issues
guardrails install-hook --fail-on-critical
```
### Project Initialization
```bash
# 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:
```json
{
"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
```yaml
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
```yaml
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
```makefile
.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
```json
{
"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
```python
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
```bash
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:
```bash
# 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](CONTRIBUTING.md).
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](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**
Raw data
{
"_id": null,
"home_page": "https://github.com/guardrails/guardrails-security",
"name": "guardrails-security",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "security, scanner, vulnerability, ai, gemini, devsecops, code-analysis",
"author": "GuardRails Team",
"author_email": "team@guardrails.dev",
"download_url": "https://files.pythonhosted.org/packages/bb/9c/4f1b4dc1d6d09522217bad95c1e728f53ecc4193ccbd3ca2d76668df25f0/guardrails_security-1.0.1.tar.gz",
"platform": null,
"description": "# \ud83d\udee1\ufe0f GuardRails Security Scanner (Python)\n\n**AI-powered security scanner for modern development workflows**\n\nGuardRails uses advanced AI (Gemini) to detect security vulnerabilities in your code, providing detailed explanations and fix suggestions.\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install from PyPI\npip install guardrails-security\n\n# Or install from source\npip install git+https://github.com/guardrails/guardrails-security.git\n\n# Scan your code\nguardrails scan .\n\n# Initialize in your project\nguardrails init\n```\n\n## \ud83d\udccb Features\n\n- \u2705 **AI-Powered Analysis** - Uses Gemini AI for intelligent vulnerability detection\n- \u2705 **Multi-Language Support** - Python, JavaScript, TypeScript, Java, Go, PHP, Ruby, C#\n- \u2705 **Detailed Fix Suggestions** - Get specific code fixes for each vulnerability\n- \u2705 **CI/CD Integration** - Easy integration with GitHub Actions, GitLab CI, etc.\n- \u2705 **Git Hooks** - Automatic scanning before commits\n- \u2705 **Multiple Output Formats** - Text, JSON, table formats\n- \u2705 **Configurable** - Customize scan rules and ignore patterns\n\n## \ud83d\udd27 Installation\n\n### From PyPI (Recommended)\n```bash\npip install guardrails-security\n```\n\n### From Source\n```bash\ngit clone https://github.com/guardrails/guardrails-security.git\ncd guardrails-security\npip install -e .\n```\n\n### Development Installation\n```bash\ngit clone https://github.com/guardrails/guardrails-security.git\ncd guardrails-security\npip install -e \".[dev]\"\n```\n\n## \ud83d\udcd6 Usage\n\n### Basic Scanning\n\n```bash\n# Scan current directory\nguardrails scan .\n\n# Scan specific file\nguardrails scan app.py\n\n# Scan with JSON output\nguardrails scan . --format json\n\n# Save report to file\nguardrails scan . --output security-report.json\n```\n\n### CI/CD Integration\n\n```bash\n# Fail build on critical issues\nguardrails scan . --fail-on-critical\n\n# Generate JSON report for CI\nguardrails scan . --format json --output guardrails-report.json\n```\n\n### Git Hooks\n\n```bash\n# Install pre-commit hook\nguardrails install-hook\n\n# Install hook that blocks commits on critical issues\nguardrails install-hook --fail-on-critical\n```\n\n### Project Initialization\n\n```bash\n# Initialize GuardRails in your project\nguardrails init\n```\n\nThis creates:\n- `guardrails.config.json` - Configuration file\n- `.guardrailsignore` - Ignore patterns\n- Updates `requirements.txt` if it exists\n\n## \u2699\ufe0f Configuration\n\nCreate a `guardrails.config.json` file:\n\n```json\n{\n \"version\": \"1.0.0\",\n \"scan\": {\n \"extensions\": [\".py\", \".js\", \".ts\", \".jsx\", \".tsx\", \".java\", \".go\"],\n \"ignore\": [\"node_modules/**\", \".git/**\", \"dist/**\", \"build/**\"],\n \"failOnCritical\": true\n },\n \"ci\": {\n \"enabled\": true,\n \"output\": \"guardrails-report.json\"\n }\n}\n```\n\n## \ud83d\udd17 CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Security Scan\non: [push, pull_request]\n\njobs:\n security:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: Setup Python\n uses: actions/setup-python@v2\n with:\n python-version: '3.9'\n - name: Install GuardRails\n run: pip install guardrails-security\n - name: Run Security Scan\n run: guardrails scan . --fail-on-critical\n```\n\n### GitLab CI\n\n```yaml\nsecurity_scan:\n stage: test\n image: python:3.9\n script:\n - pip install guardrails-security\n - guardrails scan . --format json --output guardrails-report.json\n artifacts:\n reports:\n junit: guardrails-report.json\n```\n\n### Makefile Integration\n\n```makefile\n.PHONY: security-scan\nsecurity-scan:\n\tguardrails scan . --fail-on-critical\n\n.PHONY: security-report\nsecurity-report:\n\tguardrails scan . --format json --output security-report.json\n```\n\n## \ud83c\udfaf Supported Languages\n\n- **Python** - `.py`\n- **JavaScript/TypeScript** - `.js`, `.ts`, `.jsx`, `.tsx`\n- **Java** - `.java`\n- **Go** - `.go`\n- **PHP** - `.php`\n- **Ruby** - `.rb`\n- **C#** - `.cs`\n\n## \ud83d\udd0d Vulnerability Types\n\nGuardRails detects:\n\n- **SQL Injection** - Database query vulnerabilities\n- **XSS (Cross-Site Scripting)** - Web application vulnerabilities\n- **Hardcoded Credentials** - Exposed passwords and API keys\n- **Insecure Dependencies** - Vulnerable third-party packages\n- **Authentication Issues** - Weak authentication mechanisms\n- **Authorization Flaws** - Access control problems\n- **Data Exposure** - Sensitive data leaks\n- **Cryptographic Issues** - Weak encryption and hashing\n\n## \ud83d\udcca Output Formats\n\n### Text Format (Default)\n```\n\ud83d\udee1\ufe0f GuardRails Security Report\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n\ud83d\udcca Security Score: 75/100\n\ud83d\udcc1 Files Scanned: 15\n\ud83d\udea8 Total Issues: 3\n\n\ud83d\udccb Issues by Severity:\n \ud83d\udd34 Critical: 1\n \ud83d\udfe1 High: 1\n \ud83d\udd35 Medium: 1\n \ud83d\udfe2 Low: 0\n\n\ud83d\udd0d Detailed Findings:\n\n1. SQL INJECTION\n \ud83d\udcc1 File: src/database.py:25\n \u26a0\ufe0f Potential SQL injection detected\n \ud83d\udca1 Fix: Use parameterized queries to prevent SQL injection...\n```\n\n### JSON Format\n```json\n{\n \"securityScore\": 75,\n \"summary\": {\n \"totalFiles\": 15,\n \"vulnerabilities\": 3,\n \"critical\": 1,\n \"high\": 1,\n \"medium\": 1,\n \"low\": 0\n },\n \"findings\": [\n {\n \"id\": \"sql-injection-123\",\n \"type\": \"SQL_INJECTION\",\n \"severity\": \"CRITICAL\",\n \"file\": \"src/database.py\",\n \"line\": 25,\n \"message\": \"Potential SQL injection detected\",\n \"fix\": \"Use parameterized queries...\",\n \"analysis\": \"Detailed AI analysis...\"\n }\n ]\n}\n```\n\n## \ud83d\udee0\ufe0f API Usage\n\n```python\nfrom guardrails import GuardRailsScanner\n\n# Initialize scanner\nscanner = GuardRailsScanner(\n api_key=\"your-api-key\", # Optional for local server\n base_url=\"https://api.guardrails.dev\" # Or local server\n)\n\n# Scan directory\nresults = scanner.scan(\"./src\")\n\n# Check for critical issues\nif scanner.has_critical_issues(results):\n print(\"Critical security issues found!\")\n exit(1)\n\n# Get formatted report\nreport = scanner.format_report(results, \"text\")\nprint(report)\n\n# Check server status\nstatus = scanner.check_server_status()\nprint(f\"Server status: {status['status']}\")\n```\n\n## \ud83d\udd27 Command Line Options\n\n```bash\nguardrails scan <target> [options]\n\nOptions:\n -f, --format <format> Output format (text, json, table)\n -o, --output <file> Output file path\n --fail-on-critical Exit with error code if critical issues found\n --ignore <patterns> Ignore patterns (comma-separated)\n --extensions <exts> File extensions to scan (comma-separated)\n --api-key <key> GuardRails API key\n --server <url> GuardRails server URL\n --timeout <seconds> Request timeout\n -h, --help Display help\n -V, --version Display version\n```\n\n## \ud83c\udf10 Server Setup\n\nGuardRails requires a backend server for AI analysis:\n\n```bash\n# Clone the repository\ngit clone https://github.com/guardrails/guardrails.git\ncd guardrails\n\n# Install dependencies\npip install -r requirements.txt\n\n# Set up environment\ncp env.example .env\n# Edit .env with your Gemini API key\n\n# Start the server\npython -m guardrails.server\n```\n\n## \ud83d\udcc8 Business Model\n\nGuardRails offers multiple pricing tiers:\n\n### \ud83c\udd93 Free Tier\n- Individual developers\n- Public repositories\n- 100 scans/month\n- Basic vulnerability detection\n\n### \ud83d\udcbc Team ($49/month)\n- Up to 5 developers\n- Private repositories\n- 1,000 scans/month\n- AI-powered fix suggestions\n- CI/CD integration\n\n### \ud83c\udfe2 Enterprise ($299/month)\n- Unlimited developers\n- Unlimited scans\n- Advanced reporting\n- Priority support\n- Custom rules\n\n### \ud83c\udfdb\ufe0f Enterprise+ ($999/month)\n- On-premise deployment\n- SLA guarantee\n- Dedicated support\n- Custom integrations\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## \ud83d\udd17 Links\n\n- **Website**: https://guardrails.dev\n- **Documentation**: https://docs.guardrails.dev\n- **GitHub**: https://github.com/guardrails/guardrails-security\n- **PyPI**: https://pypi.org/project/guardrails-security/\n- **Support**: support@guardrails.dev\n\n## \ud83c\udd98 Support\n\n- **Documentation**: https://docs.guardrails.dev\n- **Issues**: https://github.com/guardrails/guardrails-security/issues\n- **Email**: support@guardrails.dev\n- **Discord**: https://discord.gg/guardrails\n\n---\n\n**Made with \u2764\ufe0f by the GuardRails team**\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered security scanner for modern development workflows",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/guardrails/guardrails-security/issues",
"Documentation": "https://docs.guardrails.dev",
"Homepage": "https://guardrails.dev",
"Source": "https://github.com/guardrails/guardrails-security"
},
"split_keywords": [
"security",
" scanner",
" vulnerability",
" ai",
" gemini",
" devsecops",
" code-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "83a671754d9288269ae082c9232bd5c82c6d0d18317eac70494c4f2d6cf2977e",
"md5": "dc0e4d4929510c12cf3bdcccdb0c37e0",
"sha256": "a3ccb3f3e1bcbb6657c9e2b21ea69c0bfbc02a2205b7b4e1ee71c84e7b3e3593"
},
"downloads": -1,
"filename": "guardrails_security-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc0e4d4929510c12cf3bdcccdb0c37e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11846,
"upload_time": "2025-10-26T00:58:01",
"upload_time_iso_8601": "2025-10-26T00:58:01.538749Z",
"url": "https://files.pythonhosted.org/packages/83/a6/71754d9288269ae082c9232bd5c82c6d0d18317eac70494c4f2d6cf2977e/guardrails_security-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb9c4f1b4dc1d6d09522217bad95c1e728f53ecc4193ccbd3ca2d76668df25f0",
"md5": "42fd0b845fce8672f1ece475e70dd7a2",
"sha256": "3cb8fbbe93623caa46e8ac9ddb5b2af067593c29c43b95e507d6ffe42f0fc15f"
},
"downloads": -1,
"filename": "guardrails_security-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "42fd0b845fce8672f1ece475e70dd7a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13648,
"upload_time": "2025-10-26T00:58:03",
"upload_time_iso_8601": "2025-10-26T00:58:03.379300Z",
"url": "https://files.pythonhosted.org/packages/bb/9c/4f1b4dc1d6d09522217bad95c1e728f53ecc4193ccbd3ca2d76668df25f0/guardrails_security-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 00:58:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guardrails",
"github_project": "guardrails-security",
"github_not_found": true,
"lcname": "guardrails-security"
}
JSON
