Warden

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, ensuring your projects remain secure from development to production.

🚀 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
• FAQ

---

🚀 Installation

To install Warden, use Composer:

composer require dgtlss/warden

Publish configuration:

php artisan vendor:publish --tag="warden-config"

This creates config/warden.php with all available options.

Note: The package includes .idea in .gitignore for improved support with IntelliJ IDEA and JetBrains IDEs.

---

⚡ Quick Start

Dive into Warden's powerful security auditing capabilities with these simple commands:

Basic Security Audit

Run a comprehensive security scan of your Laravel application:

php artisan warden:audit

With NPM Dependencies

Include JavaScript vulnerabilities in your audit:

php artisan warden:audit --npm

JSON Output for CI/CD

Generate machine-readable reports for automated pipelines:

php artisan warden:audit --output=json --severity=high

Silent Mode (No Notifications)

Perform audits without triggering 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

• Enhanced debug mode auditing: Accurately detects development packages in production by scanning vendor/composer/installed.json
• 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

✅ Email

• 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

1. Parallel Execution: Enabled by default for 5x speed improvement
2. Intelligent Caching: Configurable cache duration prevents redundant API calls
3. Severity Filtering: Focus resources on critical issues

Audit Results

Exit Codes:

• 0: No vulnerabilities found
• 1: Vulnerabilities detected
• 2: Audit process failures

Severity Levels:

• critical: Immediate attention required
• high: Address as soon as possible
• medium: Should be reviewed and fixed
• low: 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',
],

---

📈 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

---

❓ FAQ

How does Warden differ from built-in Composer audit?

Warden extends beyond Composer audit with NPM scanning, environment checks, storage permissions, Laravel-specific configurations, and custom audit rules for comprehensive security monitoring.

Can Warden run in CI/CD without notifications?

Yes! Use the --silent flag to suppress notifications while still generating reports for your pipeline.

What are the performance impacts?

Minimal! Parallel execution and intelligent caching ensure audits complete in seconds, with configurable timeouts and retry logic.

How do I handle false positives?

Use severity filtering (--severity=high) and custom audits to tune findings for your organization's security policies.

Is my data secure?

Absolutely. Warden processes everything locally - no external data transmission except for configured notification webhooks.

---

🛠️ 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

⭐ Star on GitHub | 📦 Packagist | 🐦 Follow Updates