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

1.3.0 2025-08-01 15:28 UTC

This package is auto-updated.

Last update: 2025-08-01 15:33:12 UTC


README

Latest Version on Packagist Total Downloads License PHP Version Require GitHub repo size

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

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

✅ 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',
],

🆕 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

💝 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