Warden Laravel Package

Technical Evaluation

Architecture fit

• Warden is a dev-only Composer package exposing an Artisan command (warden:audit). No runtime dependency, no service to operate, no data plane — it fits a Laravel application/monorepo's existing CI and local tooling with near-zero architectural surface area.
• It sits in the SAST/secret-scanning layer of the stack, adjacent to (not overlapping with) composer audit, Dependabot, and platform-level code scanning. Multi-report output in 2.2 is the significant architectural improvement: one scan now feeds JSON, SARIF, JUnit, and GitHub annotations from a single timestamped, gated result set, which removes the common anti-pattern of running the scanner three times to satisfy three consumers.
• Schema versioning is decoupled from the package version (JSON 2.0.0 default, json-v2.1 opt-in, SARIF 2.1.0, GitLab dependency scanning 15.2.4, baseline 1.0.0). That is good contract hygiene but introduces a second axis to track during upgrades.

Integration feasibility

• Installation is a single composer require --dev and the command runs anywhere PHP CLI runs; generated GitHub/GitLab workflows reduce the setup effort to reviewing a diff. Generated GitLab jobs preserve existing stages, which lowers the political cost of adoption in an established pipeline.
• The default JSON contract is explicitly unchanged, so any existing downstream consumer (dashboards, custom parsers) keeps working through the 2.2 bump. Gate and coverage fields require an explicit opt-in to json-v2.1 — a clean, reversible migration lever.
• Legacy findings-only notification channel methods remain available, so existing custom channel integrations are not forced into a rewrite in this release.

Technical risk

• Stricter detection is the headline risk. Sanitizers are now scoped to their corresponding sink, and aliases, typed Request parameters, and named arguments are resolved. This will surface findings that were previously masked. Teams gating with --fail-on should expect red builds on upgrade day without any code change. Fingerprint/baseline stability is claimed for unchanged source, but that claim needs validation against our own codebase, not accepted from release notes.
• Suppression validation is now hard-failing. Malformed fingerprints (non-lowercase or non-SHA-256) and invalid expiry dates cause exit 2 before scanning. Any hand-edited or script-generated suppression file is now a pipeline-breaking artifact. This is fail-closed and defensible, but it is a breaking change in practice for teams with loose suppression hygiene.
• Hidden-file credential scanning expands the finding surface to .env.example, .github files, and similar. Expect a burst of low-severity findings in committed example/config files, and a triage/allowlist burden immediately after adoption.
• Support matrix is narrow: PHP 8.3–8.5 and Laravel 12–13 only. Applications still on Laravel 10/11 cannot adopt this line and will require a separate pinned version or exclusion — a portfolio-wide rollout is not a single decision.
• New abort path: equivalent report destinations (symlinks, existing hard links) are rejected before scanning. Sensible, but it is another pre-flight failure mode to document for whoever writes the CI invocation.
• Report volume and PII-adjacent content: SARIF/JSON artifacts now routinely contain file paths and code snippets and are retained by generated workflows. Artifact retention policy is a security-review item, not just a CI-config item.

Key questions

1. Is Warden's source analysis true interprocedural dataflow, or pattern/heuristic matching with sink–sanitizer pairing? This determines how much triage burden the "stricter detection" produces.
2. What is the measured false-positive rate on a representative Laravel codebase, and is there a documented triage workflow beyond raw suppressions?
3. How long are the 2.0.0 JSON and 1.0.0 baseline schemas supported? Is there a deprecation policy tying package majors to schema majors?
4. Does the tool phone home, send telemetry, or fetch rule updates at runtime? Relevant for air-gapped and regulated CI environments.
5. Who owns suppression files and baselines — application teams or a central AppSec function — and is there a review process for rule-wide suppressions (fingerprint omitted), which are the highest-blast-radius suppression type?
6. How do SARIF results map to GitHub code-scanning categories for de-duplication across branches and PRs?
7. What is the support window per Warden major, and how does it track the Laravel release cadence?
8. For incomplete scans: can CI be configured to fail the build on incomplete coverage rather than merely reporting it?

Integration Approach

Stack fit

• Native fit for Laravel 12–13 services on PHP 8.3–8.5 with GitHub Actions or GitLab CI. Good fit for monorepos that need several report consumers simultaneously.
• Complementary, not substitutive: retain composer audit/Dependabot for dependency CVEs and platform code scanning for language-level SAST. Position Warden as the Laravel-aware application-security layer covering secrets, taint-style sinks, and framework-specific sanitizer semantics.
• Poor fit for pre-Laravel-12 applications and for stacks without a PHP CLI runner in CI.

Migration path

• Greenfield (no scanner): pilot on one high-traffic service; run report-only for two sprints; then enable --fail-on=high.
• From Warden 2.1 → 2.2: bump to ^2.2 with --with-all-dependencies, regenerate CI workflows, and run a report-only comparison scan before re-enabling the gate. Diff the finding set against the 2.1 baseline to isolate stricter-detection deltas from real regressions.
• From a competing scanner: run in parallel for one to two sprints, compare finding sets on the same commits, and only then retire the incumbent. Do not dual-gate — two failing scanners in one PR is a developer-experience problem, not a security improvement.
• Suppression cleanup is the critical-path task. Normalize all fingerprints to lowercase SHA-256 and all expiries to real calendar dates before the version bump lands, otherwise exit 2 will block every build.

Compatibility

• Default JSON (2.0.0) and public object serialization, including new JsonReporter(), remain unchanged — existing parsers and dashboards are safe.
• json-v2.1 (via --format=json-v2.1, --report=json-v2.1:path, or new JsonReporter(extended: true)) is opt-in and required for gate and coverage fields. Generated GitLab config explicitly opts in; the GitHub summary tolerates legacy reports lacking gate data, which gives a mixed-version fleet a soft landing.
• SARIF 2.1.0 is consumable by GitHub code scanning; GitLab dependency scanning 15.2.4 is supported. Notification preferences carry forward; legacy findings-only channel methods still exist.
• Generated GitLab includes now install npm when a lockfile is present, with npm-shrinkwrap.json taking precedence over package-lock.json — verify this does not lengthen pipeline runtime unexpectedly on JS-bearing Laravel apps.

Sequencing

1. Pin dgtlss/warden:^2.2 in a branch; confirm PHP/Laravel matrix compatibility per repository.
2. Run an ungated audit with default JSON; snapshot the finding set as the pre-upgrade baseline.
3. Triage stricter-detection deltas: classify as true positive (fix), accepted risk (suppression), or false positive (raise upstream).
4. Normalize suppression files (lowercase SHA-256, valid ISO dates, explicit rule-wide only where justified); verify exit 0/2 behavior in a scratch pipeline.
5. Adopt multi-report in CI: --fail-on=high plus --report=json-v2.1, --report=sarif, --report=junit. Confirm no two report paths resolve to the same inode.
6. Enable SARIF upload as opt-in to GitHub code scanning; set artifact retention explicitly.
7. Decide notification posture: keep finding-only default, or set warden.notifications.on_errors=true so incomplete scans are never silent. Document that delivery never changes the audit exit code.
8. Regenerate GitHub/GitLab workflows, review the diff, and confirm existing stages and artifacts survive.
9. Publish a short internal runbook: how to suppress, how to read coverage counts, who approves rule-wide suppressions.

Operational Impact

Maintenance

• Ongoing work concentrates in three artifacts that did not previously require discipline: suppression files (now schema-validated), baselines, and CI workflow files (now generated and therefore subject to regeneration drift).
• The package version, the JSON schema version, the baseline schema version, and the SARIF/GitLab schema versions move independently. Maintenance planning must track all of them; a "minor" package bump can still alter output contracts if a team opts into a newer schema.
• Support-matrix churn (PHP 8.3–8.5, Laravel 12–13) creates a recurring quarterly task per repository rather than a one-off install.

Support

• Needs a named owner. Most organizations should assign suppression/baseline stewardship to AppSec and pipeline ownership to the platform team; leaving both to individual squads produces inconsistent gates and orphaned suppressions.
• Developer-facing surface is small (php artisan warden:audit plus flags), so first-line support load is low. Second-line load concentrates on triaging new findings after each stricter-detection release, which is recurring and non-trivial.
• Upstream dependency on a small maintainer team (single PR #35 for this release) is a supply-chain consideration; pin versions and review diffs rather than floating to *.

Scaling

• Multi-report is a direct CI-cost win: one scan, one timestamp, one gate, N report formats. Previously this implied N scans per pipeline.
• Cost drivers at scale are scan wall-clock on large repositories and the human triage of findings, not the tooling itself. Budget triage capacity before broad rollout.
• Notification fan-out has explicit limits: Teams payloads cap at 28,000 encoded JSON bytes and truncate with a pointer to the full report. High-finding-count repositories will effectively always hit truncation, so the report artifact — not the chat message — must be the source of truth.
• Unreadable directories produce coverage counts that are explicitly lower bounds. In large or permission-heterogeneous runners, "scanned" counts should not be presented as completeness guarantees.

Failure modes

• Exit 2 before scanning on malformed suppressions: fail-closed, but presents as a pipeline outage rather than a security finding. Document the error text and remediation steps.
• Incomplete scans with on_errors=false are silenced entirely, including incomplete reports that contain findings. That is a legitimate operator choice but a genuine "green build, unknown coverage" risk; the default (missing/null uses existing filters) is safer.
• Silent incomplete scans in finding-only mode when there are no active findings — teams can believe they are clean when the scanner simply could not read part of the tree. Set on_errors=true unless there is a strong reason not to.
• Notification delivery is decoupled from the gate: a delivered alert never changes the exit code, and a failed delivery never fails the build. Alerting reliability is therefore unverified by CI; treat it as best-effort.
• Report path collisions (symlinks, pre-existing hard links) abort the run. Avoid templated output paths that can resolve to the same file.
• Post-upgrade gate failures from stricter sanitizer scoping are the most likely day-one incident; mitigate with a report-only soak period.
• Schema drift if some repositories opt into json-v2.1 and others do not, producing dashboards that variously lack gate and coverage fields.

Ramp-up

• Low for developers: one command, readable console output, findings map to source lines.
• Medium for whoever owns CI and suppressions: exit-code semantics, schema selection, path-collision rules, and notification precedence (on_errors vs. finding-only mode) each need a documented decision.
• Plan roughly one sprint for a pilot service end-to-end (install → triage → gate → notifications → workflow regeneration), then a repeatable half-day per additional repository once suppressions and templates are standardized.