dgtlss / warden
A Laravel package that proactively monitors your dependencies for security vulnerabilities by running automated composer audits and sending notifications via webhooks and email
Installs: 16 887
Dependents: 0
Suggesters: 0
Security: 0
Stars: 62
Watchers: 2
Forks: 4
Open Issues: 0
Requires
- php: >=8.1
- guzzlehttp/guzzle: ^7.0
- illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0|^12.0
- laravel/prompts: ^0.3
README
Warden is a comprehensive Laravel security audit package that proactively monitors your dependencies and application configuration for security vulnerabilities. Built for enterprise-grade security scanning, Warden provides powerful features for modern Laravel applications.
🚀 Key Features
✅ Core Security Audits
- 🔍 Dependency Scanning: Composer and NPM vulnerability detection
- ⚙️ Configuration Audits: Environment, storage permissions, and Laravel config
- 📝 Code Analysis: PHP syntax validation and security checks
- 🔧 Custom Audit Rules: Organization-specific security policies
✅ Performance & Scalability
- ⚡ Parallel Execution: Up to 5x faster audit performance
- 🗄️ Intelligent Caching: Prevents redundant scans with configurable TTL
- 🎯 Severity Filtering: Focus on critical issues only
✅ Integration & Automation
- 📊 Multiple Output Formats: JSON, GitHub Actions, GitLab CI, Jenkins
- 🔔 Rich Notifications: Slack, Discord, Email with formatted reports
- ⏰ Automated Scheduling: Laravel scheduler integration
- 🔄 CI/CD Ready: Native support for all major platforms
Perfect for continuous security monitoring and DevOps pipelines.
📋 Table of Contents
- Installation
- Quick Start
- Configuration
- Security Audits
- Usage Examples
- Notifications
- Custom Audits
- Scheduling
- CI/CD Integration
- Advanced Features
🚀 Installation
Install via Composer:
composer require dgtlss/warden
Publish configuration:
php artisan vendor:publish --tag="warden-config"
This creates config/warden.php
with all available options.
⚡ Quick Start
Basic Security Audit
php artisan warden:audit
With NPM Dependencies
php artisan warden:audit --npm
JSON Output for CI/CD
php artisan warden:audit --output=json --severity=high
Silent Mode (No Notifications)
php artisan warden:audit --silent
⚙️ Configuration
Environment Variables
Add these to your .env
file:
🔔 Notifications
# Slack (recommended - rich formatting) WARDEN_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL # Discord WARDEN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/WEBHOOK # Microsoft Teams WARDEN_TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/YOUR/WEBHOOK # Email WARDEN_EMAIL_RECIPIENTS=security@company.com,admin@company.com WARDEN_EMAIL_FROM=security@company.com WARDEN_EMAIL_FROM_NAME="Security Team" # Legacy webhook (backward compatibility) WARDEN_WEBHOOK_URL=https://your-webhook-url.com
⚡ Performance
WARDEN_CACHE_ENABLED=true WARDEN_CACHE_DURATION=3600 # Cache for 1 hour WARDEN_PARALLEL_EXECUTION=true # Enable parallel audits
⏰ Scheduling
WARDEN_SCHEDULE_ENABLED=false WARDEN_SCHEDULE_FREQUENCY=daily # hourly|daily|weekly|monthly WARDEN_SCHEDULE_TIME=03:00 WARDEN_SCHEDULE_TIMEZONE=UTC
📊 Output & Filtering
WARDEN_SEVERITY_FILTER= # null|low|medium|high|critical WARDEN_OUTPUT_JSON=false WARDEN_OUTPUT_JUNIT=false
🔍 Security Audits
Warden performs comprehensive security analysis across multiple areas:
1. Composer Dependencies
- Scans PHP dependencies for known vulnerabilities
- Uses official
composer audit
command - Identifies abandoned packages with replacement suggestions
2. NPM Dependencies
- Analyzes JavaScript dependencies (when
--npm
flag used) - Detects vulnerable packages in
package.json
- Validates
package-lock.json
integrity
3. Environment Configuration
- Verifies
.env
file presence and.gitignore
status - Checks for missing critical environment variables
- Validates sensitive key configuration
4. Storage & Permissions
- Audits Laravel storage directories (
storage/
,bootstrap/cache/
) - Ensures proper write permissions
- Identifies missing or misconfigured paths
5. Laravel Configuration
- Debug mode status verification
- Session security settings
- CSRF protection validation
- General security misconfigurations
6. PHP Syntax Analysis
- Code syntax validation across your application
- Configurable directory exclusions
- Integration with existing audit workflow
💡 Usage Examples
Basic Commands
# Standard audit php artisan warden:audit # Include NPM + severity filtering php artisan warden:audit --npm --severity=medium # Force cache refresh php artisan warden:audit --force # Ignore abandoned packages php artisan warden:audit --ignore-abandoned
Output Formats
# JSON for processing php artisan warden:audit --output=json > security-report.json # GitHub Actions annotations php artisan warden:audit --output=github # GitLab CI dependency scanning php artisan warden:audit --output=gitlab > gl-dependency-scanning-report.json # Jenkins format php artisan warden:audit --output=jenkins
Advanced Usage
# Combined options php artisan warden:audit --npm --severity=high --output=json --silent # PHP syntax check php artisan warden:syntax # Schedule management php artisan warden:schedule --enable php artisan warden:schedule --status
🔔 Notifications
Warden supports multiple notification channels with rich formatting:
✅ Slack (Recommended)
- Color-coded severity levels
- Organized finding blocks
- Clickable CVE links
- Professional formatting
WARDEN_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
✅ Discord
- Rich embeds with color coding
- Grouped findings by source
- Custom branding
WARDEN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/WEBHOOK
✅ Microsoft Teams
- Adaptive Cards with structured layouts
- Color-coded severity indicators
- Action buttons and rich formatting
WARDEN_TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/YOUR/WEBHOOK
- Professional HTML templates with modern styling
- Severity-based color coding and summary statistics
- Grouped findings by source with detailed information
- Separate templates for vulnerabilities and abandoned packages
WARDEN_EMAIL_RECIPIENTS=security@company.com,admin@company.com WARDEN_EMAIL_FROM=security@company.com WARDEN_EMAIL_FROM_NAME="Security Team"
Multiple Channels
Configure multiple channels simultaneously - Warden sends to all configured endpoints.
🔧 Custom Audits
Create organization-specific security rules:
1. Implement Custom Audit
<?php namespace App\Audits; use Dgtlss\Warden\Contracts\CustomAudit; class DatabasePasswordAudit implements CustomAudit { public function audit(): bool { $dbPassword = env('DB_PASSWORD', ''); return !in_array(strtolower($dbPassword), ['password', '123456', 'admin']); } public function getFindings(): array { return [ [ 'package' => 'environment', 'title' => 'Weak Database Password', 'severity' => 'critical', 'description' => 'Database password is weak or commonly used', 'remediation' => 'Use a strong, unique password' ] ]; } public function getName(): string { return 'Database Password Security'; } public function getDescription(): string { return 'Checks for weak database passwords'; } public function shouldRun(): bool { return !empty(env('DB_CONNECTION')); } }
2. Register Custom Audit
Add to config/warden.php
:
'custom_audits' => [ \App\Audits\DatabasePasswordAudit::class, \App\Audits\ApiKeySecurityAudit::class, // Add more custom audits ],
⏰ Scheduling
Enable Automated Audits
# Enable scheduling php artisan warden:schedule --enable # Check status php artisan warden:schedule --status # Disable scheduling php artisan warden:schedule --disable
Configure Schedule
WARDEN_SCHEDULE_ENABLED=true WARDEN_SCHEDULE_FREQUENCY=daily WARDEN_SCHEDULE_TIME=03:00
Laravel Cron Setup
Ensure Laravel's scheduler is running:
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
🔄 CI/CD Integration
GitHub Actions
name: Security Audit on: [push, pull_request] jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.1' - name: Install dependencies run: composer install --no-progress --prefer-dist - name: Security Audit run: php artisan warden:audit --output=github --severity=high
GitLab CI
security_audit: stage: test script: - composer install --no-progress --prefer-dist - php artisan warden:audit --output=gitlab --silent > gl-dependency-scanning-report.json artifacts: reports: dependency_scanning: gl-dependency-scanning-report.json expire_in: 1 week allow_failure: false
Jenkins
pipeline { agent any stages { stage('Security Audit') { steps { sh 'composer install --no-progress --prefer-dist' sh 'php artisan warden:audit --output=jenkins --severity=high' } post { always { publishHTML([ allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: '.', reportFiles: 'audit-report.json', reportName: 'Security Audit Report' ]) } } } } }
🎯 Advanced Features
Performance Optimization
- Parallel Execution: Enabled by default for 5x speed improvement
- Intelligent Caching: Configurable cache duration prevents redundant API calls
- Severity Filtering: Focus resources on critical issues
Audit Results
Exit Codes:
0
: No vulnerabilities found1
: Vulnerabilities detected2
: Audit process failures
Severity Levels:
critical
: Immediate attention requiredhigh
: Address as soon as possiblemedium
: Should be reviewed and fixedlow
: Minor security concerns
Configuration Examples
// config/warden.php 'audits' => [ 'parallel_execution' => true, 'timeout' => 300, 'retry_attempts' => 3, 'severity_filter' => 'medium', ], 'cache' => [ 'enabled' => true, 'duration' => 3600, // 1 hour ], 'sensitive_keys' => [ 'DB_PASSWORD', 'STRIPE_SECRET', 'AWS_SECRET_ACCESS_KEY', ],
🆕 What's New in v1.3.0
- ✅ Parallel audit execution for 5x faster performance
- ✅ Complete notification suite (Slack, Discord, Teams, Enhanced Email)
- ✅ Professional email templates with severity colors and statistics
- ✅ Microsoft Teams integration with Adaptive Cards
- ✅ CI/CD output formats (GitHub Actions, GitLab CI, Jenkins)
- ✅ Automated scheduling via Laravel scheduler
- ✅ Custom audit rules for organization-specific policies
- ✅ Intelligent caching with force refresh capability
- ✅ Severity filtering to focus on critical issues
📈 Roadmap
Coming Soon
- 📊 Audit history tracking and trend analysis
- 🔍 Additional audit types (Docker, Git, API security)
- 📋 Web dashboard for audit management
- 🤖 AI-powered vulnerability analysis and recommendations
🛠️ Troubleshooting
Common Issues
Command not found:
php artisan config:clear composer dump-autoload
Composer audit failures:
# Update Composer to latest version
composer self-update
📄 License
This package is open source and released under the MIT License.
🤝 Contributing
We welcome contributions! Please see our CONTRIBUTING GUIDELINES for details on:
- 🐛 Bug reports
- ✨ Feature requests
- 🔧 Code contributions
- 📚 Documentation improvements
💬 Support
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📋 Releases: Version History & Changelogs
💝 Support Development
If you find Warden useful for your organization's security needs, please consider supporting its development.
Made with ❤️ for the Laravel community