Download the PHP package andreapollastri/checkpoint without Composer

Checkpoint

A Laravel security scanner that audits your application for common vulnerabilities — from known CVEs to hardcoded secrets — via a single Artisan command.

What it checks

Requirements

• PHP ^8.1 is the package floor. Newer Laravel versions may require a higher PHP, so your effective minimum is whatever your Laravel major demands.
• Laravel 8–13 (same major as illuminate/* 8.x–13.x used by your app)

Installation

The package auto-discovers itself via Laravel's package discovery — no manual registration needed.

Recommended companion tools

Checkpoint is a static scanner — it inspects your codebase but doesn't intercept package installs. To harden the npm install path against the next event-stream/ua-parser-js/chalk-style supply-chain attack, pair Checkpoint with defense in depth: run installs inside containers and add a runtime guard on the host when you must install locally.

Docker (recommended)

Run composer install, npm install, and php artisan checkpoint:scan inside a container, not directly on your laptop or server shell. Supply-chain malware often executes during a package's post-install script — if that runs on your host, it has access to your SSH keys, browser cookies, and filesystem. A disposable dev container limits blast radius to an isolated filesystem that you can throw away.

Typical workflow:

Use whatever Docker setup fits your project — Docker Compose, a devcontainer, or a CI image such as composer:2 with Node in the same job. The goal is the same: never let untrusted install scripts run on bare metal; treat the host as a control plane only.

Checkpoint's CI scaffolds (GitLab CI) already run the scan inside ephemeral containers. Mirror that pattern locally.

Safe-Chain (recommended)

Safe-Chain by Aikido is a free shell shim that blocks known-malicious npm packages before their install scripts run. Install it once, globally:

When you do run npm on the host (CI runners, one-off scripts), Safe-Chain blocks known-malicious packages before their install scripts run. Checkpoint's Supply Chain Tooling check verifies whether Safe-Chain (or an equivalent like Socket CLI) is on your PATH and emits a WARN if no protection is present.

Why Checkpoint doesn't install it for you: Safe-Chain works as a global shell shim, not a project dependency. A composer require should never invoke another ecosystem's package manager (and can't reliably do so on hosts without Node). Installing it explicitly keeps the install path auditable. Prefer Docker for day-to-day installs; keep Safe-Chain as a safety net where containers aren't practical.

Usage

Run all checks

Run only specific checks

Skip specific checks

JSON output (for CI/CD pipelines)

The command exits with code 1 if any check returns FAIL, making it suitable as a pipeline gate.

Configuration

Checkpoint works out of the box with sensible defaults. Publish the config file when you need to toggle individual checks or tune the freshness gate:

This creates config/checkpoint.php with two sections:

Enabling / disabling checks

Every default check is listed and enabled. Set any entry to false to exclude it from the scan:

Checks not listed in the map fall back to enabled. When you upgrade Checkpoint and new checks are added, you keep the protection without re-publishing the config — re-publish only when you want to see the full updated list.

Package Freshness tuning

• minimum_age_days — packages released more recently than this fail the scan. Default 3. Set to 0 to bypass the freshness gate entirely without removing the check from the scanner.
• whitelist — fully-qualified package names (vendor/package) exempt from the freshness check. Use sparingly and ideally with an inline comment explaining why each entry is allowed.

Checkpoint ships with andreapollastri/checkpoint already whitelisted by default — a fresh release of the scanner itself should never block its own user's deploy. Remove the entry if you want to gate even Checkpoint upgrades through the freshness window.

Suppressing individual findings

Every WARN or FAIL finding is shown with a stable 12-character hash:

To silence one — false positive, accepted legacy code, internal test fixture — copy the bracketed hash into config/checkpoint.php:

On the next run those findings are filtered out. If every finding of a given check ends up suppressed, the check is downgraded to PASS with an explicit "All N finding(s) suppressed via config." message — so the suppression is visible in the output, not silently ignored.

The hash is content-stable: refactors that only shift line numbers within the same file will not invalidate the suppression. The hash does change if you alter the file path or the finding content itself, which is the intended safety net.

The --only / --skip CLI flags still work and override the config for the current run, which is handy for ad-hoc scans without editing the config.

Example output

Extending with custom checks

Create a class that extends AbstractCheck and return a CheckResult:

Then register it by building a Scanner manually instead of using the default:

CI/CD integration

Checkpoint can scaffold a ready-to-use pipeline for either provider in one command.

GitHub Actions

Creates .github/workflows/checkpoint.yml — triggers on push to main/master and on every pull request. Uses actions/checkout@v4, shivammathur/setup-php@v2 (PHP 8.2), Composer cache, and runs php artisan checkpoint:scan. Pass --force to overwrite an existing file.

GitLab CI

Creates .gitlab-ci.yml — runs on merge requests and default-branch pushes using the composer:2 image with a Composer cache. If you already have a .gitlab-ci.yml, the command refuses to overwrite and prints the snippet to stdout so you can paste it into your existing pipeline. Use --force to overwrite.

Custom usage

If you prefer to wire Checkpoint into a pipeline you already maintain, just call:

Composer hooks

Run Checkpoint automatically after every composer install / composer update:

This appends @php artisan checkpoint:scan to scripts.post-update-cmd and scripts.post-install-cmd in your composer.json. The command:

• Confirms interactively before touching composer.json (skip the prompt with --no-interaction for CI).
• Is idempotent: re-running on an already-installed setup is a no-op.
• Preserves any existing hooks (append-only); does not overwrite scripts owned by other tools.
• Supports --remove to cleanly uninstall and --force to replace stale Checkpoint entries.

Why only post-*, not pre-*? Composer's pre-update-cmd fires before dependencies are resolved, so the scanner would only see the codebase pre-update — useless against a malicious package that's about to be installed. And on a fresh clone there is no vendor/, so php artisan does not exist yet and pre-install-cmd would crash. Real-time interception of malicious installs is the job of Safe-Chain on the host.

Exit codes

Architecture

License

MIT — Andrea Pollastri