Pledge Symfony Routing Laravel Package

Technical Evaluation

Architecture Fit

• Niche Use Case: The package is highly specialized for OpenBSD systems, leveraging pledge() and unveil() syscalls to enforce strict process capabilities and filesystem access controls. This is not a general-purpose Laravel/PHP solution but rather a security-hardening layer for Symfony applications running on OpenBSD.
• Symfony-Centric: Designed for Symfony’s attribute-based routing system (#[Route]). Laravel compatibility is indirect—it would require a bridge layer (e.g., a custom middleware or route service provider) to translate Laravel’s routing to Symfony’s attribute system.
• Security-First: Aligns with defense-in-depth principles by restricting process capabilities at the route level, but not a replacement for broader security measures (e.g., OpenBSD’s pledge in php.ini or FPM pools).

Integration Feasibility

• Low Effort for Symfony: Plugs into Symfony’s existing attribute system with minimal configuration. No Laravel-native integration exists, requiring custom development.
• OpenBSD Dependency: Hard blocker—ext/pledge is OpenBSD-only (no Linux/macOS/Windows support). Even if Laravel were compatible, the underlying syscalls are unavailable outside OpenBSD.
• PHP-FPM Requirement: Mandates pm.max_requests = 1 to prevent process reuse, which may impact performance in high-throughput environments.

Technical Risk

• Vendor Lock-In: Tight coupling to OpenBSD’s syscalls and Symfony’s attribute system. No abstraction layer for portability.
• Debugging Complexity: pledge()/unveil() failures are binary (success/failure) with minimal error context. Debugging misconfigured routes could be painful.
• Laravel Routing Mismatch: Laravel’s route definitions (e.g., Route::get(), closures, or controller methods without attributes) cannot natively use these annotations. Workarounds (e.g., middleware) would add overhead.
• Performance Overhead: Fine-grained pledge() calls per request may increase context-switching if not optimized (e.g., shared pledges across routes).

Key Questions

1. Is OpenBSD the Target OS?
   • If not, this package is incompatible. If yes, proceed with Symfony integration.
2. Can Laravel Routes Be Mapped to Symfony Attributes?
   • Requires a custom route resolver or middleware to translate Laravel routes to Symfony’s attribute system.
3. What’s the Security Tradeoff?
   • Does the team need per-route capability restrictions, or is a global pledge() in php.ini sufficient?
4. How Will Performance Be Monitored?
   • pm.max_requests = 1 may require horizontal scaling (more FPM workers) to maintain throughput.
5. Is There a Fallback for Non-OpenBSD?
   • Should the system gracefully degrade (e.g., log warnings) or fail fast if pledge() is unavailable?

Integration Approach

Stack Fit

• Symfony: Native fit—designed for Symfony’s attribute routing. Minimal changes needed beyond installation.
• Laravel: Poor fit—requires custom middleware or a route service provider to:
  • Parse Laravel routes and apply Pledge/Unveil annotations.
  • Example: A middleware that checks route metadata and calls pledge()/unveil() before execution.
• OpenBSD PHP Runtime: Hard dependency—must run on OpenBSD with ext/pledge enabled. No polyfill for other systems.

Migration Path

1. Symfony Projects:
   • Install the bundle (composer require ctors/pledge-symfony-routing).
   • Add #[Pledge]/#[Unveil] to controllers/actions.
   • Configure PHP-FPM (pm.max_requests = 1).
   • Test with pledge()-compliant routes (e.g., restrict inet for DB calls).
2. Laravel Projects:
   • Option A (Recommended for New Projects): Migrate to Symfony’s attribute routing (e.g., via Symfony UX) to leverage native support.
   • Option B (Legacy Laravel): Build a custom route resolver:

     // app/Providers/RouteServiceProvider.php
     public function boot()
     {
         Route::get('/example', function () {
             // ...
         })->middleware(PledgeMiddleware::class);
     }
     

     • Middleware would inspect route metadata (e.g., stored in a closure attribute or route model) and apply pledge()/unveil().
   • Option C (Hybrid): Use Symfony’s HttpKernel as a micro-framework within Laravel (advanced, high coupling).

Compatibility

• Symfony: Fully compatible with Symfony 5.4+ (attribute routing).
• Laravel: No OOTB compatibility—requires custom glue code.
• PHP Versions: Depends on pecl-pledge (e.g., PHP 8.2 in the example). Version alignment needed between PHP, Symfony/Laravel, and pecl-pledge.
• OpenBSD-Specific: No cross-platform support. Even if Laravel were adapted, pledge()/unveil() are OpenBSD-exclusive.

Sequencing

1. Infrastructure Setup:
   • Install pecl-pledge on OpenBSD.
   • Configure PHP-FPM (pm.max_requests = 1).
2. Framework Integration:
   • For Symfony: Add bundle, annotate routes.
   • For Laravel: Implement middleware/resolver.
3. Testing:
   • Verify pledge() failures (e.g., unveil() to a restricted path should return 403).
   • Load-test with pm.max_requests = 1 to ensure no process leaks.
4. Gradual Rollout:
   • Start with non-critical routes (e.g., static assets with minimal pledges).
   • Expand to sensitive endpoints (e.g., DB access with inet pledge).

Operational Impact

Maintenance

• Symfony:
  • Low maintenance—bundle updates align with Symfony’s release cycle.
  • Monitoring: Log pledge()/unveil() failures (e.g., via Symfony’s error handler).
• Laravel:
  • High maintenance—custom middleware/resolver requires ongoing upkeep (e.g., route metadata sync).
  • Documentation burden: Must clearly define how Pledge/Unveil are applied to Laravel routes.
• OpenBSD-Specific:
  • Dependency management: pecl-pledge updates may require PHP/FPM restarts.
  • Security patches: OpenBSD’s pledge() syscall is stable but niche—few community resources for troubleshooting.

Support

• Symfony:
  • Limited community support (2 stars, 0 dependents). Issues may require direct engagement with the maintainer.
  • Debugging: pledge() failures are binary—tools like strace or OpenBSD’s pledge -v may help.
• Laravel:
  • No upstream support—custom integration is team’s responsibility.
  • Error handling: Must design user-friendly messages for pledge() violations (e.g., "Route blocked: missing inet pledge").
• OpenBSD:
  • Niche expertise required. Support may need OpenBSD-specific forums (e.g., misclug).

Scaling

• Performance:
  • pm.max_requests = 1 prevents process reuse, increasing memory usage. May require:
    • More FPM workers (vertical scaling).
    • Optimized pledge() calls (e.g., reuse pledges across similar routes).
  • Cold starts: Each request may incur a pledge setup cost (mitigate with connection pooling).
• Horizontal Scaling:
  • Stateless routes (e.g., API endpoints) scale well.
  • Stateful routes (e.g., file uploads with rwc unveil) may need shared storage (e.g., NFS with unveil permissions).
• Database Access:
  • inet pledge for TCP DB connections may limit connection pooling (e.g., MariaDB’s unix_socket is pledge-free).

Failure Modes