mrpunyapal/laravel-auditor/laravel-auditor-development

Laravel Auditor Development

Use this skill when a Laravel application needs to install, configure, or apply the Laravel Auditor package. Auditor does not scan the app. After setup, the user asks their AI agent to use the laravel-audit skill.

Primary goals

• Install Laravel Auditor as a development dependency.
• Run the appropriate setup command (Boost-based or standalone).
• Verify setup with the diagnostics command.
• Use the audit workflow skill to perform an audit.

Workflow

1. Install the package

composer require --dev mrpunyapal/laravel-auditor

2. Set up resources

When Laravel Boost is installed, expose Auditor resources through Boost:

php artisan boost:install

(or php artisan boost:update after package updates).

When Boost is not installed, use the standalone installer:

php artisan auditor:install --agents=claude_code
php artisan auditor:install --agents=claude_code,opencode

The installer is idempotent and safe. It detects the Laravel application context, detects whether Boost is installed, prepares Auditor's agent-facing resources, and reports what it created or updated.

Non-interactive runs resolve agents from --agents, then laravel-auditor.agents, then project markers. When none of those resolve, no agents are wired. A .github directory alone is not treated as Copilot. Unknown --agents values warn and are skipped. To wire an agent that is not in the built-in list, add it under laravel-auditor.custom_agents. Pass --force to refresh Auditor-owned resources, including an existing laravel-auditor MCP entry.

3. Verify setup

php artisan auditor:status

4. Inspect the available rules and project facts

php artisan auditor:rules
php artisan auditor:context --list
php artisan auditor:context project_info

5. Run an audit

Ask the agent to use the laravel-audit skill to perform a structured, evidence-based audit of the application.

6. Render a report

If the agent produced a JSON findings file:

php artisan auditor:report --example
php artisan auditor:report --findings=storage/auditor-findings.json --format=markdown

Supported formats: markdown, json, text, sarif. Finding schema: publish tag laravel-auditor-schema.

7. Optional MCP

php artisan auditor:mcp -q

Register that stdio command with the agent so it can call project_info, routes, models, migrations, database_schema, dependencies, configuration, policies_authorization, jobs_events_schedules, tests, subsystems, changed_files, and review_scope. Use -q so Artisan boot output cannot break MCP stdio framing.

With Laravel Boost installed, the same context tools are registered automatically inside Boost's MCP server (via boost.mcp.tools.include); no extra setup is needed.

References

• Install: composer require --dev mrpunyapal/laravel-auditor
• Boost path: php artisan boost:install / php artisan boost:update
• Standalone path: php artisan auditor:install (--dry-run, --force, --agents=)
• Diagnostics: php artisan auditor:status
• Rules: php artisan auditor:rules (--domain=, --json, --applicable)
• Context: php artisan auditor:context (--list, {collector}, --output=)
• Reports: php artisan auditor:report (--findings=, --example, --format=markdown|json|text|sarif, --output=, --base=origin/main, --dirty)
• CI: php artisan auditor:ci --findings=storage/auditor-findings.json --base=origin/main --fail-on=high (--base gates the committed diff; --dirty gates only uncommitted work and matches nothing on a clean checkout)
• Facade: LaravelAuditor::collect('routes'), LaravelAuditor::rules(), LaravelAuditor::context(), LaravelAuditor::project()
• Config: resources_target, agents, custom_agents, context.composer_audit (on), context.test_listing (off), changed_files.include_untracked, changed_files.ignore, changed_files.max_files
• Config publish tag: laravel-auditor-config
• Resource publish tag: laravel-auditor-resources
• Schema publish tag: laravel-auditor-schema
• Example publish tag: laravel-auditor-examples
• Audit workflow skill: laravel-audit (laravel-audit-dsa for subsystem / P0–P3 ranking)

Examples

Ask the agent:

Use the laravel-audit skill. Call review_scope first and audit the dirty files plus the views, tests, and classes they directly use. Report only findings with file, route, or schema evidence.

A finding should include rule_id, severity, confidence, summary, why_it_matters, evidence, and recommendation.

Default audit prompt:

You are auditing the Laravel application in this project using the Laravel Auditor methodology.

1. Use the laravel-audit skill. Follow its Discover → Scope → Verify → Report workflow.

2. Call review_scope first. When scope is non-empty, audit those files only: the dirty files and the views, tests, and classes they directly use. Do not pull the full route, model, or schema inventory.

3. When changed is empty, say the working tree is clean. Audit the whole application only if the user asked for that.

4. Scope the relevant domains (security, database, architecture, testing, ...). Pick the domains with the most risk signal and go deep.

5. For every potential finding, verify against actual files, routes, or schema. Never report a guess.

6. Report findings ranked P0–P3, each with: file/route/schema evidence, the rule violated, why it matters, and a concrete fix.

7. Be read-only. Do not modify any application code.

Whole-application prompt:

Audit the whole application, including files outside the dirty scope. Use the laravel-audit skill, gather the context tools, and report only evidenced findings.

Discover-only quick pass:

Start with a Discover phase only: run all 13 context tools, summarize what this app is (framework versions, database, route surface, model list, test coverage), and flag any immediate red flags in 3-5 bullets. Do not write findings yet.

Anti-patterns

• Do not require Boost just to use Auditor.
• Do not run php artisan auditor:install when Boost is installed unless a standalone path is explicitly wanted.
• Do not modify application code during setup or during an audit.
• Do not treat Auditor as an autonomous scanner that invents findings without evidence.