ahmido
ec71c2d4e7
## Summary - harden finding lifecycle changes behind the canonical `FindingWorkflowService` gateway - route automated resolve and reopen flows through the same audited workflow path - tighten tenant and workspace scope checks on finding actions and audit visibility - add focused spec artifacts, workflow regression coverage, automation coverage, and audit visibility tests - update legacy finding model tests to use the workflow service after direct lifecycle mutators were removed ## Testing - `vendor/bin/sail bin pint --dirty --format agent` - focused findings and audit slices passed during implementation - `vendor/bin/sail artisan test --compact tests/Feature/Models/FindingResolvedTest.php` - full repository suite passed: `2757 passed`, `8 skipped`, `14448 assertions` ## Notes - Livewire v4.0+ compliance preserved - no new Filament assets or panel providers introduced; provider registration remains in `bootstrap/providers.php` - findings stay on existing Filament action surfaces, with destructive actions still confirmation-gated - no global search behavior was changed for findings resources Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #181
121 lines
5.3 KiB
Markdown
121 lines
5.3 KiB
Markdown
# Quickstart: Findings Workflow Enforcement and Audit Backstop
|
|
|
|
## Goal
|
|
|
|
Verify that findings lifecycle mutations now follow one canonical workflow path and always produce durable audit history for covered changes.
|
|
|
|
## Prerequisites
|
|
|
|
1. Start Sail if it is not already running.
|
|
2. Use a workspace and tenant with at least one authorized findings operator.
|
|
3. Ensure test factories can create findings in multiple statuses.
|
|
|
|
## Focused Verification Flow
|
|
|
|
### 1. Run the focused post-implementation findings workflow suites
|
|
|
|
```bash
|
|
vendor/bin/sail artisan test --compact \
|
|
tests/Feature/Findings/FindingWorkflowGuardTest.php \
|
|
tests/Feature/Findings/FindingWorkflowServiceTest.php \
|
|
tests/Feature/Findings/FindingWorkflowUiEnforcementTest.php \
|
|
tests/Feature/Findings/FindingWorkflowRowActionsTest.php \
|
|
tests/Feature/Findings/FindingWorkflowViewActionsTest.php \
|
|
tests/Feature/Findings/FindingAuditBackstopTest.php \
|
|
tests/Feature/Audit/FindingAuditVisibilityTest.php \
|
|
tests/Feature/Findings/FindingRbacTest.php
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- workflow mutations succeed only for allowed transitions
|
|
- list and view action surfaces still execute the canonical workflow gateway
|
|
- owner reassignment and reason-bearing workflow mutations follow the same gateway and validation rules
|
|
- audit entries are written exactly once per covered mutation
|
|
- non-members get `404`
|
|
- in-scope users without capability get `403`
|
|
|
|
### 2. Run the automation and recurrence suites
|
|
|
|
```bash
|
|
vendor/bin/sail artisan test --compact \
|
|
tests/Feature/Findings/DriftStaleAutoResolveTest.php \
|
|
tests/Feature/PermissionPosture/PermissionPostureFindingGeneratorTest.php \
|
|
tests/Feature/EntraAdminRoles/EntraAdminRolesFindingGeneratorTest.php \
|
|
tests/Feature/Findings/FindingRecurrenceTest.php \
|
|
tests/Feature/Findings/FindingAutomationWorkflowTest.php \
|
|
tests/Feature/Findings/FindingWorkflowConcurrencyTest.php
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- system-origin resolve and reopen mutations emit canonical audit rows
|
|
- recurrence and stale-auto-resolve paths use the same lifecycle truth as human actions
|
|
- older automated observations do not override newer human terminal decisions
|
|
|
|
### 3. Run the existing findings compatibility suites
|
|
|
|
```bash
|
|
vendor/bin/sail artisan test --compact \
|
|
tests/Feature/Findings/FindingAuditLogTest.php \
|
|
tests/Feature/Findings/FindingBulkActionsTest.php
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- legacy findings flows still pass on top of the canonical gateway and audit backstop
|
|
|
|
### 4. Run the Filament action-surface contract guard
|
|
|
|
```bash
|
|
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- the Findings resource still satisfies the required Filament action surface slots after workflow rewiring
|
|
- grouped actions, inspection affordances, and mutation visibility rules remain intact
|
|
|
|
### 5. Verify tenant-context UI actions
|
|
|
|
1. Open the Findings page for an entitled tenant.
|
|
2. Execute `Triage`, `Start progress`, `Assign`, `Resolve`, `Close`, `Risk accept`, and `Reopen` on representative findings, including an owner reassignment case and a reason-required transition.
|
|
3. Confirm that disabled actions remain visible for members without capability and execute as `403` if forced server-side.
|
|
|
|
Expected outcome:
|
|
|
|
- existing Findings action surfaces remain unchanged from the operator perspective
|
|
- destructive-like workflow actions still require confirmation
|
|
- `Close` and `Risk accept` are only visible for open findings; `Reopen` is only visible for terminal findings
|
|
- invalid transitions fail safely and do not mutate the record
|
|
- no workflow mutation bypasses the existing Findings action surface contract
|
|
|
|
### 6. Verify audit review
|
|
|
|
1. Open the canonical Audit Log surface.
|
|
2. Filter to finding-related audit rows.
|
|
3. Confirm that workflow history shows actor, tenant scope, before state, after state, owner or assignee changes, and transition reason where applicable.
|
|
4. Confirm that an authorized audit viewer can still understand the historical event when the live finding is deleted, merged away, or no longer directly accessible.
|
|
|
|
Expected outcome:
|
|
|
|
- finding audit rows remain readable even if the live finding is no longer directly visible
|
|
- unauthorized audit viewers do not see finding-related tenant details outside their entitlement scope
|
|
- internal bookkeeping metadata such as `_actor_type` and `_dedupe_key` do not render in the inspection view
|
|
|
|
## Implementation Sequence
|
|
|
|
1. Consolidate lifecycle mutations behind the canonical findings workflow gateway.
|
|
2. Neutralize direct `Finding` lifecycle mutators and other bypass paths in covered services.
|
|
3. Cover owner reassignment and reason-bearing lifecycle updates with the same gateway and audit contract.
|
|
4. Adopt the same gateway for auto-resolve and recurrence flows.
|
|
5. Normalize audit action registration and metadata expectations.
|
|
6. Add regression guards and focused test coverage, including the Filament action-surface guard.
|
|
|
|
## Rollout Notes
|
|
|
|
- Prefer additive code-path hardening over schema changes.
|
|
- Keep legacy `acknowledged` rows readable during rollout.
|
|
- Human and system-origin lifecycle mutations now converge on the same workflow gateway and audit contract.
|
|
- Workspace mismatch remains deny-as-not-found on the policy path and deny-safe on the Filament action path.
|
|
- Run the focused findings and audit suites before broader tenant workflow or baseline suites. |