Agent Laravel Laravel Package

Technical Evaluation

Architecture fit The package is an agent-side telemetry collector paired with a hosted dashboard. v1.18.0 extended the report payload with a php_code section; v1.21.0 adds distro build-suffix reporting for PHP (e.g. Ubuntu's -1ubuntu2.20) as a first-class field rather than something the dashboard infers. Neither release introduces a new service, queue, or storage dependency. Architecturally both are additive extensions of the agent→dashboard contract. The default posture remains metadata-only (file counts, sizes, and a path/size/mtime fingerprint), which aligns with the package's existing low-touch, read-only collection model.

Integration feasibility

• Default behaviour requires no configuration: scanning starts automatically for app/ and for composer.lock packages not resolvable on packagist.org, dev packages excluded. Expect a small, bounded increase in report-generation time (≤2s per report, with a deferred 20s retry path for slow packages).
• The ZIP content-upload capability is strictly opt-in via STACKMONITOR_AGENT_FILE_CONTENTS=true and hard-gated on ext-zip. This is a meaningful control: the default install ships no source code off-box.
• v1.21.0 is a payload-level addition with no new configuration, no new extension requirement, and no scanning cost of note — the build suffix is read from the runtime's PHP version string, not discovered by crawling the filesystem.
• Both v1.18.0 and v1.21.0 explicitly require a dashboard-first deployment. The dashboard must understand php_code.contents and, now, the distro build suffix. This is a version-skew constraint that must be encoded in the rollout plan, not discovered during it.

Technical risk

Key questions

1. What is the data-retention and access-control policy for uploaded ZIPs on the dashboard side, and is it covered by our DPA/security review?
2. Does the app/ scan include .env-adjacent or generated PHP (e.g. compiled views, cache files)? Are there exclusion patterns, or only the 5000-file cap?
3. What exactly is in the fingerprint (hashed or raw paths)? Is it reversible?
4. How does the agent behave when ext-zip is absent but the env var is true — silent disable, warning, or error?
5. Are there known performance issues in repositories with very large vendor/ trees, and does the 2s/20s budget hold on network-attached storage?
6. Which dashboard version first understands php_code.contents, and which first understands the distro build suffix? What is the minimum supported pairing for each?
7. How is the build suffix parsed and matched (distro + codename + revision), and does the dashboard distinguish security-pocket builds (e.g. -1ubuntu2.20 vs -1ubuntu2.19) reliably, or only warn/hint on the base version?
8. Are downgraded hints still exportable to our vulnerability reporting/SIEM pipeline, so that "hint" doesn't mean "invisible" to security operations?

Integration Approach

Stack fit Fits the existing Laravel/PHP agent deployment pattern: Composer package, env-driven configuration, no new infrastructure. The ZIP path depends on ext-zip (commonly present, but must be confirmed in base images and CI runners). The v1.21.0 build-suffix field adds nothing to the stack-fitness picture — it relies on the runtime PHP version string already available to the agent. No database migrations or new external services are implied.

Migration path

1. Upgrade the dashboard to a version that understands php_code, php_code.contents, and the distro build suffix.
2. Upgrade the agent with STACKMONITOR_AGENT_FILE_CONTENTS unset/false. This is behaviourally safe: new report fields are additive, and only metadata leaves the host.
3. Verify payload shape and scan timing in staging against a representative repo (including a monorepo and a symlinked-vendor case). Include at least one Ubuntu-based PHP image so the build suffix is populated and the hint-vs-warning behaviour can be observed.
4. Run the source-egress security review and get an explicit decision on the ZIP capability.
5. If approved, enable FILE_CONTENTS=true on a single canary app, then expand in cohorts.

Compatibility

• Backward compatible at the agent level: default config does not enable content upload, and the build suffix is an additive field.
• Forward compatible only if older dashboards ignore unknown report keys — verify before deploying agents broadly, because both releases mandate dashboard-first.
• Notify security/on-call that PHP vulnerability items on distro-patched builds may shift from warning to hint after the upgrade. This is a deliberate behaviour change, not a regression, but it should be a known item before it appears as a "missing alert".
• Confirm supported PHP/Laravel version matrix in composer.json against our current runtime baseline before scheduling.

Sequencing Dashboard → staging agent (metadata only) → production agent (metadata only, canary then fleet) → security decision → canary with content upload → broader enablement. Do not bundle the agent upgrade and the opt-in flag into the same change window; separating them keeps the blast radius of a rollback small. Because v1.21.0 changes alerting semantics, deploy it in its own window from the dashboard's vulnerability-reporting changes, so that any shift in warning counts is attributable to one change.

Operational Impact

Maintenance Low steady-state maintenance: no schema, no migrations, no new daemon. The main ongoing cost is config governance for the content-upload flag and periodic review of what counts as an "unresolvable" Composer package (private packages, path repositories, VCS dependencies). v1.21.0 adds a small second-order maintenance item: the distro-suffix mapping is a moving target as distros cut new security pockets, so dashboard-side parsing may lag newly patched builds. Expect occasional questions when the package inventory in the dashboard doesn't match team expectations, and separately when a PHP CVE shows as a hint rather than a warning.

Support New support surface: "why is my package missing from the PHP upgrade forecast?" Common causes will be dev-package exclusion, packagist-resolvable packages being skipped, the 5000-file cap, scan timeouts, and the 10-minute cache. Document these in the internal runbook. The cache means stale results are expected for up to 10 minutes after a deploy — support scripts should account for it rather than treating it as a bug.

Add a second runbook entry for v1.21.0: "why is this PHP vulnerability only a hint?" with the answer that the host's PHP build includes a distro revision and the dashboard assumes the distro backported the fix. Give support a way to verify the actual patch level (e.g. dpkg -l php* / distro changelog) when a hint is contested.

Scaling Per-report cost is bounded but real: ≤2s typical, with a slow package deferred and given 20s in a later report. Across a large fleet this is a modest CPU/IO increase, but it will be noticeable on shared hosts or network filesystems. The ZIP path is the only meaningful bandwidth consumer and is capped at 8MB per package per fetch. Because ZIPs are pulled on demand by package id rather than pushed with every report, request volume should be low — but confirm the dashboard caches them. The v1.21.0 field is effectively free from a scaling perspective.

Failure modes

Ramp-up Estimate half a day for a platform engineer to validate the metadata-only path in staging and a further 1–2 days for the security review if content upload is pursued. Teams consuming the forecast need no training beyond knowing where the data comes from and why some packages are absent. v1.21.0 needs a short briefing to security/on-call (15–30 minutes) so the warning→hint downgrade on distro-patched PHP isn't mistaken for lost coverage. The dashboard-first dependency remains the main scheduling constraint — plan it as a two-step release, not a single upgrade.

Recommendation Adopt the metadata-only capability by default; it is low-risk and directly supports PHP upgrade planning. Take v1.21.0 as part of the same metadata-only track — it is an additive field with no config or infrastructure cost, and the warning→hint behaviour is technically correct for distro-backported PHP fixes — but explicitly notify security/on-call and confirm hints remain visible in exports before rollout. Treat the ZIP content-upload feature as a separate, gated decision requiring security, legal, and data-handling sign-off — the env var makes it technically easy, which is precisely why the approval should be explicit and auditable.