Warden

A deterministic security gate for Laravel CI and deployment pipelines.

Introduction

Warden audits locked production dependencies, supply-chain configuration, and high-confidence Laravel production settings without becoming part of the deployed application.

Requirements

• PHP 8.3–8.5
• Laravel 12 or 13
• Composer 2
• npm only when a package-lock.json is present

Installation

Install Warden as a development dependency:

Laravel discovers Warden automatically. If package discovery is disabled, register Dgtlss\Warden\Providers\WardenServiceProvider::class in your application's providers array.

Usage

Run Warden before pruning development dependencies from the production artifact:

Initialize Warden safely and optionally generate a dedicated CI file:

warden:init never overwrites an existing config/warden.php or root GitLab pipeline. --force may replace only Warden-owned generated CI files. Publishing with vendor:publish --tag=warden-config remains available for manual setups.

CI usage

The default command uses the CI profile, audits production dependencies, reports every finding, and fails on low severity or higher:

Common examples:

Machine formats never mix progress or diagnostic prose into stdout. Scanner failures are included in the report and exit with code 2.

Exit codes

Profiles

CI environment variables do not disable production checks. Use --profile=production when the pipeline has loaded the intended deployment configuration.

Built-in audits

• supply-chain: lockfile presence/synchronization, secure Composer repositories, plugin allow-listing, and JavaScript lockfile support
• composer: Composer advisories, malware, and abandoned production packages from composer.lock
• npm: npm advisories from package-lock.json or npm-shrinkwrap.json, auto-detected without a flag; shrinkwrap takes precedence when both exist and report locations identify the selected lockfile
• laravel-config: tracked .env detection and production application/session/tooling rules
• platform: offline PHP and Laravel support-window enforcement, including Composer's exact platform target
• source: parser-backed PHP taint analysis, Blade review, and redacted credential detection
• storage: production-only operational warnings; these do not fail the security gate

Deployment checks use Laravel's configured storage, bootstrap, and environment file paths, including custom environment filenames. Findings show paths relative to the application root when possible and absolute paths for external locations. The Git tracking check inspects the configured environment file only when it is inside the application repository.

Yarn, pnpm, and Bun lockfiles are detected but are not yet parsed. Warden reports the limitation so the package-manager-native audit can be added as a separate CI step.

Source security model

Warden parses each selected PHP file once and distinguishes enforcement from review guidance:

• Blocking rules require a high-confidence condition such as request-controlled data reaching a command, raw output, outbound URL, redirect, deserializer, or filesystem sink. Other blocking rules cover interpolated raw SQL, disabled TLS verification, provider-format credentials, weak constant ciphers, and explicit CSRF middleware removal.
• Advisory rules highlight unescaped Blade output, forms without an obvious CSRF directive, mass-assignment disabling, debug calls, sensitive logging, weak contextual hashing/randomness, and secret-like literals.

Credentials are never copied into reports. Warden emits only the provider, location, and a redacted description; the secret contributes only a one-way hash to the stable fingerprint.

Default PHP scan paths are app, bootstrap, config, and routes; Blade templates are read from resources/views. File paths, exclusions, and the 1 MiB file limit are configurable under warden.audits.source. A selected file that cannot be read or parsed makes the scan incomplete and exits 2. Credential discovery includes dotfiles matching the supported extensions, .env.example, and .github files. Configured exclusions and VCS-directory exclusions still apply; .env contents are never scanned. Every provider credential and distinct secret-like literal on a line is examined.

Unreadable directories also make the scan incomplete. Console and explicitly selected json-v2.1 audit records expose coverage.scanned, coverage.skipped, and coverage.errors: scanned counts unique files for which all selected analysis passes ran (including parse attempts); skipped counts known eligible files rejected by size/readability or left unfinished at timeout. Excluded/unsupported files are outside this count. An unreadable directory can hide an unknown number of files, so incomplete-run counts are lower bounds, never a claim of full coverage.

Sanitization is sink-specific: HTML escaping only clears HTML-output taint; escapeshellarg only clears shell-argument taint. escapeshellcmd, basename, and realpath do not establish validation boundaries. Imported class aliases, typed Laravel Request parameters, and named arguments are recognized for existing rules. Name resolution preserves fingerprints for unchanged source, so existing fingerprint suppressions and baselines keep matching. Relative source paths such as ./app and app/. select the same files as app. Analysis remains local and heuristic, not interprocedural or a proof that application input is safe.

Rule policy

Every configurable rule has a stable ID and a built-in disposition. Override one without suppressing individual occurrences:

Allowed values are enforced, advisory, and off. Unknown rule IDs and invalid values are configuration errors. Advisory findings remain visible in every report but do not affect exit 1; suppressions and baselines still apply to them.

See the complete rule catalogue for stable IDs, default dispositions, and rationale.

Supply-chain review window

Composer packages released within three days produce an advisory. A recent package becomes a blocking critical finding when it is a Composer plugin or registers autoload.files, because it can execute automatically. The window is offline, uses composer.lock timestamps, respects --scope, and is configurable with warden.audits.supply_chain.minimum_release_age_days.

Reviewed suppressions

Suppressions are exact, documented, and expiring. Wildcards are not supported.

An expired or malformed suppression is a configuration error and exits 2 before scanning. A supplied fingerprint must be a 64-character lowercase SHA-256 hash; null, false, arrays, numbers, empty strings, and malformed hashes are rejected rather than becoming rule-wide suppressions. Expiry must be an actual calendar date in YYYY-MM-DD format; it remains valid through the end of that day. Baselines always require a fingerprint.

Baselines

Legacy applications can commit an explicit fingerprint baseline while continuing to fail on new findings:

This creates warden-baseline.json. Baseline generation refuses to write a file if any audit is incomplete.

Reports

Warden supports:

• console: readable terminal report
• json: the unchanged 2.1-release JSON contract, with audits, blocking/advisory counts, findings, ignored findings, errors, and summary; validates against resources/schemas/warden-report-2.0.0.json
• json-v2.1: explicitly selected extended JSON with gate and per-audit coverage fields; validates against resources/schemas/warden-report-2.1.0.json
• github: GitHub Actions workflow annotations
• gitlab: GitLab dependency scanning report schema 15.2.4
• sarif: SARIF 2.1.0 for GitHub code scanning and compatible platforms
• junit: portable JUnit XML for Jenkins and other CI systems

Advisory findings render as notices in GitHub and skipped tests in JUnit. Blocking findings below --fail-on (including all findings with never) are also non-gating in these outputs. JUnit errors still represent incomplete scans. json-v2.1 adds gate.fail_on, gate.exit_code, and audits[].coverage (null when unavailable); SARIF adds runs[].properties.wardenGate while preserving finding severity and disposition. Default json, new JsonReporter(), and direct json_encode($report) / json_encode($auditResult) preserve schema 2.0.0 without gate or coverage fields. Use new JsonReporter(extended: true) for schema 2.1.0. Schema versions are independent of the package version. Programmatic reporters default to low; call $report->withGate('high') to choose another threshold.

--output-file=- writes to stdout. Relative file paths are resolved from the Laravel application root. Equivalent destinations (including dot segments, symlinks, and existing hard links) are rejected with exit 2 before scanning or writing any report; the error goes to stderr. Repeat --report=format:path to emit additional files from one scan, with the same timestamp, suppressions, and gate:

Generated GitHub and GitLab configurations explicitly select json-v2.1 for warden.json. The GitHub summary reports an unavailable gate for legacy JSON instead of guessing an exit code. Generated GitHub workflows retain reports for 14 days, emit annotations, and write a concise job summary even after gate failure. SARIF upload is opt-in: after confirming code-scanning availability and policy, set repository variable WARDEN_CODE_SCANNING=true and add security-events: write to the generated job's permissions. Upload failure is non-gating; annotations and artifacts remain available. Fork PRs skip upload. Warden initialization does not change repository permissions, settings, or secrets.

Generated GitLab includes use the built-in .pre stage without replacing an existing stages list. Newly created root pipelines override Warden to the regular test stage so standalone pipelines run. Existing root pipelines remain untouched and must include .gitlab/warden.yml; a pipeline containing only .pre/.post jobs also needs a regular-stage job. The Composer Alpine image installs Node/npm only when an npm lockfile exists. JUnit, SARIF, JSON and the GitLab report are retained even on gate failure.

Notifications

Notifications are opt-in and never affect the audit exit code:

To skip messages for completed scans when no active findings remain, use --notify-on-finding instead of --notify (or combine both flags):

To apply this filter to every --notify run, set warden.notifications.only_on_findings to true or WARDEN_NOTIFY_ONLY_ON_FINDINGS=true. The setting defaults to false and does not enable notifications by itself. The flag and configured filter combine with OR: --notify cannot override a finding-only preference, and suppressed findings do not count as active findings.

warden.notifications.on_errors controls incomplete reports. Missing or null (the default) respects existing finding-only preferences. Only the boolean true explicitly opts into additional error-only alerts; boolean false silences all incomplete reports, including those containing active findings. Existing published 2.1 configs need no new key and do not gain additional alerts.

Delivery requires --notify or --notify-on-finding and a configured channel in every case:

Reports containing only ignored findings use the no-active-findings rows. To opt into error-only alerts, deliberately add 'on_errors' => true to the notifications array of your published config. This does not enable notification delivery on its own.

Every delivered incomplete report explicitly describes the failure and never claims all-clear. Completed emails retain the existing warden::mail.enhanced-report view, including application overrides, recipients, and sender settings. Incomplete emails use explicit plain text because legacy findings-only templates cannot safely represent scan errors; suppress these with on_errors=false if that format is unsuitable. Built-in dispatch uses ReportNotificationChannel::sendReport; the legacy NotificationChannel::send(array) API remains available. Teams report payloads are limited to 28,000 encoded JSON bytes; long reports retain status and counts and mark truncation. Delivery filtering does not change reports or exit codes, including exit 2 for incomplete audits.

Configure any combination of:

Each channel is dispatched once. Delivery failures are written to stderr after the report is produced.

Custom audits

Custom audits receive the immutable audit context and return a typed result:

Register the class in config/warden.php under custom_audits.

Testing

Changelog

Please see the releases page for a list of changes.

Contributing

Please see UPGRADE.md before changing the dependency constraint.

Security Vulnerabilities

Please report security vulnerabilities privately using GitHub Security Advisories.

License

Warden is open-sourced software licensed under the MIT license.