diddyy / plumbline
A precision-first static security scanner for Laravel applications. The scanner that doesn't cry wolf.
Requires
- php: ^8.3
- nikic/php-parser: ^5.0
- symfony/console: ^7.0
- symfony/finder: ^7.0
Requires (Dev)
- justinrainbow/json-schema: ^6.14
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A precision-first security scanner for Laravel. The scanner that doesn't cry wolf.
Measured on 8 popular open-source Laravel apps (BookStack, Pixelfed, Firefly III, Monica, koel...): zero Critical/High false positives. See BENCHMARK.md.
Most static scanners match patterns: they flag every DB::raw() and every {!! !!}, and teams
learn to ignore them. Plumbline reads your code the way Laravel runs it, and only speaks up
when it can explain why something is exploitable:
app/Http/Controllers/SearchController.php
CRITICAL SQLI-001 line 22
User input from $request->query('sort') reaches raw SQL in orderByRaw(). Pass it as a
binding instead, e.g. ->whereRaw('lower(name) = ?', [$name]).
│ return Post::query()->orderByRaw($column.' desc')->get();
app/Http/Controllers/PostController.php
HIGH AUTHZ-001 line 18
DELETE /posts/{post} (PostController@destroy) deletes the Post chosen in the URL ($post)
without an authorization check, so any signed-in user can do this to any Post.
Add $this->authorize('delete', $post) or ->can('delete,post') on the route.
│ $post->delete();
What makes it different
- It knows Laravel. It rebuilds your routes statically from
bootstrap/app.php,RouteServiceProvider, groups, prefixes, resources,required route files and controller middleware. It knows which routes need a login and which check authorization. It reads FormRequestrules()andauthorize(), model$fillable/$guarded, global scopes, and Livewire public properties and#[Locked]. - It tracks real data flow. A real PHP AST (nikic/php-parser), with taint tracked through
assignments, string building,
sprintf, loops and closures. Casts,$request->integer(), validation rules (integer,in:,Rule::in,uuid...),in_arrayallowlists andmatchall clear taint. - It stays quiet when unsure. Unknown functions are treated as clean. Custom route middleware might be an access check, so access rules skip those routes. That trade-off is deliberate.
- Precision is tested. Every rule ships with a vulnerable fixture (every marked line must be
reported, and nothing else) and a safe fixture (zero findings). The official
laravel/laravelskeleton andreact-starter-kitmust come back with zero findings.
Install
composer require --dev diddyy/plumbline
php artisan plumbline:scan # or: vendor/bin/plumbline scan
Tested with Laravel 11–13 (Symfony Console 7 and 8) on PHP 8.3–8.5. Laravel 10 (Symfony 6.4) is allowed by the constraints but not yet tested. The artisan commands register through package auto-discovery.
It never boots your app or runs your code, so it's safe to point at anything.
Rules
| ID | Finds | Severity |
|---|---|---|
| SQLI-001 | User input in raw SQL (DB::select, *Raw(), DB::raw) |
Critical |
| CMD-001 | User input in shell commands | Critical |
| DESER-001 | unserialize() on user input |
High |
| MASS-001 | $request->all() written to an unguarded model, a builder update(), or one with is_admin/role in $fillable |
High |
| AUTHZ-001 | Signed-in route updates or deletes a URL-chosen model with no authorization check (IDOR) | High |
| AUTHZ-002 | Livewire action updates or deletes a record chosen by the browser ($wire.delete(42)) with no authorization check (experimental) |
High |
| AUTH-001 | Route with no auth middleware that changes existing records | High |
| XSS-001 | {!! !!} with request data (High), unsafe Markdown (Medium), other raw output (Low) |
High–Low |
| REDIR-001 | Redirects to user-supplied URLs | Medium |
| UPLOAD-001 | Uploads stored under the client's file name and extension | Medium/High |
| CSRF-001 | CSRF disabled for paths that aren't webhooks | High–Low |
| CFG-001 | APP_DEBUG=true for production |
High |
| CRYPTO-001 | Fast hashes on passwords, rand() tokens, timing-unsafe token comparison |
High–Low |
Usage
vendor/bin/plumbline scan [path] --format=console|json|sarif|github --output=report.sarif --min-severity=medium # hide lower-severity findings --fail-on=high # exit 1 only for high/critical (default: any finding) --rules=SQLI-001,AUTHZ-001 # run only these --skip-rules=XSS-001 --exclude=legacy # extra directories to skip --baseline=plumbline-baseline.json --generate-baseline=plumbline-baseline.json vendor/bin/plumbline rules # list rules
Adopting it on an existing app
Record what's there today, then fail CI only on new findings:
vendor/bin/plumbline scan --generate-baseline=plumbline-baseline.json vendor/bin/plumbline scan --baseline=plumbline-baseline.json
Baseline entries match on rule + file + source line, not line number, so unrelated edits don't bring old findings back.
Suppressing a finding
Put a comment on the line or the line above. A reason is required:
// plumbline-ignore SQLI-001: $column is checked against the schema in ColumnGuard return Post::orderByRaw($column)->get();
{{-- plumbline-ignore XSS-001: body is purified on save --}} {!! $post->body !!}
GitHub code scanning
name: Security on: [push, pull_request] permissions: contents: read security-events: write jobs: plumbline: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: shivammathur/setup-php@v2 with: { php-version: '8.3' } - uses: Diddyy/Plumbline@v0 with: fail-on: high
Findings appear in the repository's Security → Code scanning tab and as annotations on pull requests.
Limits (honest ones)
- Taint tracking stays within one function. A value passed into a helper method and used there is not followed yet.
- AUTHZ-001 can't know whether every signed-in user is meant to be an admin. Suppress it, or use a baseline, if that's your app.
- Plumbline doesn't replace a dependency audit. Run
composer auditas well.
Contributing
False-positive reports are the most valuable contribution. See CONTRIBUTING.md: adding a rule means writing the rule, its fixtures, and its docs.
License
MIT