Migration

🔄 Migration Guide

This guide helps you migrate between versions of Laravel Safeguard and from other security auditing tools.

📈 Version Migrations

From v1.x to v2.x

Configuration Changes

Old Configuration (v1.x):

// config/safeguard.php
return [
    'enabled_rules' => [
        'app-debug-check',
        'app-key-check',
    ],
    'environments' => ['production'],
];

New Configuration (v2.x):

// config/safeguard.php
return [
    'rules' => [
        'app-debug-false-in-production',
        'app-key-is-set',
    ],
    'environments' => [
        'production' => ['app-debug-false-in-production'],
        'development' => ['app-debug-can-be-true'],
    ],
];

Command Changes

v1.x Command	v2.x Command	Notes
safeguard:run	safeguard:check	Command renamed
safeguard:scan	safeguard:check --verbose	Verbose mode added
safeguard:rules	safeguard:list	Command renamed

Rule Name Changes

v1.x Rule Name	v2.x Rule Name	Migration
app-debug-check	app-debug-false-in-production	Automatic
app-key-check	app-key-is-set	Automatic
csrf-check	csrf-protection-enabled	Automatic

Migration Script

# Download migration script
curl -o migrate-v2.php https://raw.githubusercontent.com/yourorg/laravel-safeguard/main/scripts/migrate-v2.php

# Run migration
php migrate-v2.php

From v2.x to v3.x

New Features

• Environment-specific rules
• Custom rule namespacing
• Performance optimizations
• New output formats

Breaking Changes

1. Configuration Structure:

// Old (v2.x)
'rules' => ['rule-name']

// New (v3.x)
'rules' => [
    'production' => ['rule-name'],
    'development' => ['other-rule'],
]

2. Custom Rule Interface:

// Old (v2.x)
class CustomRule implements RuleInterface
{
    public function check(): bool
    {
        return true;
    }
}

// New (v3.x)
class CustomRule extends BaseRule
{
    public function check(): RuleResult
    {
        return RuleResult::passed('Check successful');
    }
}

🔄 From Other Tools

From Laravel Security Checker

# Old command
vendor/bin/security-checker security:check composer.lock

# New equivalent
php artisan safeguard:check --only=dependencies

Configuration Migration:

// Create new Safeguard config
php artisan vendor:publish --tag=safeguard-config

// Add equivalent rules
'rules' => [
    'dependencies-vulnerability-check',
    'composer-audit',
]

From Enlightn

Enlightn Security Rules → Safeguard Equivalent:

Enlightn Rule	Safeguard Rule	Notes
AppDebugAnalyzer	app-debug-false-in-production	Direct equivalent
AppKeyAnalyzer	app-key-is-set	Direct equivalent
CSRFAnalyzer	csrf-protection-enabled	Enhanced version
DatabaseAnalyzer	database-security	More comprehensive

Migration Script:

<?php
// migrate-from-enlightn.php

$enlightnConfig = config('enlightn');
$safeguardRules = [];

// Map Enlightn analyzers to Safeguard rules
$mapping = [
    'AppDebugAnalyzer' => 'app-debug-false-in-production',
    'AppKeyAnalyzer' => 'app-key-is-set',
    'CSRFAnalyzer' => 'csrf-protection-enabled',
    // Add more mappings...
];

foreach ($enlightnConfig['analyzers'] as $analyzer) {
    if (isset($mapping[$analyzer])) {
        $safeguardRules[] = $mapping[$analyzer];
    }
}

// Generate new Safeguard config
file_put_contents(
    config_path('safeguard.php'),
    '<?php return ' . var_export(['rules' => $safeguardRules], true) . ';'
);

From PHPStan Security

# Old PHPStan security check
vendor/bin/phpstan analyze --configuration=phpstan-security.neon

# Add equivalent Safeguard rules
php artisan safeguard:check --only=code-analysis

🔧 Step-by-Step Migration

1. Install Laravel Safeguard

composer require yourorg/laravel-safeguard

2. Publish Configuration

php artisan vendor:publish --tag=safeguard-config

3. Migrate Existing Configuration

From Custom Security Scripts:

// config/safeguard.php
return [
    'rules' => [
        // Map your existing checks to Safeguard rules
        'app-debug-false-in-production',
        'app-key-is-set',
        'database-encryption-enabled',
        'session-security-configured',
    ],
    'custom_rules' => [
        // Add your custom security logic
        App\Security\CustomDatabaseRule::class,
        App\Security\CustomFilePermissionRule::class,
    ],
];

4. Update CI/CD Pipelines

GitHub Actions:

# Old workflow
- name: Run security checks
  run: vendor/bin/old-security-tool

# New workflow
- name: Run Laravel Safeguard
  run: php artisan safeguard:check --format=ci --fail-on-error

5. Migrate Custom Rules

Old Custom Rule:

class OldSecurityRule
{
    public function execute()
    {
        // Old logic
        return $this->isSecure();
    }
}

New Safeguard Rule:

class NewSafeguardRule extends BaseRule
{
    public function name(): string
    {
        return 'custom-security-check';
    }
    
    public function check(): RuleResult
    {
        // Migrated logic
        if ($this->isSecure()) {
            return RuleResult::passed('Security check passed');
        }
        
        return RuleResult::failed('Security issue detected');
    }
}

6. Test Migration

# Test with dry-run
php artisan safeguard:check --dry-run

# Compare with old tool results
php artisan safeguard:check --format=json > new-results.json
old-security-tool --format=json > old-results.json

# Verify coverage
php artisan safeguard:list

🚨 Common Migration Issues

1. Missing Rules

Problem: Some security checks from your old tool aren't available.

Solution: Create custom rules or request new built-in rules.

// Create custom rule for missing functionality
php artisan make:safeguard-rule MissingSecurityCheck

2. Different Output Format

Problem: CI/CD expects specific output format.

Solution: Use format options or create custom formatter.

# Use compatible format
php artisan safeguard:check --format=junit

# Or create custom format in configuration

3. Performance Differences

Problem: New tool is slower/faster than expected.

Solution: Adjust performance settings.

'performance' => [
    'parallel_execution' => true,
    'cache_enabled' => true,
],

✅ Migration Checklist

• Install Laravel Safeguard
• Migrate configuration
• Map existing rules to Safeguard equivalents
• Create custom rules for missing functionality
• Update CI/CD pipelines
• Test in development environment
• Verify coverage matches old tool
• Deploy to staging
• Monitor performance
• Deploy to production
• Remove old security tool

📚 Related Documentation

• 🔧 Installation - Installing Laravel Safeguard
• ⚙️ Configuration - Configuration options
• 🎨 Custom Rules - Creating custom rules
• 🚀 CI/CD Integration - Pipeline integration

---

🏠 Home | 🔧 Installation | ⚙️ Configuration | 🎨 Custom Rules