Introduction

Excubia is an open-source (MIT) health check for Laravel apps, part of the Qiick suite. The Composer package qiick/excubia-core reads your lockfiles and manifests and reports, in one place: PHP / Laravel / Node end of life, known vulnerabilities, abandoned and stale packages, blockers for the next Laravel major, and a suggested upgrade order. Run through Artisan, it also checks the posture of the booted app (debug mode, caches, migrations, failed jobs, scheduler, maintenance mode).

Optional, and off by default: push the report to your own self-hosted excubia-app, send runtime aggregates and masked exceptions to it, or serve an Oh Dear-compatible health endpoint. Nothing is sent to Qiick or any third party.

Status: 1.0.0-beta. The public contracts (CLI options, report JSON, check ids, exit codes, excubia.json, push payloads, health endpoint, SARIF ids, Action inputs) are frozen for 1.0.0-beta: docs/CONTRACTS.md. See docs/ROADMAP.md and docs/VERSIONING.md.

Requirements

Any Composer project can be scanned. Laravel-specific checks are skipped when laravel/framework is not locked.

Quick start

composer require --dev qiick/excubia-core
vendor/bin/excubia check

vendor/bin/excubia does not boot your app and never runs project code. In a Laravel app the package is auto-discovered, so the same checks plus the six posture checks run with:

php artisan excubia:check

Install without --dev (composer require qiick/excubia-core) when the deployed app runs Excubia itself: the scheduled push, runtime monitoring, exception capture, the health endpoint or posture checks in production. While those opt-ins are off, the package registers four Artisan commands and one every-minute scheduled heartbeat, and nothing else.

More examples:

vendor/bin/excubia check --format=json --output=report.json
vendor/bin/excubia check --format=markdown --output=report.md
vendor/bin/excubia check --fail-on=critical
vendor/bin/excubia check --only=php-eol,composer-advisories
vendor/bin/excubia check --skip=node-eol --no-dev
vendor/bin/excubia check ../other-project --offline
vendor/bin/excubia cache:clear
vendor/bin/excubia --version

Checks

• The six laravel-* posture checks after laravel-next-blocker need the booted app, so only php artisan excubia:check and excubia:push run them. vendor/bin/excubia reports them as skipped ("requires Artisan").
• For laravel-scheduler-heartbeat, the service provider schedules php artisan excubia:heartbeat every minute. It stores the Unix time under the cache key excubia:scheduler-heartbeat in the default cache store. Keep the usual * * * * * php artisan schedule:run cron (or schedule:work), and use a shared cache store (database, Redis) when the scheduler and excubia:check run on different machines.
• Every report ends with an ordered upgrade plan (upgrade-plan): security fixes, runtime EOL, blockers, Laravel major, replacements. It is info only, never changes the exit code and cannot be selected with --only / --skip.
• Thresholds (180 days, 24 months, 10 minutes, 24 hours) are configurable in excubia.json. Full severity rules: docs/SPEC.md section 3.

Formats

In the JSON report every skipped finding has a skipReason: data-source-failure, offline (--offline found no cached response) or not-applicable (the check does not apply or is disabled).

The JSON report also carries, as optional fields of schema version 1:

• top level: generatedAt (UTC, Y-m-d\TH:i:s\Z), excubiaVersion (the value of --version) and project with php, laravel and node, each {version, cycle, securitySupportEndsOn, activeSupportEndsOn} or null when not declared (no name, path or hostname). The cycle and the Y-m-d dates come from the endoflife.date data the EOL checks already read, also when they pass; they are null when that check was skipped or did not run;
• per finding: fingerprint (sha256 of checkId, subject and advisoryId joined by a NUL byte, the same value as the SARIF partialFingerprints, stable across runs), advisoryId on advisory findings, and details with check-specific values so you do not parse message:

laravel-debug-mode, laravel-production-caches, laravel-maintenance-mode and other skipped rows have no details. The exact rules are in docs/report-schema.json.

CLI

vendor/bin/excubia check [path] [options]
vendor/bin/excubia push [path] [--config=FILE] [--strict]
vendor/bin/excubia cache:clear [path] [--config=FILE]

path is the project directory to scan (default: the current directory).

The Artisan commands take the same options, without path (they always scan the app's base path):

Exit codes

When several apply, 2 wins over 1, and 1 wins over 3, so CI sees real findings first.

Strict mode is --strict or "strict": true. A failed data source means the network was down with no cached response, or an API answered an error; the message on stderr names each check and data source. Without strict mode such checks are only marked skipped and the exit code ignores them. Deliberate skips never exit 3: --offline without a cached response, --only / --skip, Laravel checks on a non-Laravel project, a disabled check, or a row removed by an ignore rule. --strict can only turn strict mode on: it wins over "strict": false, and nothing on the command line turns "strict": true off.

Privacy

By default only package names and versions (and runtime versions) leave the machine, and only to the public data sources in the check table. No file contents, .env values, source code, paths or hostnames. Private packages (path, VCS, Satis, Private Packagist, file: or other-registry origins in the lockfile, plus privacy.skipPackages) are never sent and show as skipped. No telemetry. Each opt-in that sends data to your own excubia-app is listed field by field in the privacy guide.

Versioning and support

Excubia follows SemVer. Public contracts change only in a major; deprecated options keep working with a warning for at least one minor. In 0.x, minors may still break and only the latest minor gets fixes. Policy and supported versions: docs/VERSIONING.md. The list of public contracts, with their files, version fields and contract tests: docs/CONTRACTS.md; everything else (PHP classes, message wording, table and Markdown layout) is internal.

Guides

• Configuration reference
• CI
• Push to excubia-app
• Runtime monitoring
• Exception capture
• Health endpoint
• Privacy
• Upgrading from 0.x to 1.0