README

This PHP Package provides a streamlined approach to gaining insights into the security and protection of your application's routes. In just a few seconds, you can assess critical aspects such as:

• Test Coverage: Comprehensive tests cover all routes to ensure reliability
• Authentication: Routes requiring authentication are clearly identified
• Scoped Bindings: Nested route models are scoped to maintain data integrity
• Permissions: Permission or policy checks enforce access control
• Middleware: Essential middleware is applied for security and request handling

Built for Laravel with extensible architecture for other PHP frameworks.

Requirements

• PHP: 8.1+

Documentation

Comprehensive documentation is available to help you get the most out of Audit Routes:

Getting Started

• Installation - Install and set up the package
• Quick Start - Get auditing in under 5 minutes
• Configuration - Customize settings and behavior

Guides

• Basic Usage - Essential patterns and common scenarios
• Advanced Usage - Complex configurations and custom scoring
• Custom Auditors - Build application-specific security checks
• Testing - PHPUnit assertions and CI integration
• CI Integration - Automate audits in your deployment pipeline
• Troubleshooting - Resolve common issues

Reference

• API Documentation
  • Assertions - Integrate route security validation directly into your test suite
  • Auditors - Auditors are the core components that analyze your routes
  • Commands - Available Artisan Commands
• Architecture
  • Auditor system - How the auditor system works internally
  • Overview - Understanding the internal architecture
• Examples
  • Integrations - Integrating with popular PHP frameworks
  • Real world - Real-world implementation examples

Community

• FAQ - Frequently asked questions
• Resources - Additional tools and resources

Quick Reference

• Quick Reference - Fast reference for commands and common patterns

Installation

You can install the package via Composer:

composer require mydevnl/audit-routes --dev

Optionally publish the configuration file:

php artisan vendor:publish --tag=audit-routes-config

Quick Start

Get your first audit running in seconds:

# Run a basic security audit
php artisan route:audit -vv

# Generate a detailed HTML report
php artisan route:audit-report

# Check authentication coverage
php artisan route:audit-auth -vv

For programmatic usage:

use MyDev\AuditRoutes\AuditRoutes;
use MyDev\AuditRoutes\Auditors\PolicyAuditor;
use MyDev\AuditRoutes\Auditors\MiddlewareAuditor;

$result = AuditRoutes::for($router->getRoutes())
    ->setBenchmark(50)
    ->run([
        PolicyAuditor::make()->setWeight(25),
        MiddlewareAuditor::make(['auth'])->setWeight(20),
    ]);

How It Works

Audit Routes uses a scoring system to evaluate route security:

• Built-in Auditors: PolicyAuditor, MiddlewareAuditor, PhpUnitAuditor, and more
• Configurable Weights: Customize importance of different security aspects
• Benchmark System: Set minimum scores for compliance (routes below benchmark are flagged)
• Multiple Outputs: Console, HTML reports, JSON exports for different workflows

Learn more about the Architecture and Auditor System.

Available Commands

The package provides several built-in commands to help you get started quickly:

• route:audit - Comprehensive route security analysis
• route:audit-report - Generate detailed HTML audit reports
• route:audit-test-coverage - Analyze test coverage for routes
• route:audit-auth - Focus on authentication middleware analysis

For detailed usage examples and command-line options, see the Basic Usage Guide.

Quick Reference

# Basic audit with detailed output
php artisan route:audit -vv

# High security standards
php artisan route:audit --benchmark 75 -vv

# Generate HTML report
php artisan route:audit-report

# Check authentication coverage
php artisan route:audit-auth -vv

# Verify test coverage
php artisan route:audit-test-coverage --benchmark 1 -vv

# Export results for CI/CD
php artisan route:audit --benchmark 50 --export json --filename security-audit.json

Testing Integration

The package includes PHPUnit assertions for integrating route security checks directly into your test suite. Use the AssertsAuditRoutes trait to enforce security standards as part of your CI/CD pipeline.

See the Testing Guide for comprehensive examples and best practices.

Troubleshooting

Common issues:

• No routes found? Ensure your Laravel application has defined routes and clear route cache: php artisan route:clear
• Permission errors? Check that storage/exports/audit-routes/ is writable: chmod -R 775 storage/
• Configuration issues? Verify your config/audit-routes.php settings match your project structure

For detailed troubleshooting and solutions, see the Troubleshooting Guide or FAQ.

Contributing

We welcome contributions to this project! If you have ideas for improvements or find bugs, please submit them as issues on GitHub. We highly appreciate and encourage community participation.

For additional help or questions, feel free to reach out via GitHub issues.

Learn more about contributing.

Security Vulnerabilities

If you discover any security vulnerabilities, please report them immediately. All security-related issues will be addressed with the highest priority.

License

This package is open-sourced software licensed under the MIT license.

We're still in development

Please be aware that the most stable release is an beta release and may be unstable. The roadmap will be published soon. Follow mydevnl to stay updated!

May your routes be flawless! 🔒✨