Download the PHP package prahsys/laravel-perimeter without Composer

Laravel Perimeter

Comprehensive system-level security monitoring for Laravel applications, integrating malware protection, runtime behavioral analysis, vulnerability detection, intrusion prevention, and firewall management.

Overview

Laravel Perimeter provides comprehensive security monitoring at the infrastructure boundary by seamlessly integrating multiple industry-standard security tools into a unified package with Laravel-native interfaces, standardized APIs, and consolidated logging. It creates a multi-layered security perimeter around your application to detect and respond to various security threats.

Core Components

1. File Protection (ClamAV Integration)

• Malware scanning with OnAccess real-time protection
• Scheduled and on-demand scanning with configurable paths
• Signature-based detection with automatic database updates
• Integration with Laravel's file upload system
• Configurable exclusion patterns for performance optimization

2. Runtime Protection (Falco Integration)

• Behavioral anomaly detection with kernel-level monitoring
• Container runtime security for containerized environments
• Suspicious process execution monitoring
• File access anomaly detection
• Network activity monitoring and alerting
• Custom security rules for Laravel-specific threats
• Point-in-time or continuous real-time monitoring modes

3. Vulnerability Scanning (Trivy Integration)

• Full system vulnerability scanning of OS packages and system libraries (debian, ubuntu, alpine, etc.)
• PHP dependency vulnerability detection (composer.lock)
• JavaScript dependency scanning (package-lock.json, yarn.lock)
• Known CVE detection with CVSS scoring
• Configurable severity thresholds (CRITICAL, HIGH, MEDIUM, LOW)
• License compliance checking
• Configuration file security analysis
• Container image scanning support

4. Intrusion Prevention (Fail2ban Integration)

• Automatic detection and blocking of suspicious IPs
• Protection for SSH, web applications, and API endpoints
• Custom jail configurations for Laravel-specific attack patterns
• Ban action monitoring and management
• Integration with system firewall rules

5. Firewall Management (UFW Integration)

• Network-level protection with simplified rule management
• Service-based security policies
• Port access control and monitoring
• Policy enforcement and validation

6. Laravel Integration

• File upload protection via middleware
• Security event broadcasting
• Integration with Laravel's logging system
• Compatible with Laravel scheduler for automated scanning
• Unified interfaces for all security components

7. Reporting & Data Export

• Comprehensive security event collection and standardization
• Raw security event data export (JSON/CSV)
• Time-range filtering with from/to date parameters
• Event type filtering (malware, vulnerability, behavioral)
• Severity threshold filtering (critical, high, medium, low)
• Configurable output formats (text, json, csv)
• Security status overview for compliance documentation

Installation

1. Install the Package

2. Publish the Configuration

This will create a config/perimeter.php file in your application.

3. Run the Installation Command

This command will help you install and configure the required system dependencies:

Each service is installed with optimized configurations for Laravel applications:

• ClamAV: Installs with real-time protection capabilities and optimized scan settings
• Falco: Installed without a kernel driver for non-interactive installation, providing comprehensive runtime monitoring with minimal system impact
• Trivy: Configured for comprehensive system and dependency scanning with automated vulnerability database updates
• Fail2ban: Set up with Laravel-specific jail configurations and monitoring permissions for the current user (requires logout/login to take effect)
• UFW: Configured with secure default policies and Laravel-friendly port rules

The installation command will:

• Install the necessary security tools based on your system type
• Configure each service for optimal operation with Laravel
• Set up your .env file with appropriate Perimeter settings
• Create necessary directories for rules and custom configurations
• Set appropriate permissions for security operations

4. Configure Environment Variables

The installer will add these to your .env file, but you can customize them:

Basic Usage

1. Protect File Uploads

Add the Perimeter middleware to routes that handle file uploads:

The middleware will:

• Scan uploaded files for malware
• Block files with detected threats
• Log security events for audit purposes
• Apply configurable threat response policies

2. Scan Files Programmatically

3. Schedule Regular Security Checks

Add these to your app/Console/Kernel.php file:

4. Set Up Real-time Monitoring

Perimeter provides comprehensive real-time security monitoring through two primary services:

Behavioral Monitoring with Falco

Falco provides kernel-level behavioral analysis to detect suspicious activities:

Falco monitoring provides:

• Kernel-level visibility into all system calls
• Rule-based detection of suspicious processes
• Detection of privilege escalation attempts
• Monitoring of file access patterns for data exfiltration
• Network connection monitoring
• JSON-formatted, standardized security events

Malware Detection with ClamAV

ClamAV provides real-time file system monitoring for malware:

ClamAV monitoring provides:

• Real-time scanning of files as they are accessed
• Detection of malware, trojans, and other threats
• On-access protection for uploads and other file operations
• Signature-based detection with daily database updates
• Low false-positive rate suitable for web applications

Centralized Monitoring Dashboard

For continuous monitoring, use Supervisor:

The combined monitoring system:

• Stores all security events in a standardized format
• Provides audit-ready logs for compliance requirements
• Timestamps and categorizes all security events
• Associates events with specific scans for traceability
• Tracks service origin for each event (falco, clamav, etc.)
• Enables filtering by severity, type, and timeframe

5. Respond to Security Events

Command Reference

Security Audit

Perform a comprehensive security assessment across all protection layers:

This command:

• Checks all security components for proper operation
• Scans the application for malware
• Scans system packages and dependencies for vulnerabilities
• Analyzes recent behavioral events
• Checks firewall and intrusion prevention status
• Generates a comprehensive security assessment

Options:

• --format=json - Output in JSON format for automated processing
• --services=clamav,trivy - Run audit only for specific services (comma-separated)

Health Check

Verify that all security components are properly installed and operational:

This command quickly verifies:

• Service installation status
• Service configuration status
• Service operational status
• Environment configuration
• Required permissions

Monitoring

Monitor security events across all protection layers:

Options:

• --duration=3600 - Duration in seconds (default: indefinite)
• --services=clamav,falco - Focus on specific security services (comma-separated)

Daemon Management

For production deployments, monitoring should be run as a daemon using supervisor. The terminate command allows for graceful shutdown during deployments:

This is particularly useful with supervisor configuration for automatic restart after deployments:

Deployment workflow:

1. php artisan perimeter:terminate - Gracefully stop monitoring
2. Deploy application updates
3. Supervisor automatically restarts monitoring

Reporting

Generate detailed security reports with flexible filtering:

Options:

• --scan-id=123 - Filter by specific scan ID
• --from=2025-01-01 - Start date for filtering events
• --to=2025-06-01 - End date for filtering events
• --type=malware,vulnerability,behavioral - Filter by event type
• --severity=critical,high,medium,low - Filter by severity
• --format=json - Output format (text, json, csv)
• --output=/path/to/file.json - Output file path
• --scans-only - Show only scan summary without event details

System Maintenance

Audit Artifacts

Laravel Perimeter automatically collects comprehensive audit artifacts during security audits, providing detailed compliance documentation and forensic evidence.

What Are Audit Artifacts?

Audit artifacts are timestamped collections of security service outputs, logs, and system states captured during each security audit. These artifacts serve multiple purposes:

• Compliance Documentation: Detailed records for security audits and compliance reporting
• Forensic Evidence: Preserved system states and security tool outputs for incident investigation
• Historical Analysis: Point-in-time snapshots of security posture for trend analysis
• Troubleshooting: Detailed service outputs to diagnose security tool issues

Artifact Collection

Every time you run php artisan perimeter:audit, the system automatically:

1. Captures Service Outputs: Collects logs, scan results, and status information from all enabled security services
2. Records System State: Documents firewall rules, service configurations, and system health
3. Generates Metadata: Creates audit summaries with timestamps, service versions, and scan statistics
4. Compresses Archives: Packages all artifacts into timestamped ZIP files for efficient storage

Example artifacts include:

• ClamAV scan logs and malware detection reports
• Trivy vulnerability scan results and database information
• UFW firewall status and rule configurations
• Fail2ban intrusion logs and banned IP lists
• Falco behavioral monitoring events
• Complete audit command output (audit.log)

Storage Configuration

Configure artifact storage in config/perimeter.php:

Storage Disk Options

Use any Laravel storage disk for artifact storage:

Environment Variables

Distributed Environments

For server clusters or distributed deployments, you can add machine identification to artifact paths to prevent conflicts:

Option 1: Machine ID in Path

Option 2: Custom Disk Per Environment

Option 3: Dynamic Path Configuration

Artifact Structure

Artifacts are organized in a consistent directory structure:

Artifact Retention

Artifacts are automatically cleaned up based on the retention period:

Accessing Artifacts

Access artifacts through Laravel's storage system:

Compliance Integration

Artifacts are designed to support various compliance frameworks:

• SOC 2: Regular security monitoring evidence
• ISO 27001: Information security management documentation
• PCI DSS: Security scanning and monitoring logs
• HIPAA: Security safeguard documentation
• Custom Audits: Comprehensive security posture evidence

The standardized format and automated collection ensure consistent, auditable security documentation.

Advanced Integration Features

1. Logging Integration

All security events use Laravel's logging system, enabling seamless integration with your existing logging infrastructure:

2. Event Handling & Callbacks

Register custom handlers for security events to integrate with your application's notification systems:

3. Programmatic Reporting

Generate security reports programmatically for integration with dashboards or compliance systems:

Data Storage & Integration

The package provides robust data storage and standardized data structures for security events, making it easy to integrate with existing monitoring and compliance systems.

Database Storage

Security events are stored in dedicated database tables with optimized schemas:

• perimeter_security_events: Stores standardized security events from all sources

  • Includes type, severity, timestamps, descriptions, and structured details
  • Supports JSON column for flexible event-specific data
  • Indexed for efficient querying and reporting
• perimeter_security_scans: Stores metadata about security scan operations
  • Tracks scan types, timestamps, durations, and results
  • Links to related security events
  • Provides audit trail of security operations

The package automatically migrates these tables during installation.

Data Transfer Objects

All security events use standardized Data Transfer Objects (DTOs) that provide consistent representations across different security tools:

Security Assessment

The package provides detailed security assessments with actionable information through:

1. Comprehensive Issue Tracking: Clear categorization of issues by type and severity
2. Component Health Status: Verification that all security components are properly functioning
3. Protection Coverage: Assessment of which security layers are active and properly configured
4. Actionable Findings: Specific, concrete security issues that need attention
5. Compliance Information: Relevant data points for security compliance requirements

This detailed approach provides security professionals with clear, actionable insights about your application's security posture.

Example of security assessment output:

Development Environment

Using Docker for Development

The package includes a Docker environment for local development and testing. This setup allows you to develop and test all security features without needing a full VM or physical machine.

Docker Setup Instructions

1. Make sure Docker and Docker Compose are installed on your machine
2. Run the following commands:

This Docker configuration:

• Creates a fully configured Laravel application for testing
• Installs this package from the local directory with proper volume mounting
• Properly configures all security components
• Sets up necessary permissions and directory structures
• Uses SQLite for a lightweight database with minimal configuration
• Exposes the application on port 8000 for browser testing

How Security Services Run in Docker

The security services (ClamAV, Falco, Fail2ban, Trivy, UFW) are configured to work properly in the container with standard configurations and include:

• Proper service startup and monitoring
• Configuration management
• Log collection and rotation
• Full functionality testing
• Status checking and reporting

This approach enables reliable testing across different environments with consistent behavior.

Testing Security Services

The Docker environment allows for comprehensive testing of all security components:

Troubleshooting

If you encounter issues during installation or operation, follow these steps:

1. Check Component Health

The first step is to verify all components are properly installed and configured:

This provides a detailed status report of all security components with specific error messages.

2. Check Logs

Review the Laravel and component-specific logs:

3. Common Issues

• Permission Problems: Security services often require elevated permissions. Ensure proper user/group settings.
• Missing Dependencies: Some components require additional system packages. Check the installation output.
• Container Limitations: Some features may be limited in containerized environments without privileged access.
• Database Issues: Ensure migrations have run properly: php artisan migrate:status

4. ClamAV Not Starting

If you see "ClamAV is installed and configured but daemon is not running" in the health check:

AppArmor Configuration Issues

If ClamAV real-time scanning (clamonacc) fails to start, it may be blocked by AppArmor security policies:

FiThe installer automatically configures AppArmor profiles, but manual configuration may be needed:

If AppArmor is not installed but needed:

See DEBUGGING.md for more detailed ClamAV troubleshooting steps.

5. Sample Outputs

The package includes reference outputs for all security tools in the resources/examples/ directory. These examples show what properly functioning services should produce and help with troubleshooting.

The resources/examples/perimeter/audit/ directory contains example audit artifacts showing the complete output structure of security audits, including service logs, scan results, and compliance documentation.

Documentation

For more detailed information, check out these documentation files:

• RUNBOOKS.md - Incident response procedures and runbooks
• DEBUGGING.md - Detailed debugging procedures for all components
• Example outputs - Sample outputs from security tools

License

The MIT License (MIT). Please see License File for more information.