Security Debug Command Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require egulias/security-debug-command-bundle
   

   Add the bundle to config/bundles.php:

   Egulias\SecurityDebugCommandBundle\EguliasSecurityDebugCommandBundle::class => ['all' => true],
   

2. First Use Case: Run the security:debug:firewalls command to inspect firewall configurations:

   php bin/console security:debug:firewalls /login main anonymous
   

   Replace /login, main, and anonymous with your target URI, firewall name, and user type (e.g., user).

Where to Look First

• Command Reference: Check EguliasSecurityDebugCommandBundle/Command/ for available commands and their logic.
• Symfony Security Docs: Understand how firewalls, voters, and ACLs work in Symfony to interpret the output.
• Debugging Output: Focus on the security:debug:voters command for voter inspection, especially if authorization issues arise.

Implementation Patterns

Common Workflows

1. Debugging Access Denied Issues: Use security:debug:voters to inspect why a user is being denied access:

   php bin/console security:debug:voters /admin user ROLE_ADMIN
   

   • Pattern: Compare the output with your expected voter logic (e.g., VotersInterface::ACCESS_GRANTED).

2. Firewall Configuration Validation: Verify firewall mappings and listeners with:

   php bin/console security:debug:firewalls /api authenticated
   

   • Pattern: Cross-check with security.yaml to ensure URIs and firewalls align.

3. ACL Debugging (if enabled): Use security:debug:acl_voters or security:debug:acl_object to inspect ACL permissions:

   php bin/console security:debug:acl_object /object/123 MASK_EDIT
   

   • Pattern: Test with different masks (e.g., MASK_OWNER, MASK_EDIT) to validate object-level permissions.

Integration Tips

1. Symfony Events:

   • The bundle triggers events during debugging. If your listeners have side effects (e.g., logging, notifications), they may fire twice. Mitigate by:
     • Adding a flag (e.g., if (!$this->isDebugging())) in your listeners.
     • Using Symfony’s EventDispatcher to conditionally skip logic:

       if (!$event->isDebug()) { /* ... */ }
       

2. Custom Voters:

   • Extend AbstractVote or implement VoterInterface and test with:

     php bin/console security:debug:voters /custom-route user ROLE_CUSTOM
     

   • Tip: Use supportsAttribute() and voteOnAttribute() methods to ensure your voter logic matches the debug output.

3. Role Hierarchy:

   • Test role inheritance with security:debug:voters:

     php bin/console security:debug:voters /admin user ROLE_USER ROLE_ADMIN
     

   • Tip: Verify security.yaml role hierarchy (e.g., role_hierarchy: { ROLE_ADMIN: ROLE_USER }).

4. Token Impersonation:

   • The bundle fakes tokens for debugging. If you need to test with a real token (e.g., for OAuth), mock the TokenStorage service temporarily:

     $this->container->get('security.token_storage')->setToken($realToken);
     

Gotchas and Tips

Pitfalls

1. Double Event Firing:

   • Issue: Custom listeners or voters with side effects (e.g., sending emails, modifying data) may execute twice during debugging.
   • Fix: Add a debug flag to your logic:

     public function onKernelRequest(GetResponseEvent $event) {
         if (!$event->isDebug()) {
             // Your side-effect logic here
         }
     }
     

2. Outdated Output:

   • Issue: The bundle was last updated in 2017 and may not support newer Symfony versions (e.g., 5.x/6.x) out-of-the-box.
   • Fix:
     • Check compatibility with your Symfony version.
     • Fork the repository and update dependencies if needed (e.g., symfony/security-bundle).
     • Use symfony/debug-bundle as an alternative for modern Symfony versions.

3. ACL Limitations:

   • Issue: ACL-related commands (acl_voters, acl_object) may not work if ACL is not properly configured.
   • Fix: Ensure symfony/security-acl is installed and configured in security.yaml:

     security:
         access_control:
             - { path: ^/admin, roles: ROLE_ADMIN }
         acl:
             connection: default
     

4. Token Security Warning:

   • Issue: The bundle fakes credentials/tokens, which could expose sensitive data if misused.
   • Fix:
     • Never run debug commands in production.
     • Avoid using real credentials in debug commands (e.g., username: admin should be a test user).

Debugging Tips

1. Voter Logic:

   • If a voter returns ACCESS_ABSTAIN, the next voter in the chain decides. Use security:debug:voters to trace the chain:

     php bin/console security:debug:voters /route user ROLE_TEST --verbose
     

2. Firewall Mismatches:

   • If a URI isn’t matched, check:
     • The exact URI in the command (e.g., /login vs /login/).
     • Firewall order in security.yaml (first match wins).

3. Performance:

   • Debug commands can be slow for complex setups. Use --no-debug flag to skip verbose output:

     php bin/console security:debug:voters /route user ROLE_TEST --no-debug
     

4. Custom Commands:

   • Extend the bundle by creating a custom command that reuses its logic (e.g., EguliasSecurityDebugCommandBundle\Command\DebugVotersCommand).

Extension Points

1. Custom Voters/Listeners:

   • Override the bundle’s services to add your own debug logic. Example in config/services.yaml:

     services:
         App\Security\CustomDebugVoter:
             tags: { name: security.voter }
             arguments: ['@security.token_storage']
     

2. Event Subscribers:

   • Add a subscriber to filter or modify debug events:

     public static function getSubscribedEvents() {
         return [
             KernelEvents::REQUEST => 'onDebugRequest',
         ];
     }
     
     public function onDebugRequest(GetResponseEvent $event) {
         if ($event->isDebug()) {
             // Modify debug behavior
         }
     }
     

3. DataCollector Integration:

   • The bundle mentions a DataCollector feature. If enabled, ensure your config/packages/dev/security.yaml includes:

     security:
         debug: true