FAQ

❓ FAQ - Frequently Asked Questions

Welcome to the Laravel Safeguard FAQ! Here you'll find answers to the most common questions about installation, configuration, usage, and troubleshooting.

🔧 General Questions

What is Laravel Safeguard?

Laravel Safeguard is a configurable security audit package for Laravel applications. It acts like Pint, PHPStan, or Rector but for security and configuration auditing. It helps identify security issues, misconfigurations, and potential vulnerabilities before they reach production.

Why do I need Laravel Safeguard?

Common production issues that Laravel Safeguard helps prevent:

• ❌ Missing critical variables (APP_KEY, DB_PASSWORD, etc.)
• 🔓 Hardcoded secrets in code instead of environment variables
• 🚨 Inconsistencies between .env.example and .env
• ⚠️ Security misconfigurations (APP_DEBUG=true in production)
• 🔒 Insecure defaults that should be changed before going live

How is it different from other security tools?

Laravel Safeguard focuses specifically on configuration and environment security rather than code vulnerability scanning. It's complementary to tools like:

Tool	Focus	Laravel Safeguard
PHPStan	Static code analysis	✅ Configuration auditing
Psalm	Type checking	✅ Environment validation
Security scanners	Code vulnerabilities	✅ Security misconfigurations
Pint	Code formatting	✅ Security standards

Is Laravel Safeguard free?

Yes! Laravel Safeguard is open source and completely free to use in both personal and commercial projects.

📦 Installation & Setup

Can I use Laravel Safeguard in production?

Yes, but we recommend installing it as a development dependency (--dev) since it's primarily used for auditing and CI/CD processes:

composer require --dev grazulex/laravel-safeguard

Do I need to publish the configuration?

Publishing the configuration is optional but recommended for customization:

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

Without publishing, Laravel Safeguard will use sensible defaults.

What Laravel versions are supported?

Laravel Safeguard requires:

• PHP: 8.3 or higher
• Laravel: 12.19 or higher

Can I use it with older Laravel versions?

The current version is designed for Laravel 12.x. For older Laravel versions, you may need to:

• Use an older version of the package
• Manually adapt the configuration
• Check compatibility with your specific Laravel version

Does it work with Lumen?

Laravel Safeguard is primarily designed for full Laravel applications. While some features might work with Lumen, it's not officially supported.

⚙️ Configuration

How do I enable/disable specific rules?

Edit config/safeguard.php:

'rules' => [
    'app-key-is-set' => true,                    // ✅ Enabled
    'https-enforced-in-production' => false,    // ❌ Disabled
    'csrf-enabled' => true,                     // ✅ Enabled
],

Can I have different rules for different environments?

Yes! Use environment-specific configuration:

'environments' => [
    'production' => [
        'app-debug-false-in-production',
        'secure-cookies-in-production',
        'https-enforced-in-production',
        'database-connection-encrypted',
    ],
    'staging' => [
        'app-debug-false-in-production',
        'csrf-enabled',
    ],
    'local' => [
        'app-key-is-set',
        'storage-writable',
    ],
],

How do I add custom secret patterns?

Customize the secret_patterns array in your configuration:

'secret_patterns' => [
    '*_KEY',
    '*_SECRET',
    '*_TOKEN',
    '*_PASSWORD',
    'MY_CUSTOM_*',
    'COMPANY_API_*',
    'STRIPE_*',
    'AWS_*',
],

Can I exclude certain files or directories from scanning?

Currently, you can specify which paths to scan. To exclude paths, simply don't include them in scan_paths:

'scan_paths' => [
    'app/',
    'config/',
    'routes/',
    // 'tests/' - excluded by not listing it
    // 'vendor/' - excluded by not listing it
],

How do I configure different timeout settings?

Adjust performance settings in your configuration:

'performance' => [
    'max_scan_files' => 10000,
    'timeout_seconds' => 300,
    'memory_limit' => '512M',
    'parallel_processing' => true,
],

🚀 Usage

What's the difference between --env and --env-rules?

• --env=production: Sets the environment context but runs all enabled rules
• --env-rules: Uses only the rules defined for that specific environment

# Runs all enabled rules with production context
php artisan safeguard:check --env=production

# Runs only production-specific rules
php artisan safeguard:check --env=production --env-rules

How do I run only critical security checks?

Use the --severity option:

# Only critical issues
php artisan safeguard:check --severity=critical

# Critical and error level issues
php artisan safeguard:check --severity=critical,error

Can I run specific rules only?

Yes, use the --rules option:

php artisan safeguard:check --rules=app-key-is-set,csrf-enabled

What output formats are available?

Laravel Safeguard supports multiple output formats:

# CLI format (default, human-readable)
php artisan safeguard:check

# JSON format (machine-readable)
php artisan safeguard:check --format=json

# CI format (no colors, CI-friendly)
php artisan safeguard:check --format=ci

# JUnit XML format (for test integration)
php artisan safeguard:check --format=junit

# HTML format (for reports)
php artisan safeguard:check --format=html

How do I make security checks fail my CI/CD pipeline?

Use the --fail-on-error flag:

php artisan safeguard:check --fail-on-error

This will exit with code 1 if any security issues are found, causing your CI/CD pipeline to fail.

🏗️ Custom Rules

How do I create a custom rule?

Use the artisan command to generate a new rule:

php artisan safeguard:make-rule MyCustomRule

This creates a new rule class that you can customize:

<?php

namespace App\SafeguardRules;

use Grazulex\LaravelSafeguard\Contracts\SafeguardRule;
use Grazulex\LaravelSafeguard\SafeguardResult;

class MyCustomRule implements SafeguardRule
{
    public function id(): string
    {
        return 'my-custom-rule';
    }

    public function check(): SafeguardResult
    {
        // Your custom logic here
        return SafeguardResult::pass('Custom check passed');
    }
    
    // ... other required methods
}

Where should I put custom rules?

By default, custom rules go in app/SafeguardRules/. You can customize this path:

// config/safeguard.php
'custom_rules_path' => app_path('Security/Rules'),
'custom_rules_namespace' => 'App\\Security\\Rules',

How do I register custom rules?

Add them to your configuration:

'rules' => [
    // Built-in rules
    'app-key-is-set' => true,
    
    // Your custom rules
    'my-custom-rule' => true,
    'another-custom-rule' => false,
],

Can I organize custom rules in subdirectories?

Yes! You can organize rules by category:

app/SafeguardRules/
├── Authentication/
│   ├── PasswordPolicyRule.php
│   └── TwoFactorRule.php
├── Database/
│   └── DatabaseSecurityRule.php
└── Api/
    └── ApiSecurityRule.php

🚀 CI/CD Integration

How do I integrate with GitHub Actions?

Create .github/workflows/security.yml:

name: Security Checks
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3
      - name: Install dependencies
        run: composer install
      - name: Run security checks
        run: php artisan safeguard:check --fail-on-error

How do I integrate with GitLab CI?

Add to .gitlab-ci.yml:

security_check:
  stage: test
  image: php:8.3-cli
  script:
    - composer install
    - php artisan safeguard:check --fail-on-error --format=junit > security.xml
  artifacts:
    reports:
      junit: security.xml

Should I run security checks on every commit?

Yes, but consider a progressive approach:

1. Pull Requests: Run all security checks
2. Development branches: Run critical checks only
3. Main branch: Run comprehensive security audit

# For development branches
php artisan safeguard:check --severity=critical --fail-on-error

# For production deployments
php artisan safeguard:check --env=production --fail-on-error

📊 Performance & Optimization

Laravel Safeguard is slow on my large project. How can I optimize it?

Several optimization strategies:

1. Limit scan paths:

'scan_paths' => [
    'app/',
    'config/',
    // Remove 'vendor/', 'node_modules/', etc.
],

2. Reduce file scan limits:

'performance' => [
    'max_scan_files' => 5000, // Reduce from default
    'timeout_seconds' => 120,
],

3. Enable parallel processing:

'performance' => [
    'parallel_processing' => true,
],

4. Use rule caching:

php artisan safeguard:cache rebuild

Can I run only critical checks for faster execution?

Yes:

php artisan safeguard:check --severity=critical

How much memory does Laravel Safeguard use?

Memory usage depends on your project size. For most projects, it uses 50-200MB. For large projects, you can increase the memory limit:

'performance' => [
    'memory_limit' => '1G', // Increase if needed
],

🐛 Troubleshooting

"Command not found" error

If you get a "Command not found" error:

1. Check if the package is installed:

composer show grazulex/laravel-safeguard

2. Check if commands are available:

php artisan list | grep safeguard

3. Clear Laravel caches:

php artisan config:clear
php artisan cache:clear

"Config file not found" error

Make sure you've published the configuration:

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

Rules are not being detected

1. Check rule configuration:

// Make sure rules are enabled
'rules' => [
    'app-key-is-set' => true, // Should be true
],

2. Verify custom rules path:

'custom_rules_path' => app_path('SafeguardRules'),
'custom_rules_namespace' => 'App\\SafeguardRules',

3. Check rule class implementation:

// Must implement SafeguardRule interface
class MyRule implements SafeguardRule
{
    // Required methods must be implemented
}

Performance issues with large codebases

1. Reduce scan scope:

'scan_paths' => [
    'app/', // Only scan essential directories
    'config/',
],

2. Increase timeouts:

'performance' => [
    'timeout_seconds' => 600, // 10 minutes
    'max_scan_files' => 20000,
],

3. Use file patterns to exclude large files:

# In your CI script
find . -name \"*.log\" -delete # Remove log files
find . -name \"node_modules\" -type d -exec rm -rf {} + # Remove node_modules

False positives in secret detection

Configure more specific patterns or exclusions:

'secret_patterns' => [
    '*_KEY',
    '*_SECRET',
    '!TEST_*', // Exclude test-related patterns
    '!MOCK_*', // Exclude mock data
],

🔒 Security Concerns

Is Laravel Safeguard safe to use in production?

Yes, but install it as a dev dependency. Laravel Safeguard only reads your configuration and code - it doesn't modify anything.

Does it send data to external servers?

No. Laravel Safeguard runs entirely locally and doesn't send any data externally.

Can it expose sensitive information?

Laravel Safeguard is designed to detect sensitive information, not expose it. However:

• Be careful with output logs in CI/CD
• Don't commit security reports with sensitive data
• Use appropriate log retention policies

What if I have false positives for secrets?

You can:

1. Update patterns to be more specific
2. Use exclusion patterns for test data
3. Move test secrets to dedicated test files
4. Use environment variables even for test data

📚 Best Practices

How often should I run security checks?

Recommended frequency:

• ✅ Every commit (via CI/CD)
• ✅ Before deployments (mandatory)
• ✅ Weekly reports (comprehensive audit)
• ✅ Before major releases (full security review)

What rules should I enable first?

Start with critical rules:

1. app-key-is-set
2. app-debug-false-in-production
3. csrf-enabled
4. no-secrets-in-code

Then add environment-specific rules: 5. secure-cookies-in-production 6. env-file-permissions 7. database-connection-encrypted

How do I handle security failures in CI/CD?

Progressive approach:

1. Block deployment on critical issues
2. Warn but continue on medium issues
3. Report but allow informational issues

# Critical issues block deployment
php artisan safeguard:check --severity=critical --fail-on-error

# Medium issues create warnings
php artisan safeguard:check --severity=error || echo \"Warning: Security issues found\"

# Full report for review
php artisan safeguard:check --format=json > security-report.json

🆘 Still Need Help?

If you can't find the answer to your question:

1. 📖 Check the documentation: Wiki Home
2. 🐛 Search issues: GitHub Issues
3. 💬 Ask the community: GitHub Discussions
4. 🆘 Report bugs: New Issue

---

Didn't find what you're looking for? Check the 🆘 Troubleshooting Guide for more detailed solutions.

🏠 Home | ⚡ Quick Start | 🆘 Troubleshooting | 📚 Documentation