Scout Laravel Package

Getting Started

Minimal Steps to Begin

1. Clone the Repository

   git clone https://github.com/DirectoryTree/Scout
   cd Scout
   

2. Install Dependencies

   composer install
   

3. Configure LDAP Connection Edit .env to include your LDAP server details:

   LDAP_HOST=your-ldap-server
   LDAP_PORT=389
   LDAP_BASE_DN=dc=example,dc=com
   LDAP_USERNAME=cn=admin,dc=example,dc=com
   LDAP_PASSWORD=your-password
   

4. Run Migrations

   php artisan migrate
   

5. Set Up Scheduling (Optional) Configure a cron job to run the scanner periodically (e.g., every 5 minutes):

   * * * * * cd /path/to/scout && php artisan scout:scan
   

6. Access the Web Interface Start the Laravel development server:

   php artisan serve
   

   Navigate to http://localhost:8000 to view the dashboard.

First Use Case: Monitoring LDAP Changes

• Use the scout:scan Artisan command to manually trigger an LDAP audit.
• Check the scout:notifications table for detected changes (e.g., password resets, attribute modifications).
• Customize notifications via the Notifiers section in the admin panel.

Implementation Patterns

Core Workflows

1. LDAP Scanning

   • Schedule regular scans using Laravel’s task scheduling (app/Console/Kernel.php):

     $schedule->command('scout:scan')->everyFiveMinutes();
     

   • Extend the scanner logic in app/Scout/Scanners/LdapScanner.php to add custom checks.

2. Notification System

   • Define custom notification rules in app/Scout/Notifications/NotificationRule.php:

     public function shouldNotify($change)
     {
         return $change->attribute === 'userPassword';
     }
     

   • Register new notifiers in config/scout.php:

     'notifiers' => [
         'email' => \DirectoryTree\Scout\Notifications\EmailNotifier::class,
         'slack' => \App\Notifications\SlackNotifier::class,
     ],
     

3. Password Management

   • Reset passwords via the web UI (/password-reset route) and log changes:

     // In a controller
     $user = \DirectoryTree\LdapRecord\Models\User::find($id);
     $user->setPassword('temp123!');
     $user->save();
     

   • Trigger expiry notifications by extending app/Scout/Notifications/PasswordExpiryNotifier.php.

4. Integration with Laravel

   • Use Scout’s events to react to LDAP changes:

     // In EventServiceProvider
     public function boot()
     {
         \DirectoryTree\Scout\Events\LdapChangeDetected::class => [
             \App\Listeners\LogLdapChange::class,
         ],
     }
     

Integration Tips

• Custom LDAP Attributes: Extend DirectoryTree\LdapRecord\Models\Model to map custom attributes.
• API Access: Build an API endpoint to fetch recent changes:

  Route::get('/api/ldap-changes', function () {
      return \DirectoryTree\Scout\Models\Change::latest()->take(100)->get();
  });
  

• Webhooks: Use Laravel’s Http client to send changes to external systems:

  use Illuminate\Support\Facades\Http;
  
  Http::post('https://external-api.com/webhook', [
      'change' => $change->toArray()
  ]);
  

Gotchas and Tips

Pitfalls

1. LDAP Connection Issues

   • Ensure the PHP LDAP extension is enabled (php -m | grep ldap).
   • Debug connection errors by checking .env credentials and firewall rules.
   • Use php artisan scout:test-connection to verify LDAP access.

2. Performance with Large Directories

   • Limit scan depth in config/scout.php:

     'scan' => [
         'depth' => 3, // Reduce if scanning large trees
         'batch_size' => 100,
     ],
     

   • Cache frequent queries using Laravel’s cache:

     $changes = Cache::remember('ldap_changes', now()->addHours(1), function () {
         return \DirectoryTree\Scout\Models\Change::all();
     });
     

3. Notification Delays

   • Queue notifications to avoid timeouts:

     // In NotificationRule
     public function notify($change)
     {
         Notification::route('mail', $change->user->email)
                     ->notify(new LdapChangeNotification($change));
     }
     

   • Monitor queues with php artisan queue:work.

4. Password Reset Security

   • Validate temporary passwords in app/Scout/Policies/PasswordPolicy.php:

     public function passes($password)
     {
         return preg_match('/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/', $password);
     }
     

Debugging Tips

• Log LDAP Queries: Enable debug mode in config/ldaprecord.php:

  'debug' => env('LDAP_DEBUG', false),
  

• Test Changes Locally: Use Tinker to simulate LDAP changes:

  php artisan tinker
  >>> $user = \DirectoryTree\LdapRecord\Models\User::find(1);
  >>> $user->setAttribute('mail', 'new@example.com');
  >>> $user->save();
  

• Check Scout Logs: Review storage/logs/laravel.log for scanner errors.

Extension Points

1. Custom Scanners

   • Create a new scanner by extending DirectoryTree\Scout\Contracts\Scanner:

     namespace App\Scout\Scanners;
     
     use DirectoryTree\Scout\Contracts\Scanner;
     
     class CustomScanner implements Scanner
     {
         public function scan()
         {
             // Custom logic here
         }
     }
     

   • Register it in app/Providers/ScoutServiceProvider.php:

     $this->app->bind(
         \DirectoryTree\Scout\Contracts\Scanner::class,
         App\Scout\Scanners\CustomScanner::class
     );
     

2. Plugin System

   • Build plugins for additional features (e.g., Active Directory-specific rules) by publishing assets:

     php artisan vendor:publish --provider="DirectoryTree\Scout\ScoutServiceProvider"
     

   • Override views in resources/views/vendor/scout/.

3. Webhook Events

   • Listen for ldap.change.detected events to trigger external actions:

     // In EventServiceProvider
     \DirectoryTree\Scout\Events\LdapChangeDetected::class => [
         \App\Listeners\SendWebhook::class,
     ];