Audit Bundle Laravel Package

Technical Evaluation

Release Delta (v1.3.1 → v1.3.2)

• What shipped: PR #121 ("Honour audited_entities and unaudited_entities") by a first-time contributor. This is nominally a patch release, but it is a behavioural change, not a cosmetic one: the bundle's inclusion/exclusion configuration is now actually applied.
• Why it matters: Prior to v1.3.2, applications that declared an allow-list (audited_entities) or a deny-list (unaudited_entities) were, in practice, getting audit coverage driven by something other than that configuration. After upgrading, coverage is driven by the configuration as written. The set of audited entities can change on a patch upgrade without any application code change.
• Corrects a prior assumption: The earlier assessment flagged Unaudited Entities as a deprecated feature to be replaced. That was wrong — it is an active configuration surface that was simply not being honoured. The remediation is an upgrade plus a config audit, not a replacement plan.
• Maintenance signal: A new external contributor landing a fix, plus a tagged release, is evidence of a maintained project. The earlier "abandoned or hypothetical" risk should be downgraded from abandonment to bus-factor / low-adoption risk (still no meaningful dependent ecosystem).
• No new dependencies, no schema changes, no API breaks are indicated by the notes. Risk is concentrated entirely in the audit-coverage delta.

Architecture Fit

• ORM-Centric Design: The bundle is tightly coupled with Doctrine ORM, making it ideal for Symfony/Laravel applications using Doctrine (via Laravel Doctrine or similar bridges). If the application relies heavily on Eloquent ORM (Laravel's default), integration would require additional abstraction layers (e.g., event listeners or proxies) to bridge Doctrine-specific audit logic.
• Configuration Surface Is Now Load-Bearing: With v1.3.2, audited_entities / unaudited_entities become the primary lever for scoping audit coverage. This strengthens the architectural fit for Laravel apps that need a selective audit trail (audit business-critical models, exclude high-churn or PII-heavy tables) — but it also means the config file is now an audit-policy document that must be reviewed and owned, not a default left untouched.
• Transaction Safety: Audit logs are inserted within the same transaction as the original operation, ensuring atomicity. This aligns well with Laravel's transactional workflows (e.g., DB::transaction()) but may introduce performance overhead if audit logging is disabled mid-transaction.
• User Context: Leverages Symfony's TokenStorage for user attribution. In Laravel, this would require mapping to Laravel's Auth system (e.g., via middleware or service providers).
• Limited Scope: Does not track DQL/raw SQL, which is a critical gap for applications with complex queries or direct database access. Requires complementary tools (e.g., Laravel's DB::listen() or query loggers) for full coverage. Note that v1.3.2 widens this gap in perception: a correctly configured allow-list now gives a false sense of completeness — "we configured our audited entities" does not mean "we audit our data changes."

Integration Feasibility

• Symfony vs. Laravel Compatibility:
  • High: For Symfony apps, integration is straightforward (as documented).
  • Medium-High: For Laravel, requires:
    • Doctrine ORM setup (e.g., laravel-doctrine/orm).
    • Symfony components (e.g., TokenStorage) to be bridged (e.g., via symfony/http-foundation or custom wrappers).
  • Low: For pure Eloquent apps without Doctrine, integration would be non-trivial (custom event listeners or proxy patterns needed).
• Configuration Feasibility (new): The upgrade makes config correctness a hard prerequisite. Before enabling, you must be able to answer, in writing, which entities are in scope and why. In a Laravel codebase this is non-obvious: entity class names are Doctrine FQCNs, not Eloquent model names, so the mapping must be produced deliberately.
• Database Schema: Requires additional tables (audit_entry, audit_entity, etc.). Laravel's migrations system can adopt these, but schema changes must be backward-compatible.
• Performance: Audit logs are generated on flush, which could impact write-heavy operations. v1.3.2 is performance-relevant: correctly applied unaudited_entities is now a legitimate lever for removing audit write load from high-churn tables. Benchmarking is recommended for high-throughput systems.

Technical Risk

• Silent Audit-Coverage Change (elevated, primary risk): A patch-level bump can now narrow the audit trail. If audited_entities was configured as a whitelist while the option was ignored, everything was being logged; post-upgrade only the whitelist is. That is a retroactive compliance gap — records the organisation believed it had will simply not be written going forward, with no error, warning, or log line. Conversely, a previously-ignored unaudited_entities deny-list means sensitive or high-volume tables may have been captured in audit tables all along (data-protection exposure in existing rows) and will stop being captured now.
• Version Verification Still Required: Confirm the actual release history (GitHub tags), that v1.3.2 is the version resolved by Composer, and compatibility with Laravel 10.x/Symfony 6.x+. The presence of a real changelog resolves the "abandoned" concern but not the "is this the version we pinned" concern.
• Laravel-Specific Gaps:
  • Authentication: Symfony's TokenStorage ≠ Laravel's Auth. Requires custom mapping.
  • Event System: Laravel's events (e.g., eloquent.*) won't trigger Doctrine listeners by default.
  • Testing: Audit logs may not persist in test environments (e.g., SQLite in-memory DBs). Critically, tests that asserted audit rows existed may now fail if the entity under test is excluded by config — and tests that asserted absence may now pass for the wrong reason.
• Data Diff Complexity: Handling nested relations (e.g., many-to-many) may require customization for Laravel's Eloquent relations.
• Low Adoption / Bus Factor: New contributor is a positive signal, but the project still has a thin maintainer base. A regression in coverage logic in a future patch is plausible and would be equally silent.

Key Questions

1. Coverage Delta: What is the concrete before/after list of audited entities for our configuration at v1.3.1 vs v1.3.2? This must be produced empirically, not from reading the config file.
2. ORM Strategy: Is Doctrine ORM already in use, or would Eloquent require a custom audit solution? If using Eloquent, can the bundle's logic be adapted via model observers or query listeners?
3. Configuration Ownership: Who owns audited_entities / unaudited_entities, and is that list traceable to a stated audit policy? Is the config currently a placeholder?
4. User Attribution: How is user context stored in Laravel? Can it be mapped to Symfony's TokenStorage?
5. Performance: What is the acceptable latency for audit logging? Does enabling correct exclusion materially reduce write volume, and are there plans to batch or asynchronously process logs?
6. Backfill / Historical Inconsistency: Existing audit rows were captured under the old (config-ignoring) behaviour. How do we reconcile a log where coverage semantics changed mid-stream, and do downstream consumers (reports, compliance exports) assume uniform coverage?
7. Schema Management: How will audit tables be versioned alongside Laravel migrations? Are there conflicts with existing audit tables (e.g., from other packages)?
8. Compliance: Does the bundle meet regulatory requirements (e.g., immutable logs, retention policies)? Does the v1.3.2 coverage change require disclosure to an auditor?
9. Fallbacks: How will direct SQL/queries be audited? (Requires additional tooling.)
10. Testing: How will audit logs be verified in CI/CD? Recommend pinning explicit positive and negative assertions per entity so a config-driven regression fails loudly.

Integration Approach

Stack Fit

• Best Fit:
  • Symfony + Doctrine ORM: Native integration with minimal effort.
  • Laravel + Doctrine ORM: Possible with laravel-doctrine/orm and custom Symfony component bridges.
• Partial Fit:
  • Laravel Eloquent: Requires custom event listeners to mirror Doctrine's audit logic (e.g., retrieved, saved, deleted events). The v1.3.2 config honouring does not help here — it is meaningless without Doctrine entities.
• Non-Fit:
  • Applications relying on raw SQL or non-Doctrine ORMs (e.g., Eloquent-only with no Doctrine).

Migration Path

1. Assess ORM Dependency:
   • If using Doctrine, proceed with Symfony-style integration.
   • If using Eloquent, evaluate:
     • Option A: Replace Doctrine with Eloquent (high effort).
     • Option B: Build a parallel audit system using Eloquent events.
2. Coverage Baseline (new, do this first):
   • On the current pinned version, capture the observed set of audited entities empirically (e.g., exercise a representative write path per entity in staging, diff audit_entry rows).
   • Record the resulting list as the "as-is" baseline. Do this before any Composer change so the delta is attributable.
3. Configuration Review (new):
   • Explicitly author audited_entities and unaudited_entities to match the intended audit policy; reconcile against the as-is baseline and get sign-off from the compliance/security owner.
   • Decide and document the default posture: allow-list (audit only listed) is safer for data-protection; deny-list is safer for coverage. Pick one deliberately.
4. Installation:
   • Composer: composer require data-dog/audit-bundle:^1.3.2 (pin the minor; do not float the patch given the behavioural nature of patch releases here).
   • Register bundle in config/app.php (Laravel) or config/bundles.php (Symfony):

     // Laravel Service Provider (hypothetical)
     DataDog\AuditBundle\DataDogAuditBundle::class,
     

5. Schema Setup:
   • Use Laravel Migrations to create audit tables:

     php artisan doctrine:migrations:diff
     php artisan doctrine:migrations:migrate
     

   • Alternatively, manually define tables in a migration:

     Schema::create('audit_entry', function (Blueprint $table) {
         // Match bundle's schema
     });
     

6. User Context Bridge:
   • Create a service to map Laravel's Auth::user() to Symfony's TokenStorage:

     // Example: src/Providers/AuditServiceProvider.php
     public function register()
     {
         $this->app->bind(\Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface::class, function () {
             return new LaravelTokenStorage($this->app['auth']);
         });
     }
     

7. Testing:
   • Verify audit logs in unit/feature tests:

     public function test_audit_logs_are_created()
     {
         $user = User::factory()->create();
         $model = Model::factory()->create();
     
         // Trigger an update...
         $this->assertDatabaseHas('audit_entry', [
             'entity_id' => $model->id,
             'user_id' => $user->id,
         ]);
     }
     

   • Add a coverage contract test: one test per in-scope entity asserting a row is written, and one per out-of-scope entity asserting no row is written. This is the cheapest guard against a future silent config regression.

Compatibility

• Laravel-Symfony Components:
  • Requires compatibility with Symfony's HttpFoundation, Security, and DoctrineBridge.
  • Use packages like symfony/http-foundation or symfony/security if not already present.
• Doctrine Version:
  • Confirm compatibility with Laravel Doctrine's Doctrine version (e.g., Doctrine ORM 2.10+).
• PHP Version:
  • Bundle likely supports PHP 8.0+. Verify Laravel's PHP version alignment.
• Patch-Pinning (new): Given that this patch release altered behaviour, adopt a policy of pinned patch versions plus a mandatory review of changelog + coverage-diff before any bump.

Sequencing

1. Phase 0: Baseline & Policy — Capture as-is audit coverage; authorise the target entity list. No code changes.
2. Phase 1: Proof of Concept — Upgrade to v1.3.2 in a non-production environment. Test with a single model to validate both audit generation and exclusion behaviour. Diff observed coverage against the Phase 0 baseline and explain every difference.
3. Phase 2: Full Rollout — Enable for all audited entities per the authorised list. Implement user context mapping. Ship the coverage contract tests alongside.
4. Phase 3: Optimization — Benchmark performance; confirm the exclusion list is delivering the expected write reduction. Consider async processing if needed. Add filters (e.g., exclude sensitive fields).
5. Phase 4: Complementary Tools — Implement raw SQL auditing (e.g., Laravel's DB::listen()). Add retention policies (e.g., TTL for old logs).

Operational Impact

Maintenance

• Patch Release Hygiene (new, elevated): This release demonstrates that patch-level upgrades to this package can change runtime behaviour. Treat every bump as a change requiring a coverage diff, not a routine composer update. Pin the version in composer.json.
• Configuration as Code-Reviewed Artefact (new): audited_entities / unaudited_entities must be in version control, code-reviewed on change, and reviewed on every package bump. Treat edits to this list as compliance-relevant changes.
• Bundle Updates:
  • Monitor for Symfony/Laravel version compatibility.
  • Customizations may break with upstream changes (e.g., Doctrine schema updates).
• Schema Changes:
  • Audit tables must evolve with the bundle. Use Laravel migrations to manage schema updates.
• Deprecations:
  • Retract the earlier note flagging Unaudited Entities as deprecated — it is a supported, now-functional configuration option. Continue to track genuine deprecation warnings from the changelog.

Support

• Silent Failure Modes (new): The highest-severity support scenario is absence of audit records with no error emitted. Because exclusion is a config decision, a misconfigured entity produces a clean, green, healthy application that is simply not auditing. Detection must come from the contract tests and monitoring, not from logs or alerts.
• Debugging:
  • Audit logs may obscure errors if transactions fail. Ensure proper error handling in listeners.
  • Laravel's try-catch blocks may need adjustment to log failures before rollback.
  • Triage rule: "missing audit row" should first be checked against the entity's presence in the include/exclude config, then against transaction/flush behaviour.
• User Context:
  • Debugging user attribution requires tracing from Laravel's Auth → Symfony's TokenStorage.
• Historical Reconciliation (new): Any incident review spanning the upgrade boundary must account for the fact that coverage changed. Define a cut-over timestamp and annotate it for downstream consumers.
• Community:
  • A new contributor and an active changelog improve the support picture; the project nonetheless has limited real-world adoption, so upstream fixes for edge cases may not arrive. Budget for internal fixes.

Scaling

• Performance:
  • Write Overhead: Audit logs increase database load. Test under production-like conditions.
  • New Lever: A correctly applied unaudited_entities list is now the first-line tool for reducing audit write amplification on high-churn tables — quantify the reduction rather than assuming it.
  • Mitigations:
    • Batch Processing: Use Laravel Queues to defer audit log inserts.
    • Indexing: Optimize audit tables for queries (e.g., entity_id, user_id).
• Data Volume: If the pre-upgrade behaviour was capturing excluded tables, audit table growth rate may drop materially after v1.3.2 — re-baseline capacity and retention assumptions rather than extrapolating from historical growth.
• Ramp-Up: Onboarding cost is unchanged for the framework itself but increases for configuration ownership — the on-call engineer must understand that this config controls audit coverage and is not a benign tunable. Capture this in the runbook alongside the contract tests.