Getting Started

Minimal Steps to Begin

Installation

composer require artflow-studio/laravel-security
php artisan vendor:publish --provider="ArtflowStudio\Security\SecurityServiceProvider" --tag="security-config"

First Scan
```
php artisan security:scan
```
- Review the interactive CLI output for detected vulnerabilities.
- Focus on Critical and High severity issues first.

Quick Wins

Run a dry-run to preview fixes:
```
php artisan security:fix --dry-run
```

Generate an HTML report for stakeholders:

php artisan security:scan --format=html --output=report.html

Where to Look First

Default Config: config/security.php (adjust scanner thresholds, exclusions, or auto-fix rules).
CLI Help: php artisan security:scan --help (lists all scanners and options).
Livewire Focus: Run php artisan security:scan --scanner=livewire to target Livewire-specific issues.

Implementation Patterns

Daily Workflow Integration

Pre-Commit Hook Add to .git/hooks/pre-commit (or use Laravel Forge/Envoyer):

#!/bin/bash
php artisan security:scan --severity=critical --format=json | jq -e '.findings | length > 0' && exit 1 || exit 0

Blocks commits with Critical issues.

CI/CD Pipeline

# Example GitHub Actions step
- name: Security Scan
  run: |
    php artisan security:scan --format=json --output=scan-results.json
    # Upload artifact or fail build if critical issues exist

Livewire Development Loop
- Run incremental scans during development:
```
php artisan security:scan --scanner=livewire --path=app/Http/Livewire
```
- Use --auto-fix for safe fixes (e.g., missing useForm in Livewire components):
```
php artisan security:fix --scanner=livewire --dry-run
```

Common Patterns

Exclude Directories:

// config/security.php
'excludes' => [
    'vendor/**',
    'storage/**',
    'tests/**',
],

Custom Severity Thresholds:

php artisan security:scan --severity=high,critical

Focused Scans:

# Scan only for SQL injection risks
php artisan security:scan --scanner=sql

# Scan only Livewire components
php artisan security:scan --scanner=livewire

Integration Tips

Laravel Forge/Envoyer: Add a post-deploy hook to run scans and email reports:
```
php artisan security:scan --format=email --to=security-team@example.com
```

Laravel Telescope: Log scan results to Telescope for historical tracking:

// In SecurityServiceProvider
$this->app->booting(function () {
    if (config('security.track_in_telescope')) {
        \ArtflowStudio\Security\Telescope\SecurityScan::observe(\ArtflowStudio\Security\Models\Scan::class);
    }
});

Livewire Component Testing: Pair with Pest/Laravel TestKit to verify fixes:

use ArtflowStudio\Security\Tests\LivewireSecurityTestCase;

public function test_livewire_component_security()
{
    $this->scanLivewireComponent(MyComponent::class)
         ->assertNoVulnerabilities();
}

Gotchas and Tips

Pitfalls and Debugging

False Positives
- Issue: Scanners may flag custom patterns (e.g., {{ $user->name }} in Blade) as XSS risks.
- Fix: Use excludes in config or whitelist patterns:
```
'whitelists' => [
    'Blade' => [
        '/\{\{\s*\$user->[a-zA-Z0-9_]+\s*\}\}/' => 'Safe user property access',
    ],
],
```
Performance Overhead
- Issue: Full scans on large apps may time out.
- Fix:
  - Run scans in parallel (if supported):
```
php artisan security:scan --parallel
```
  - Exclude heavy directories (e.g., storage/framework/views).
Auto-Fix Limitations
- Issue: Some fixes may break functionality (e.g., auto-adding useForm to a Livewire component with existing state).
- Fix: Always use --dry-run first and review changes:
```
php artisan security:fix --scanner=livewire --dry-run --diff
```
Livewire 3 Quirks
- Issue: Scanners may misidentify public properties in Livewire as security risks.
- Fix: Configure Livewire-specific rules:
```
'livewire' => [
    'ignore_public_properties' => ['id', 'createdAt'], // Whitelist safe properties
],
```

Debugging Tips

Verbose Output:
```
php artisan security:scan --verbose
```

Scan a Single File:

php artisan security:scan --path=app/Http/Controllers/AuthController.php

Inspect Scanner Logic: Review the ArtflowStudio\Security\Scanners namespace for custom rules or overrides.

Extension Points

Custom Scanners Create a new scanner by extending ArtflowStudio\Security\Contracts\Scanner:

namespace App\Security\Scanners;

use ArtflowStudio\Security\Contracts\Scanner;
use ArtflowStudio\Security\Severity;

class CustomScanner implements Scanner
{
    public function scan(string $path): array
    {
        return [
            new Finding(
                path: $path,
                description: 'Custom security rule violated',
                severity: Severity::High,
                fix: 'Apply custom fix...'
            ),
        ];
    }
}

'scanners' => [
    // ...
    App\Security\Scanners\CustomScanner::class,
],

Override Findings Extend the Finding class to add custom metadata:

namespace App\Security;

use ArtflowStudio\Security\Finding as BaseFinding;

class Finding extends BaseFinding
{
    public function __construct(array $data)
    {
        parent::__construct($data);
        $this->metadata['custom'] = 'value';
    }
}

Hook into Fixes Override the Fix class to add pre/post-fix logic:

namespace App\Security\Fixes;

use ArtflowStudio\Security\Fix as BaseFix;

class CustomFix extends BaseFix
{
    public function apply(): bool
    {
        // Custom logic before applying fix
        $result = parent::apply();
        // Custom logic after applying fix
        return $result;
    }
}

Configuration Quirks

Severity Mapping: Ensure config/security.php maps severities correctly to your team’s workflow (e.g., Critical = P0, High = P1).
Path Handling: Use forward slashes (/) in excludes/includes even on Windows (Laravel normalizes paths).
Rate Limiting: For CI/CD, add a --max-runtime flag to avoid long-running scans:
```
php artisan security:scan --max-runtime=300
```

Pro Tips

Combine with Other Tools: Use alongside phpstan, psalm, and laravel-shift for layered security.
Document Findings: Export reports to Confluence/Jira via the --format=markdown output.

Automate Remediation: Chain fixes with Git commits:

php artisan security:fix --scanner=sql --auto-commit

Monitor Drift: Track scan results over time to identify recurring issues:
```
php artisan security:history --since=1month
```

Laravel Security Laravel Package