Pledge Symfony Routing Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require ctors/pledge-symfony-routing
   

   Ensure ext/pledge is installed on OpenBSD (see pecl-pledge).

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       ctors\PledgeSymfonyRoutingBundle\PledgeSymfonyRoutingBundle::class => ['all' => true],
   ];
   

3. First Use Case Apply #[Pledge] and #[Unveil] to a controller method:

   use ctors\PledgeSymfonyRoutingBundle\Attribute\Pledge;
   use ctors\PledgeSymfonyRoutingBundle\Attribute\Unveil;
   
   class SecureController extends AbstractController {
       #[Route('/secure', name: 'secure')]
       #[Pledge('stdio rpath')]
       #[Unveil('/var/log', 'rw')]
       public function secureEndpoint(): Response {
           return new Response('Secure!');
       }
   }
   

Implementation Patterns

Workflows

1. Granular Route Security Apply #[Pledge]/#[Unveil] per route or controller:

   // Controller-level (applies to all routes)
   #[Pledge('stdio rpath')]
   class SecureController extends AbstractController { ... }
   
   // Method-level (overrides controller-level)
   #[Pledge('stdio rpath inet')]
   public function dbEndpoint(): Response { ... }
   

2. Dynamic Unveil Paths Use __DIR__ for relative paths:

   #[Unveil(__DIR__.'/../storage', 'rwc')]
   

3. Fallback Pledges Define default pledges in config/packages/pledge_symfony_routing.yaml:

   pledge_symfony_routing:
       default_pledge: 'stdio rpath'
   

Integration Tips

• PHP-FPM Configuration Set pm.max_requests = 1 in www/conf.php-fpm.conf to avoid process reuse.
• Dependency Injection Inject services with restricted pledges (e.g., database clients):

  #[Pledge('inet')]
  public function __construct(private EntityManager $em) { ... }
  

• Testing Mock pledge()/unveil() calls in unit tests using PHPUnit extensions.

Gotchas and Tips

Pitfalls

1. Overly Restrictive Pledges

   • #[Pledge('stdio')] blocks all file operations. Use rpath/wpath for filesystem access.
   • Fix: Test with pledge('stdio rpath', ...) in development.

2. Unveil Order Matters

   • Paths must be unveiled before being accessed. Unveiling / last is common:

   #[Unveil('/htdocs/storage', 'rwc')]
   #[Unveil('/', 'r')] // Allow reading other files
   

3. FPM Pool Isolation

   • Reusing processes with different pledges breaks security. Always set pm.max_requests = 1.

4. Missing ext/pledge

   • Symptom: Class 'ctors\PledgeSymfonyRoutingBundle\Attribute\Pledge' not found.
   • Fix: Install pecl-pledge and restart PHP-FPM.

Debugging

• Check Pledge Failures OpenBSD logs pledge violations to /var/log/system.log. Use:

  tail -f /var/log/system.log | grep pledge
  

• Temporary Disable Pledges For debugging, use:

  #[Pledge('')] // Disables all pledges (dev-only!)
  

Extension Points

1. Custom Attributes Extend the bundle by creating your own attributes (e.g., #[DbPledge]):

   #[Attribute]
   class DbPledge implements PledgeInterface {
       public function getPledge(): string { return 'inet'; }
   }
   

2. Event Listeners Listen to kernel.controller to dynamically adjust pledges:

   $event->getController()->addAttribute(new Pledge('stdio rpath'));
   

3. Global Configuration Override defaults in config/packages/pledge_symfony_routing.yaml:

   pledge_symfony_routing:
       default_unveils:
           - { path: '/var/log', mode: 'rw' }