Warden Laravel Package

Product Decisions This Supports

• Build vs. buy for security scanning. Warden is a dev-only, in-repo Laravel scanner that a PM can adopt without procurement, a SaaS contract, or a data-sharing review. The 2.2 release strengthens the "buy" case on integration depth (native artisan command, framework-aware analysis, CI bootstrapping) rather than on breadth, so the decision is really "adopt a Laravel-native gate alongside, not instead of, a platform SAST/SCA tool."
• CI cost and pipeline simplification. One scan now emits multiple artifacts (--report=json-v2.1:… --report=sarif:… --report=junit:…) sharing a single timestamp, suppression set, and gate outcome. That is a direct lever on CI minutes and on the number of pipeline steps a platform team has to maintain: one job can simultaneously feed GitHub code scanning, a JUnit test dashboard, and a retained compliance artifact. If your pipeline currently runs the scanner two or three times to get different formats, this release removes that duplication.
• Gate policy as an explicit product decision. --fail-on drives JUnit failures and GitHub annotations consistently across all reports, which means "what blocks a merge" is now a single, auditable knob rather than per-format behavior. Choose the severity threshold deliberately and document it as policy; the package now makes the gate visible in the extended report schemas, which is what auditors and platform reviews tend to ask for.
• Suppression and exception governance. Fingerprints must be lowercase SHA-256 and expiry dates must be real calendar dates, with malformed suppressions exiting 2 before any scanning. This turns suppressions into a time-boxed, auditable exception register instead of free-text that can silently rot. It supports a real process decision: require expiry dates on every waiver, and treat a malformed suppression file as a build break rather than a warning.
• Honest "no false all-clear" reporting. Unreadable directories now make a scan incomplete, with scanned/skipped/error counts exposed in console and json-v2.1 output, and counts explicitly documented as lower bounds. This is the deciding input for a risk-acceptance decision: a clean-but-incomplete scan is materially different from a clean complete scan, and the tooling now refuses to conflate them. Pair it with a policy that incomplete scans never count as evidence of compliance.
• Notification routing and on-call design. Delivery requires both a notification flag and a configured channel, and never changes the audit exit code — clean separation between "the build is red" and "someone was told." Incomplete scans with no findings stay silent in finding-only mode unless warden.notifications.on_errors=true is set. That is a product decision your team has to make explicitly: opt in if you want noise about coverage gaps, leave it off if you only want to be paged on findings.
• Roadmap sequencing for the upgrade itself. Stricter detection (sink-scoped sanitizers, alias/typed-Request/named-argument resolution, hidden-file and per-line credential coverage) is likely to surface findings that were previously hidden. Plan a triage sprint before rollout rather than treating the new findings as regressions; budget remediation capacity against an expected, not hypothetical, backlog.
• Schema/contract management. Default JSON stays on the 2.0.0 schema and new JsonReporter() remains compatible; json-v2.1 (with gate and coverage fields) is opt-in via --format=json-v2.1, --report=json-v2.1:path, or new JsonReporter(extended: true). Generated CI opts in for you. This is a low-risk contract story to communicate to any team consuming Warden output downstream.

When to Consider This Package

Consider adopting when:

• You run PHP 8.3–8.5 on Laravel 12–13 and want a security gate that lives in composer.json as a dev dependency, with no data egress and no seat-based pricing negotiation.
• You want first-party CI bootstrapping: generated GitHub workflows that retain reports, summarize results, and offer opt-in SARIF upload; generated GitLab includes that preserve existing stages, retain artifacts, and install npm when a lockfile is present (with npm-shrinkwrap.json correctly taking precedence over package-lock.json, and report output identifying which lockfile was selected).
• You need SARIF into GitHub code scanning or GitLab dependency scanning (schema 15.2.4) from a tool that also produces JUnit and a stable JSON contract — i.e., you are wiring one scanner into several dashboards and don't want per-format divergence.
• You want baselines and fingerprints that survive refactors: this release explicitly preserves existing fingerprint and baseline matching for unchanged source despite the name-resolution improvements, which is the difference between an adoptable upgrade and a re-baselining project.
• You have a lightweight governance need: time-boxed suppressions, an auditable gate threshold, and coverage counts that a reviewer can read without a training course.
• You are specifically worried about credentials in files people forget: .env.example and .github files are now in scope, every credential match on a line is examined, and .env itself stays excluded. Equivalent paths like ./app and app/. resolve identically, so CI invocations are predictable.

Look elsewhere when:

• Your repo is polyglot. A Laravel/PHP-source analyzer will not cover Go services, Terraform, containers, or frontend dependencies; you need Semgrep/CodeQL/Snyk-class coverage, likely in addition.
• You need software composition analysis (known-vulnerable dependencies, license checks) or runtime/DAST testing. This is static source and credential analysis; it is not a dependency scanner and not a runtime probe.
• You need hosted triage workflows: trend dashboards, assignee routing, mean-time-to-remediate reporting, or vendor SLAs and compliance attestations (SOC 2 report, pen-test letters). An OSS single-maintainer dev tool will not satisfy a vendor-risk questionnaire on its own.
• You need deep interprocedural taint/dataflow analysis. This is pattern- and framework-aware analysis with sink/sanitizer pairing; the 2.2 accuracy work narrows false negatives but does not make it a whole-program dataflow engine.
• Secrets detection at scale with entropy scoring, live-token validation, and revocation workflows is a requirement — this is file-based credential matching, improved but not a dedicated secrets platform.
• Your team cannot absorb a findings backlog. Stricter detection on upgrade means new findings. If there is no triage owner, the gate either gets disabled or gets a wildcard suppression file, and you have paid the integration cost for no risk reduction.
• You need scale guarantees on a very large monorepo, or you need the scanner to be a supported commercial dependency with an escalation path.

One operational caveat worth flagging before you commit: the release notes state that Composer derives the package version from Git tags and that merging, tagging, and publication are separate steps. Verify the tag is actually published before pinning ^2.2 in CI, and read UPGRADE.md for the intentional validation and notification changes.

How to Pitch It (Stakeholders)

For executives (one paragraph). Warden 2.2 is a low-cost, low-risk upgrade to a security check we run in CI: one scan now produces every report format our pipeline and auditors need, detection gets meaningfully better at catching real leaks, and the gate stays a single configurable threshold. Nothing downstream breaks — the default report format is unchanged and new fields are opt-in. The cost is a triage pass for findings the stricter analysis will newly surface; the benefit is a defensible, repeatable "we scan every change and we can prove what we found" story.

For engineering leads. The upgrade is additive. Default JSON, including public object serialization and new JsonReporter(), stays compatible with the unchanged strict 2.0.0 schema; the new gate and coverage fields live under a separate opt-in 2.1.0 schema, and the generated CI already opts in. Existing fingerprints and baselines keep matching unchanged source, so nobody re-baselines. The practical change is one scan producing multiple reports, which lets us delete redundant pipeline steps. Expect new findings — sink-scoped sanitizers, alias/Request/named-argument resolution, hidden-file credential coverage, and per-line credential matching are all false-negative reductions, not behavior regressions. Treat those as the point of the upgrade, not as breakage.

For security and compliance reviewers. Three properties matter here. First, integrity is now fail-fast: malformed suppression fingerprints or impossible expiry dates exit 2 before scanning, so an exception register cannot silently degrade. Second, coverage is honest: unreadable directories produce an explicitly incomplete scan with scanned/skipped/error counts documented as lower bounds, and incomplete reports describe the error rather than claiming all-clear. Third, notifications cannot corrupt results — delivery requires a configured flag and channel, never changes the audit exit code, and incomplete-scan alerting is an explicit opt-in (warden.notifications.on_errors=true). Teams payloads are capped at 28,000 encoded bytes with a pointer to the full report, so alerting degrades predictably. The right policy to pair with this: no suppression without an expiry, and no clean-build claim from an incomplete scan.

The ask. Approve a one-repo pilot at --fail-on=high with SARIF upload enabled, measure the newly surfaced findings over two weeks, then decide on org-wide rollout and triage capacity with real numbers instead of estimates. Success looks like: pilot repo green on a complete scan, a suppression file with dated expiries, and a triage budget the team has actually agreed to.