Audit & Compliance Framework Guide

Last Updated: 2026-01-17 Status: Implemented Plan Reference: 039-audit-compliance-framework.md, 058-audit-compliance-enhancement.md, 094-audit-compliance-improvement.md, 115-extended-audit-templates.md, 120-compliance-score-improvement.md

Overview

The Audit & Compliance Framework provides comprehensive tools for tracking, auditing, and ensuring regulatory compliance within the client portal. It includes audit trails, data retention policies, compliance reporting, GDPR/privacy features, automated compliance checks, and a monitoring dashboard supporting multiple frameworks (GDPR, SOC 2, HIPAA, PCI-DSS).

Table of Contents

1. Accessing Compliance Features
2. Compliance Dashboard
3. Compliance Reports
4. Automated Compliance Checks
5. Findings Management
6. Audit Features
7. Data Retention
8. Privacy & GDPR
9. Technical Architecture
10. Related Features

Accessing Compliance Features

Navigation

Note: There are two separate audit systems: the Compliance Audit Timeline focuses on compliance-related activities, while the Admin Audit Trail provides a complete activity log for all system operations.

Permissions

Compliance Dashboard

The compliance dashboard provides a centralized view of your organization's compliance posture.

Dashboard Metrics

Score Calculation

The compliance score is calculated based on:

• MFA adoption rate (30% weight)
• Inactive account rate (20% weight)
• Security alerts count (20% weight)
• Failed login attempts (15% weight)
• Other security factors (15% weight)

Framework Status Levels

Compliance Reports

Available Report Templates

Generating Reports

1. Navigate to Admin → Compliance → Reports
2. Select a report template
3. Configure date range and parameters
4. Click Generate Report
5. View report details or export

Report Export Formats

Report Data Structure

Each report includes:

• Summary: Key metrics and totals
• Details: Categorized data sections
• Recommendations: Suggested improvements
• Period: Date range covered

Automated Compliance Checks

Available Checks

Check Results

Each check returns:

Running Checks

Manual Execution:

1. Navigate to Admin → Compliance → Checks
2. Click Run All Checks or select individual checks
3. View results and findings

Scheduled Execution:

// Runs daily via scheduler
$schedule->command('compliance:run-checks')->daily();

Check Severity Levels

When checks fail, findings are created with severity:

Findings Management

Finding Lifecycle

Open → In Progress → Resolved
                  ↘ Deferred

Finding Fields

Managing Findings

1. Navigate to Admin → Compliance → Findings
2. Filter by status, severity, or framework
3. Click a finding to view details
4. Update status, assign user, add notes
5. Resolve with resolution notes

Audit Features

Audit Trail

Complete record of all system changes:

Audit Report Types

Viewing Audit Trail

1. Navigate to Admin → Compliance → Audit Trail
2. Filter by:
   • Date range
   • User
   • Entity type
   • Event type
3. View detailed records
4. Export for external review

Data Retention

Retention Policies

Configuring Retention

1. Navigate to Admin → Compliance → Retention
2. Select data category
3. Set retention period
4. Configure auto-deletion or archival
5. Save policy

Retention Actions

Retention Automation

// Scheduled task
$schedule->command('compliance:enforce-retention')->daily();

Privacy & GDPR

Privacy Features

Data Subject Requests

Request Types:

• Access Request (view my data)
• Portability Request (export my data)
• Erasure Request (delete my data)
• Rectification Request (correct my data)

Processing Requests:

1. User submits request via profile or email
2. Request logged in system
3. Admin reviews and verifies
4. Action taken within deadline
5. User notified of completion

Data Export

Exportable Data:

• Profile information
• Activity history
• Files uploaded
• Communications
• Preferences

Export Process:

1. User requests export
2. System compiles data
3. Package generated (JSON/ZIP)
4. Download link sent
5. Link expires after 7 days

Data Deletion

Deletion Scope:

• User account
• Personal information
• Associated content
• Activity history

Exceptions:

• Legal hold data
• Financial records
• Audit trail entries

Technical Architecture

Central Configuration

Location: config/compliance.php

All compliance settings are centralized in this configuration file:

return [
    // Compliance Frameworks
    'frameworks' => [
        'gdpr' => [
            'name' => 'GDPR',
            'description' => 'General Data Protection Regulation',
            'enabled' => env('COMPLIANCE_GDPR_ENABLED', true),
            'data_retention_days' => env('GDPR_DATA_RETENTION_DAYS', 365),
        ],
        'soc2' => [
            'name' => 'SOC 2',
            'description' => 'Service Organization Control 2',
            'enabled' => env('COMPLIANCE_SOC2_ENABLED', true),
        ],
        'hipaa' => [
            'name' => 'HIPAA',
            'description' => 'Health Insurance Portability and Accountability Act',
            'enabled' => env('COMPLIANCE_HIPAA_ENABLED', false),
        ],
        'pci' => [
            'name' => 'PCI DSS',
            'description' => 'Payment Card Industry Data Security Standard',
            'enabled' => env('COMPLIANCE_PCI_ENABLED', false),
        ],
    ],

    // Compliance Checks Configuration
    'checks' => [
        'enabled' => env('COMPLIANCE_CHECKS_ENABLED', true),
        'schedule' => env('COMPLIANCE_CHECK_SCHEDULE', 'daily'),
        'notify_on_failure' => env('COMPLIANCE_NOTIFY_FAILURES', true),
        'password_policy' => [
            'min_length' => env('PASSWORD_MIN_LENGTH', 12),
            'require_uppercase' => true,
            'require_lowercase' => true,
            'require_numbers' => true,
            'require_symbols' => true,
            'max_age_days' => env('PASSWORD_MAX_AGE_DAYS', 90),
        ],
        'mfa_enforcement' => [
            'require_for_admins' => true,
            'require_for_clients' => env('MFA_REQUIRED_FOR_CLIENTS', false),
        ],
        'session_timeout' => [
            'max_lifetime_minutes' => env('SESSION_MAX_LIFETIME', 120),
            'idle_timeout_minutes' => env('SESSION_IDLE_TIMEOUT', 30),
        ],
        'inactive_accounts' => [
            'warning_days' => env('INACTIVE_ACCOUNT_WARNING_DAYS', 60),
            'lockout_days' => env('INACTIVE_ACCOUNT_LOCKOUT_DAYS', 90),
        ],
        'data_retention' => [
            'audit_log_days' => env('AUDIT_LOG_RETENTION_DAYS', 365),
            'soft_delete_days' => env('SOFT_DELETE_RETENTION_DAYS', 90),
            'auto_purge' => env('DATA_AUTO_PURGE', false),
        ],
    ],

    // Reports Configuration
    'reports' => [
        'storage_path' => env('COMPLIANCE_REPORTS_PATH', 'compliance-reports'),
        'retention_days' => env('COMPLIANCE_REPORTS_RETENTION', 365),
        'formats' => ['pdf', 'html', 'json', 'csv'],
        'default_format' => 'pdf',
        'include_evidence' => true,
    ],

    // Evidence Collection
    'evidence' => [
        'enabled' => env('COMPLIANCE_EVIDENCE_ENABLED', true),
        'storage_path' => env('COMPLIANCE_EVIDENCE_PATH', 'compliance-evidence'),
        'auto_collect' => true,
        'types' => ['screenshot', 'log_export', 'config_snapshot', 'policy_document', 'attestation'],
    ],

    // Findings Management
    'findings' => [
        'severity_levels' => ['critical', 'high', 'medium', 'low', 'info'],
        'statuses' => ['open', 'in_progress', 'resolved', 'accepted', 'deferred'],
        'auto_assign' => env('COMPLIANCE_AUTO_ASSIGN', false),
        'default_assignee' => env('COMPLIANCE_DEFAULT_ASSIGNEE'),
        'sla_days' => [
            'critical' => 1,
            'high' => 7,
            'medium' => 30,
            'low' => 90,
        ],
    ],

    // Notifications
    'notifications' => [
        'check_failure' => ['enabled' => true, 'channels' => ['mail', 'database']],
        'finding_created' => ['enabled' => true, 'channels' => ['mail', 'database']],
        'report_generated' => ['enabled' => true, 'channels' => ['database']],
    ],

    // Dashboard Settings
    'dashboard' => [
        'score_thresholds' => ['good' => 90, 'warning' => 70, 'critical' => 0],
        'show_trends' => true,
        'trend_days' => 30,
        'cache_ttl' => 300,
    ],
];

Environment Variables:

Models

Location: app/Models/

ComplianceReport Model:

class ComplianceReport extends Model
{
    protected $fillable = [
        'generated_by', 'report_type', 'template', 'framework',
        'title', 'period_start', 'period_end', 'parameters',
        'data', 'summary', 'file_path', 'status', 'completed_at',
    ];

    protected $casts = [
        'period_start' => 'date',
        'period_end' => 'date',
        'parameters' => 'array',
        'data' => 'array',
        'summary' => 'array',
        'completed_at' => 'datetime',
    ];
}

ComplianceFinding Model:

class ComplianceFinding extends Model
{
    public const STATUS_OPEN = 'open';
    public const STATUS_IN_PROGRESS = 'in_progress';
    public const STATUS_DEFERRED = 'deferred';
    public const STATUS_RESOLVED = 'resolved';

    public const SEVERITY_CRITICAL = 'critical';
    public const SEVERITY_HIGH = 'high';
    public const SEVERITY_MEDIUM = 'medium';
    public const SEVERITY_LOW = 'low';
    public const SEVERITY_INFO = 'info';

    protected $fillable = [
        'check_key', 'check_run_id', 'framework', 'severity',
        'title', 'description', 'evidence', 'affected_resources',
        'remediation', 'remediation_steps', 'status', 'assigned_to',
        'due_date', 'notes', 'resolved_at', 'resolved_by', 'resolution_notes',
    ];
}

Services

Location: app/Services/Compliance/

ComplianceReportService:

class ComplianceReportService
{
    private array $templates = [
        'gdpr_data_access' => GdprDataAccessReport::class,
        'gdpr_data_processing' => GdprDataProcessingReport::class,
        'gdpr_consent_audit' => GdprConsentAuditReport::class,
        'soc2_access_control' => Soc2AccessControlReport::class,
        'soc2_change_management' => Soc2ChangeManagementReport::class,
        'hipaa_access_log' => HipaaAccessLogReport::class,
        'pci_access_audit' => PciAccessAuditReport::class,
        'user_access_review' => UserAccessReviewReport::class,
        'data_retention' => DataRetentionReport::class,
        'security_audit' => SecurityAuditReport::class,
    ];

    public function generate(string $template, array $params): ComplianceReport;
    public function getTemplates(): array;
    public function hasTemplate(string $template): bool;
    public function getTemplatesByFramework(): array;
}

ComplianceCheckService:

class ComplianceCheckService
{
    private array $checks = [
        'mfa_enforcement' => MfaEnforcementCheck::class,
        'password_policy' => PasswordPolicyCheck::class,
        'inactive_accounts' => InactiveAccountsCheck::class,
        'data_retention' => DataRetentionCheck::class,
        'audit_logging' => AuditLoggingCheck::class,
        'session_timeout' => SessionTimeoutCheck::class,
    ];

    public function runAll(?int $triggeredBy = null): ComplianceCheckRun;
    public function runCheck(string $key): array;
    public function getAvailableChecks(): array;
}

ReportExportService:

class ReportExportService
{
    public function export(ComplianceReport $report, string $format): mixed;
    public function supports(string $format): bool;
    // Supports: pdf, html, csv, json
}

Report Templates

Location: app/Services/Compliance/Reports/

Each report implements ComplianceReportInterface:

interface ComplianceReportInterface
{
    public static function getName(): string;
    public static function getDescription(): string;
    public static function getFramework(): string;
    public static function getParameters(): array;
    public function generate(): array;
}

Compliance Checks

Location: app/Services/Compliance/Checks/

Each check implements ComplianceCheckInterface:

interface ComplianceCheckInterface
{
    public static function getName(): string;
    public static function getDescription(): string;
    public static function getFramework(): string;
    public function run(): array;
}

Controllers

Location: app/Http/Controllers/Admin/

Key Methods:

class ComplianceDashboardController extends Controller
{
    public function index(): View;              // Dashboard
    public function reports(): View;            // Reports list
    public function generateReport(Request);    // Create report
    public function showReport(Report);         // View report
    public function exportReport(Report, fmt);  // Export report
    public function checks(): View;             // Checks list
    public function runChecks(Request);         // Execute checks
    public function findings(): View;           // Findings list
    public function updateFinding(Request, Finding);  // Update finding
    public function resolveFinding(Request, Finding); // Resolve finding
}

Routes

Route::prefix('admin/compliance')->middleware(['auth', 'admin'])->group(function () {
    // Dashboard
    Route::get('/', [ComplianceDashboardController::class, 'index'])
        ->name('admin.compliance.dashboard');

    // Reports
    Route::get('/reports', [ComplianceDashboardController::class, 'reports'])
        ->name('admin.compliance.reports');
    Route::post('/reports/generate', [ComplianceDashboardController::class, 'generateReport'])
        ->name('admin.compliance.generate-report');
    Route::get('/reports/{report}', [ComplianceDashboardController::class, 'showReport'])
        ->name('admin.compliance.report.show');
    Route::get('/reports/{report}/export/{format}', [ComplianceDashboardController::class, 'exportReport'])
        ->name('admin.compliance.report.export');

    // Checks
    Route::get('/checks', [ComplianceDashboardController::class, 'checks'])
        ->name('admin.compliance.checks');
    Route::post('/checks/run', [ComplianceDashboardController::class, 'runChecks'])
        ->name('admin.compliance.run-checks');
    Route::get('/checks/{run}', [ComplianceDashboardController::class, 'showCheckRun'])
        ->name('admin.compliance.check-run.show');

    // Findings
    Route::get('/findings', [ComplianceDashboardController::class, 'findings'])
        ->name('admin.compliance.findings');
    Route::put('/findings/{finding}', [ComplianceDashboardController::class, 'updateFinding'])
        ->name('admin.compliance.finding.update');
    Route::post('/findings/{finding}/resolve', [ComplianceDashboardController::class, 'resolveFinding'])
        ->name('admin.compliance.finding.resolve');
});

Commands

# Run all compliance checks
php artisan compliance:run-checks

# Enforce retention policies
php artisan compliance:enforce-retention

# Generate compliance report
php artisan compliance:report --type=gdpr

# Process privacy requests
php artisan compliance:process-requests

# Manage inactive accounts (SOC 2 compliance)
php artisan compliance:inactive-accounts --list           # List inactive accounts
php artisan compliance:inactive-accounts --deactivate    # Deactivate inactive non-admins
php artisan compliance:inactive-accounts --days=60       # Custom inactivity threshold

# Enforce MFA for admins (SOC 2 compliance)
php artisan compliance:enforce-mfa --list                # List admin MFA status
php artisan compliance:enforce-mfa --notify              # Send MFA setup reminders

Scheduled Tasks

// app/Console/Kernel.php
$schedule->command('compliance:run-checks')->daily();
$schedule->command('compliance:enforce-retention')->daily();
$schedule->command('compliance:process-requests')->hourly();

Database Tables

compliance_reports

compliance_checks

compliance_check_runs

compliance_findings

compliance_report_schedules

Related Features

Dependencies

Complementary Features

Improving Compliance Score

If your compliance score is low or 0%, here's how to fix each check:

1. Password Policy Compliance (SOC 2)

Requirements:

• password_changed_at column must exist on users table
• 95%+ of users must have passwords changed within 90 days

Fix:

php artisan migrate  # Ensure migration is run

The system tracks password changes automatically via the password_changed_at field.

2. MFA Enforcement (SOC 2)

Requirements:

• 100% of admin accounts must have MFA enabled
• 80%+ overall MFA adoption

Fix:

php artisan compliance:enforce-mfa --list    # See which admins need MFA
php artisan compliance:enforce-mfa --notify  # Send reminders

Admins must enable MFA via Account Settings > Security > Two-Factor Authentication.

3. Inactive Accounts Review (SOC 2)

Requirements:

• No inactive admin accounts (90+ days without login)
• Less than 5% inactive users overall

Fix:

php artisan compliance:inactive-accounts --list        # Review inactive accounts
php artisan compliance:inactive-accounts --deactivate  # Deactivate non-admin accounts

4. Data Retention Policy (GDPR)

Requirements:

• config('audit.retention_days') must be configured
• No audit logs older than 7 years

Fix: Add to .env:

AUDIT_LOGGING_ENABLED=true
AUDIT_LOG_RETENTION_DAYS=365

5. Audit Logging Coverage (General)

Requirements:

• At least 1 audit log in the last 24 hours
• Must capture: login, logout, create, update, delete events
• All logs must have integrity signatures

Fix:

• Ensure audit logging is enabled (AUDIT_LOGGING_ENABLED=true)
• Generate activity by logging in/out and performing CRUD operations
• The system automatically captures these events when the Auditable trait is used

6. Session Timeout Configuration (General)

Requirements:

• Session lifetime ≤ 120 minutes
• HttpOnly cookies enabled
• Secure cookies enabled (production)
• SameSite not set to "none"

Fix: Add to .env:

SESSION_LIFETIME=120
SESSION_SECURE_COOKIE=true  # Required for production

Production Environment Variables

For a compliant production environment, ensure these are set in .env:

# Audit & Compliance
AUDIT_LOGGING_ENABLED=true
AUDIT_LOG_RETENTION_DAYS=365
AUDIT_AUTO_PURGE=false

# Session Security
SESSION_LIFETIME=120
SESSION_SECURE_COOKIE=true

# Compliance Checks
COMPLIANCE_CHECKS_ENABLED=true
COMPLIANCE_CHECK_SCHEDULE=daily

Best Practices

For Compliance

1. Run automated checks regularly - Schedule daily checks
2. Address findings promptly - Prioritize by severity
3. Document all decisions in audit trail
4. Generate reports before audits - Have documentation ready
5. Train staff on compliance procedures

For Security

1. Encrypt sensitive data at rest and in transit
2. Limit access to compliance tools
3. Audit access to compliance data
4. Backup audit trails separately

For Reporting

1. Use appropriate templates for your framework
2. Set date ranges carefully for accurate data
3. Review reports before sharing with auditors
4. Keep historical reports for trend analysis

Troubleshooting

Testing

Test Files

Configuration Tests

Location: tests/Unit/ComplianceConfigTest.php

Tests verify:

• Framework configuration structure (GDPR, SOC 2, HIPAA, PCI)
• Check configuration with password policy, MFA enforcement
• Report configuration including formats and paths
• Evidence collection configuration
• Findings management with severity levels and SLAs
• Notification configuration
• Dashboard settings with score thresholds

Service Tests

Location: tests/Unit/ComplianceCheckServiceTest.php

Tests verify:

• Available checks are returned with proper structure
• Checks are grouped by framework correctly
• Single check execution returns proper result format
• All checks run successfully with results
• Compliance score calculation
• Zero score returned with no check runs
• Exception thrown for unknown checks
• MFA check fails when admins lack MFA
• Session timeout check execution

Running Tests

# Run all compliance tests
php artisan test tests/Unit/ComplianceConfigTest.php tests/Unit/ComplianceCheckServiceTest.php

# Run specific test method
php artisan test --filter=it_runs_all_checks

See Also

• Activity Logging - Audit source
• Security - Security features
• Reports - Report framework