Download the PHP package intentphp/guard without Composer

IntentPHP Guard

A Laravel CLI tool that scans your application for common security risks: authorization gaps, unsafe query input, and mass assignment vulnerabilities.

Why Guard?

Most static analysis tools answer:
“Is this code valid?”

Guard answers a different question:
“Does this code match the security and data-handling intent of this project?”

Guard introduces an optional intent specification (intent/intent.yaml) where you declare expected security and data rules — for example:

• which routes must be authenticated
• which guards must be used
• which models must use explicit $fillable
• which attributes must never be mass-assignable

Guard then scans your code and reports mismatches between:

declared intent vs actual implementation

This makes Guard especially useful in CI pipelines, security-sensitive Laravel applications, and multi-developer teams where architectural and security rules must stay enforced over time.

Guard is:

• ✅ additive — no breaking changes without intent spec
• ✅ deterministic — stable fingerprints and reproducible results
• ✅ CI-safe — predictable exit codes and output
• ✅ non-invasive — never modifies your code

Comparison With Other Tools

Quick Start

Add the last command to CI — Guard will now fail builds only on new security risks.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12, or 13

Installation

Install Guard as a dev dependency:

The service provider is auto-discovered. Optionally publish the config:

Commands

guard:scan — Scan for security issues

Exit codes:

• 0 — No active HIGH severity findings
• 1 — Active HIGH severity findings exist
• 2 — Baseline file missing (with --strict)

guard:baseline — Save current findings as baseline

Saves a fingerprint snapshot to storage/guard/baseline.json. Future scans with --baseline will suppress any findings that match the saved fingerprints.

This is the recommended workflow for adopting Guard on an existing codebase:

1. Run php artisan guard:baseline to snapshot current state
2. Add php artisan guard:scan --baseline --strict to CI
3. CI will now only fail on new findings, not existing ones
4. Fix existing findings at your own pace

guard:fix — Generate safe patch proposals

Generates .diff files in storage/guard/patches/ for each HIGH severity finding. With --ai, falls back to AI-generated patches when templates cannot produce a diff. AI patches are marked with a header comment. When AI returns guidance that cannot be structured as a diff, a .md note file is written instead.

Warning: Always review patches before applying. Guard never guarantees semantic correctness of generated diffs.

Patches are never applied automatically — review and apply manually:

Exit codes:

• 0 — No patches generated (clean scan)
• 1 — Patches were generated (findings exist)

guard:apply — Validate and apply a patch

Checks if a patch applies cleanly using git apply --check and shows the command to apply it. Never applies patches automatically.

guard:testgen — Generate security tests

Generates PHPUnit tests in tests/Feature/GuardGenerated/:

• RouteAuthorizationTest.php — guest access assertions
• DangerousInputValidationTest.php — malicious input regression tests
• MassAssignmentProtectionTest.php — model protection assertions

guard:intent — Manage the intent spec

Manages the optional intent/intent.yaml spec file. init generates a starter file with example auth rules and model declarations. validate checks the spec for parse and schema errors. show prints a summary of the parsed spec. map builds a mapping index between spec rules and code targets (routes, models). If the intent spec is missing, map produces an observed-only index containing routes only (no models). The intent spec is optional — Guard works without it.

guard:doctor — Environment diagnostics

Runs a series of environment checks and prints a diagnostic report with actionable guidance. Useful for verifying your setup after installation or troubleshooting issues.

Checks performed:

Exit codes:

Example output:

Checks

1. Route Authorization Coverage

Detects routes missing auth middleware or authorization calls. Checks route-level and group-level middleware, $this->authorize(), Gate:: calls, authorizeResource() in constructors, and FormRequest type hints. Enriched with Project Map context (model, policy, ability).

2. Dangerous Request Input in Queries

AST-based detection of request input flowing into query builder sinks. Catches whereRaw, orderByRaw, havingRaw, groupByRaw, selectRaw, fromRaw, the column position of orderBy / where / whereColumn, and the DB facade family (raw, statement, select, selectOne, insert, update, delete, unprepared).

Coverage extends beyond the literal ->whereRaw($request->...) form. The check sees:

• multi-line calls (formatting-independent);
• string interpolation and concatenation embedding request input: whereRaw("id = {$request->input('id')}"), '..' . $request->q;
• one-hop variable indirection (monotonic per-function taint): $dir = $request->input('dir'); …->orderByRaw("name $dir");
• request access through a FormRequest-typed parameter (any class under *\Http\Requests\*).

->where('col', $request->x) is recognised as a safe parameterized binding and is not flagged. ->orderBy($sort) based purely on a sort-like variable name is reported as MEDIUM (since the value may be validated) — it never gates CI.

3. Mass Assignment Risk

Detects bulk request input flowing into mass-assignment sinks: Model::create(...) and ->update(...) / ->fill(...). Bulk input is $request->all(), argless $request->input(), $request->except(), or $request->validated() (the last is MEDIUM). One-hop variable indirection ($d = $request->all(); $m->fill($d);) is caught via the same per-function taint analysis as check #2.

A model is treated as mass-assignable when:

• $guarded = [] (everything open), or
• $guarded is set to a non-['*'] partial allowlist and there is no $fillable.

A bare Eloquent model (no $fillable and no $guarded) inherits the framework default $guarded = ['*'] and is not flagged. Likewise, an explicit $guarded = ['*'] or any $fillable allowlist is treated as safe.

4. Intent Auth (intent-auth)

Compares actual route middleware against requirements declared in the intent spec. Detects routes that should be authenticated, require a specific guard, or are declared public but lack auth middleware. Only active when intent/intent.yaml is present and contains auth.rules.

5. Intent Mass Assignment (intent-mass-assignment)

Checks model files against mass-assignment constraints declared in the intent spec. Detects models missing $fillable when declared as explicit_allowlist, forbidden attributes present in $fillable, and empty $guarded when declared as guarded mode. Only active when intent/intent.yaml is present and contains data.models.

Intent checks are additive. A route can receive both a route-authorization finding and an intent-auth finding. They serve different purposes (config-driven vs spec-driven) and are independently suppressible via baseline or inline ignores.

6. Intent Drift (intent-drift/auth, intent-drift/mass-assignment)

Detects divergence between declared intent and observed project state. Auth drift detects missing auth middleware, missing guard middleware, and public routes with unnecessary auth middleware. Mass-assignment drift detects missing $fillable, forbidden attributes in $fillable, empty $guarded, and unparseable model patterns. Drift findings have stable fingerprints and integrate with baseline suppression. Only active when intent/intent.yaml is present.

7. Spec↔Code Mapping (guard:intent map)

Builds a versioned mapping index (v1.0) linking spec rules to code targets (routes and models). Each entry is classified as spec_linked (matched by an intent rule) or observed_only (no spec coverage). The mapping is used internally by the drift engine for context enrichment and can be dumped as deterministic JSON via guard:intent map --dump. If the intent spec is missing, the mapping contains routes only (no models).

Intent Spec (optional)

Guard supports an optional intent/intent.yaml file at the project root. This file declares expected security properties (auth rules, model constraints) that Guard validates against your actual code.

• If the file is missing, Guard behaves exactly as before. No configuration needed.
• If the file is present and valid, additional intent-auth and intent-mass-assignment checks run alongside existing checks.
• If the file has parse errors or validation failures, Guard prints the errors and exits non-zero.
• This is fully additive. No existing behavior changes.

Setup

Minimal example

Warnings

If the intent spec references a model whose file cannot be found on disk, Guard prints a warning and continues. Warnings do not produce findings and do not cause the scan to fail. The scan only fails if the spec itself is structurally invalid.

Inline Suppressions

Suppress individual findings by adding a comment on the same line or the line above:

Suppressed findings are tracked and shown in the summary. Disable inline ignores in config:

Configuration

Incremental Scanning

Guard can scan only files that changed in your working tree, dramatically speeding up scans in large projects and CI pipelines.

Modes

Base branch auto-detection tries: origin/main → origin/master → main → master → HEAD~1. If your default branch is master, use --base=origin/master to skip auto-detection.

Route authorization check runs in one of three modes:

• full — when route files changed or no incremental mode is active
• filtered — when only controller files changed (only related routes are checked)
• skipped — when neither routes nor controllers changed

File-based checks (dangerous query input, mass assignment) are filtered to only the changed files.

Pre-commit hook example

CI with incremental scan

Caching

Guard caches expensive computations (Project Map, reflection results) to speed up repeated scans. The cache is stored in storage/guard/cache/ and invalidated automatically when:

• The git HEAD SHA changes (new commits), when available
• The PHP or Laravel version changes
• Relevant file modification times change (routes, controllers, policies, kernel, auth provider) — used as fallback when git SHA is unavailable

Configuration

Caching is enabled by default. To disable:

Clearing the cache

The cache is safe to delete at any time — Guard will rebuild it on the next scan.

You can bypass the cache for a single run with --no-cache:

Performance Notes

• Full scan: analyzes routes + controllers + models (every PHP file in scope)
• Incremental scan: analyzes only changed files, with route check filtering based on what changed
• With caching enabled, repeated scans are typically 3-10x faster (Project Map and reflection results are cached)

Report Output

Saving reports to file

Use --output with --format=json or --format=md to save the report to a file:

The --output option is supported for json and md formats. Console format (--format=console) does not support file output. When --output is set, Guard writes the report to the file and prints a short confirmation line to the console.

AI Setup (Local CLI)

Guard uses locally installed AI CLI tools (e.g. claude, codex) to generate fix suggestions. No API keys needed for local usage.

Quick start (macOS / Linux):

Quick start (Windows PowerShell):

The auto driver tries in order: local CLI tool in PATH, then OpenAI API (if key set), then falls back gracefully to no AI (scan still works, just without suggestions).

Explicit CLI configuration:

Using a different CLI tool:

Using any custom CLI:

JSON output mode — If your CLI supports structured JSON output with suggestion and patch keys, enable it for richer results:

AI Setup (OpenAI API)

For CI pipelines or environments without a local CLI tool, use the OpenAI HTTP driver:

Compatible with any OpenAI-compatible API — Azure OpenAI, Ollama, LM Studio, local vLLM, etc.:

The client retries once on 429 (rate limit) and 5xx errors. API key is never logged.

AI Driver Priority (auto)

When using GUARD_AI_DRIVER=auto, Guard selects the best available driver:

1. CLI — local claude/codex binary in PATH (free, no API cost)
2. OpenAI — API key set in GUARD_AI_API_KEY
3. Null — no AI, scan works normally without suggestions

This means auto works everywhere: locally with a CLI tool, in CI with an API key, or gracefully without either.

Troubleshooting AI

Security Note

The prompt sent to the AI includes only the finding context: check name, severity, message, file path, line number, and a short code snippet. Guard never sends your entire codebase or any secrets to the AI. All AI output is treated as suggestions — Guard never applies changes automatically.

Non-Goals

Guard does not:

• Apply patches automatically — all fixes require manual review and git apply
• Upload your repository or source code to any external service
• Replace full security audits, penetration testing, or dedicated SAST/DAST tools

Guard is a lightweight first line of defense that catches common Laravel security patterns early in the development cycle.

Recommended CI Setup

For most teams, this is the golden path:

1. Commit a baseline once:

2. In CI, use:

This gives you:

• Fast incremental scans (only changed files)
• No legacy noise (baseline suppresses known findings)
• PR annotations only for new issues

CI Integration (GitHub Actions)

Basic scan

With baseline (recommended for existing projects)

Commit storage/guard/baseline.json to your repository. The scan will only fail on new findings.

Incremental scan on PRs (fastest)

Note: fetch-depth: 0 is required so Guard can compare against the base branch.

Markdown report as PR comment

License

MIT