Agent Laravel Laravel Package

Getting Started

StackMonitor is a self-hosted Laravel monitoring agent that ships a report to a dashboard on a schedule. The PHP-upgrade additions are the first thing to look at, because they answer a question every team asks before a PHP bump: which code is going to fight us?

1. composer require the agent, then publish its config (php artisan vendor:publish --tag=stackmonitor-config or equivalent) and check config/stackmonitor.php for the report/schedule block.
2. Set the usual credentials/URL for the dashboard in .env, then php artisan config:cache so the new keys are picked up by queue workers too.
3. Trigger a report manually (the agent's artisan command, or dispatch the report job) and inspect the outgoing payload.
   • Look for extra.php_code — the code-impact field introduced in v1.18.0.
   • Look for the PHP version entry — since v1.21.0 it also carries the distribution's build suffix (e.g. 8.3.6-1ubuntu2.20) as its own value, separately from the bare version.
4. First use case: run the report against a staging clone of your app and read extra.php_code before scheduling a PHP minor/major upgrade. It lists (a) your own app/ tree and (b) composer.lock packages that are not on packagist.org — i.e. your private/VCS/path-repository packages. Those are precisely the ones a composer update won't transparently replace.
5. Second use case (new in v1.21.0): if you run distro-packaged PHP (Ubuntu/Debian base images, ondrej PPAs, distro php8.3-* packages), read the distro build suffix before acting on a PHP vulnerability alert. Distro builds routinely backport security fixes without bumping the version number, so the dashboard now downgrades PHP vulnerability findings to a hint on those builds rather than a warning.

Only flip STACKMONITOR_AGENT_FILE_CONTENTS=true after the non-contents report looks sane; it is a separate, opt-in escalation.

Implementation Patterns

Treat the report as a pre-upgrade gate, not just telemetry. Wire the report into your upgrade process: generate a report on the release branch, diff extra.php_code entries between 8.2 and 8.3 branches, and attach the package list to the upgrade PR. The fingerprint (path + size + mtime over each *.php) gives you a cheap "did anything in this private package change since we last signed off?" signal between releases.

Use the distro build suffix to triage PHP CVEs correctly. Since v1.21.0 the report tells you what the distribution's build adds on top of upstream (Ubuntu's -1ubuntu2.20, for example). The dashboard's behaviour follows directly from that:

• Hint, not warning, when the distro build suffix is present — the dashboard is acknowledging that Ubuntu/Debian may already have backported the fix without changing 8.3.6.
• Warning when you're on a plain upstream build with no distro suffix.

Practically: a hint is a prompt to check apt changelog php8.3 / your distro's security tracker, not a green light. A warning on a self-compiled or official-Docker-image PHP deserves immediate attention. Encode that branch in your runbook so nobody treats "hint" as "safe".

Track the suffix, not just the version, across deploys. Because 8.3.6-1ubuntu2.19 → 8.3.6-1ubuntu2.20 is a real security change with an identical upstream version, diff the suffix between reports the same way you diff extra.php_code. A suffix bump on an apt upgrade is the signal that a previously-hinted CVE may now be patched — or that a new backport landed.

Understand the timeboxing, then design around it. Each report gets 2 seconds of file-listing budget. Packages that don't finish queue up and one of them gets a dedicated 20-second report later. Practical consequence: on a codebase with one huge private vendor package, expect the first report to be partial and to fill in over the following cycles. Don't build a dashboard tile that assumes completeness on report #1 — show "pending" instead of an empty list.

Lean on the 10-minute cache. The scan result is cached for 10 minutes, so it is safe to run the report more frequently than you'd otherwise dare (e.g. hourly or on every deploy) without re-walking the filesystem each time. Make sure the cache store backing this is a real shared store (redis, file, database) — not array, and not a per-request store. Under Octane or a multi-container deploy, an inconsistent cache means inconsistent reports.

Keep the contents flag for a narrow window. The STACKMONITOR_AGENT_FILE_CONTENTS=true path is best used deliberately: enable it, let the dashboard pull the ZIP for the one package you're auditing, then turn it off. That avoids an evergreen "source code egress" checkbox in your security review. Gate it per-environment: on in staging, off in production, unless your data policy has explicitly cleared sending PHP source to the dashboard host.

Order of operations for a rollout. Deploy the dashboard first, then the agent, then flip the flag. The report publishes php_code.contents as a capability marker; older dashboards that don't know the field will either ignore it or error on it. Same discipline for v1.21.0: a dashboard that doesn't understand the distro build suffix will at best ignore it and fall back to warning-on-everything, at worst mis-render the version string — so upgrade the dashboard before the agents.

Gotchas and Tips

• Dashboard-first is mandatory. The release notes say it outright: the dashboard must know php_code.contents before the agent starts emitting it. If you run the dashboard and agents from separate release trains, pin the dashboard version forward first. The v1.21.0 distro-suffix field follows the same rule.
• Don't string-compare PHP versions any more. PHP_VERSION on Ubuntu is 8.3.6-1ubuntu2.20, not 8.3.6. Any monitoring, feature-gate or alerting code that does equality or version_compare against a bare semver will start behaving oddly once the suffix is surfaced. Compare the upstream portion separately from the build suffix.
• The hint/warning downgrade is version-string-based, not vulnerability-database-based. It keys off the presence of a distro build suffix. If you compiled PHP yourself from distro sources and kept a -1ubuntu2.x suffix by accident — or a custom build that mimics one — you'll get the softer hint. Verify against the actual package, not just the label.
• Distro builds lag on non-security fixes. The downgrade only holds for security backports. A distro build can be on an upstream minor that predates a deprecation or a bugfix you're relying on. Use the hint as "no urgent CVE action", never as "this is the same PHP as upstream 8.3.6".
• zip extension is a hard dependency for the contents path. Without ext-zip, the dashboard simply cannot fetch file contents — the report will honestly say contents are off. Check php -m | grep zip in the container image before you file a bug.
• Hard caps you will hit: 5000 files per package (packages above that are skipped entirely — not truncated, so they won't appear at all) and 8 MB of ZIP. A private package with a generated resources/ tree can silently fall out of the forecast. Exclude generated PHP (compiled views, proxy classes, stubs) from your private packages, or split them.
• Symlinks aren't followed. Linked folders inside a package are deliberately skipped. If you use a path-repository with a symlinked vendor directory, the report will look empty — that's the feature, not a bug. Use a real path repo or a private packagist mirror.
• Dev-only packages are excluded from the composer.lock scan. Your private test helpers and require-dev tooling won't be fingerprinted. This is fine for upgrade forecasting but means the report is not an inventory of everything in vendor/.
• The fingerprint is path + size + mtime, not a content hash. A rebase that preserves mtimes (rare, but common in Docker layers with fixed timestamps) or a same-size edit within the same second can go undetected. Treat a "no change" fingerprint as probably no change, and composer install cleanly before an audit if you need certainty.
• "No content leaves the server" only holds while the flag is off. The listing itself (paths, sizes, dates) still goes to the dashboard. If path names are sensitive, that's worth a note in your privacy review.
• Debugging a missing package: check the cache first (php artisan cache:forget the relevant key, or just wait 10 minutes), then check whether the package's vendor folder contains a symlink, then check the file count against the 5000 cap. Those three account for nearly every "it's not showing up" report.
• Debugging a wrong PHP version: if the dashboard shows a bare version with no distro suffix on a host you know runs distro PHP, check that the agent is at >= v1.21.0 and that the dashboard understands the field. The suffix is reported by the agent, so a stale agent on one node in a fleet makes that node look like a self-compiled build — and its CVE findings will look louder than the rest of the fleet.
• Config caching bites when toggling the flag. STACKMONITOR_AGENT_FILE_CONTENTS is read from config; if you set it at runtime in .env without re-running config:cache (or without clearing it), the agent keeps the old value — so the dashboard sees contents: true while no ZIP is available, or vice versa.