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.

🚀 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

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

dgtlss / warden

Maintainers

Details

README

🚀 Key Features

✅ Core Security Audits

✅ Performance & Scalability

✅ Integration & Automation

📋 Table of Contents

🚀 Installation

⚡ Quick Start

Basic Security Audit

With NPM Dependencies

JSON Output for CI/CD

Silent Mode (No Notifications)

⚙️ Configuration

Environment Variables

🔔 Notifications

⚡ Performance

⏰ Scheduling

📊 Output & Filtering

🔍 Security Audits

1. Composer Dependencies

2. NPM Dependencies

3. Environment Configuration

4. Storage & Permissions

5. Laravel Configuration

6. PHP Syntax Analysis

💡 Usage Examples

Basic Commands

Output Formats

Advanced Usage

🔔 Notifications

✅ Slack (Recommended)

✅ Discord

✅ Microsoft Teams

✅ Email

Multiple Channels

🔧 Custom Audits

1. Implement Custom Audit

2. Register Custom Audit

⏰ Scheduling

Enable Automated Audits

Configure Schedule

Laravel Cron Setup

🔄 CI/CD Integration

GitHub Actions

GitLab CI

Jenkins

🎯 Advanced Features

Performance Optimization

Audit Results

Configuration Examples

📈 Roadmap

Coming Soon

❓ FAQ

How does Warden differ from built-in Composer audit?

Can Warden run in CI/CD without notifications?

What are the performance impacts?

How do I handle false positives?

Is my data secure?

🛠️ Troubleshooting

Common Issues

📄 License

🤝 Contributing

💬 Support

💝 Support Development