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, 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
• Command Reference
• Configuration
• Security Audits
• Usage Examples
• Notifications
• Custom Audits
• Scheduling
• CI/CD Integration
• Advanced Features
• FAQ
• Troubleshooting

🚀 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

No Notifications

Run audits without sending notifications (useful for CI or local checks):

php artisan warden:audit --no-notify

Note: --silent still works for backward compatibility.

📌 Command Reference

Quick reference for all commands and options.

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

🔬 PHP Syntax Audit

WARDEN_PHP_SYNTAX_AUDIT_ENABLED=false   # Enable via warden:syntax or config

⏰ Scheduling

WARDEN_SCHEDULE_ENABLED=false
WARDEN_SCHEDULE_FREQUENCY=daily   # hourly|daily|weekly|monthly
WARDEN_SCHEDULE_TIME=03:00
WARDEN_SCHEDULE_TIMEZONE=UTC

🔍 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 --no-notify

# 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 [
            [
                'source' => 'Database Password Security',
                '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.4'
      
      - 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 --no-notify > 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, // seconds
],

'cache' => [
    'enabled' => true,
    'duration' => 3600, // 1 hour
],

'sensitive_keys' => [
    'DB_PASSWORD',
    'STRIPE_SECRET',
    'AWS_SECRET_ACCESS_KEY',
],

Output & severity: Use --output and --severity CLI options (not config). See Command Reference above.

📈 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 --no-notify to suppress notifications while still generating reports for your pipeline. (--silent also works.)

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