Download the PHP package jayanta/laravel-ai-guard without Composer

Laravel AI Guard

Protect your Laravel app from AI scrapers, spoofed crawlers, and prompt injection — and guard the LLM features you build yourself: budgets, moderation, PII redaction, a tool-call firewall, MCP pinning, safe rendering, red-teaming, and an audit trail.

Upgrading from v2? Read UPGRADE.md — AI bots are now split by purpose, and prompt-injection scores are weighted.

What It Does

Inbound traffic — a middleware with a multi-layer detection pipeline:

• 353 bot signatures in 8 categories, with AI bots split by purpose — training crawlers, AI search crawlers, and user-triggered AI agents — each with its own policy; extend them from the community ai.robots.txt list
• Bot verification — prove a crawler is who it claims to be with Web Bot Auth signatures (RFC 9421), published IP ranges, and forward-confirmed reverse DNS; impersonators are logged as spoofed_bot
• 76 weighted prompt-injection patterns with de-obfuscation (zero-width characters, fullwidth letters, homoglyphs, leetspeak, letter-spacing, Unicode tag and emoji smuggling, base64 / URL / HTML-entity payloads), many-shot and Policy Puppetry detection, chat-template tokens, and instruction overrides in 12 non-English languages
• Optional ML detection — Lakera, Llama Prompt Guard 2 (HuggingFace), Pangea, Ollama, or your own endpoint, for borderline cases or on every input of your chat endpoints
• Edge and network fingerprints — JA4 TLS fingerprints and bot scores from Cloudflare or CloudFront, datacenter IP scoring, and header analysis to catch bots faking a browser
• AI agent policy — decide per route whether user-triggered AI agents may use a page (ai-guard.agents)
• Honeypot trap routes, response scanning for leaked secrets and hidden prompt injection, robots.txt enforcement and generation, and AI usage preference headers

Your own LLM features — helpers and middleware for chatbots, agents, RAG, and MCP:

• LLM route guard (ai-guard.llm) — token and cost budgets, harm moderation, topic policy, and multi-turn escalation scoring
• PII redaction that restores safe values in the reply, and spotlighting of untrusted content
• Output scanning for exfiltration and system-prompt leaks, canary tokens, and safe HTML rendering with a CSP nonce
• Tool-call firewall — roles, argument schemas, egress allow-lists, taint tracking, and human approval for risky calls
• MCP — a firewall for MCP servers you serve, and server allow-listing plus tool-definition pinning (rug-pull detection) for servers you use
• laravel/ai integration — agent middleware and guarded tools
• Model-written SQL gate, a red-team command with CI thresholds, and a tamper-evident audit trail with SIEM and OpenTelemetry export

All detections are logged to your database with a built-in dashboard, 10 REST API endpoints, Artisan commands, a ThreatDetected event, and Slack alerts. Bot identity is also published as dependency-free events that other code can listen to.

Requirements

• PHP 8.1 or higher (Laravel 11 and 12 need PHP 8.2+, Laravel 13 needs PHP 8.3+)
• Laravel 10.x, 11.x, 12.x, or 13.x
• A database supported by Laravel (MySQL, PostgreSQL, SQLite)

No PHP extensions or external services are required. ext-intl (full Unicode folding), ext-sodium (native Ed25519), and ext-dom (HTML sanitizing) are used when present; fallbacks cover them otherwise. The laravel/ai integration needs laravel/ai (PHP 8.3+, Laravel 12+).

Installation

Publish and run migrations:

Publish the config file:

Quick Start

Register the middleware globally so every request is scanned.

Laravel 11 / 12 / 13 — bootstrap/app.php:

Laravel 10 — app/Http/Kernel.php:

That's it. AI Guard is now monitoring all incoming requests in log_only mode.

Protecting specific routes only

The package registers an ai-guard middleware alias, so you can guard individual routes or groups instead of every request:

Other aliases: ai-guard.llm (routes that call a model), ai-guard.agents (AI agent policy), ai-guard.mcp (MCP servers), ai-guard.csp (Content-Security-Policy), and ai-guard.preferences (AI usage preferences).

Recommended First Steps

1. Start in log_only mode (default) — detects and logs everything, blocks nothing
2. Open the dashboard at http://your-app.com/ai-guard — it requires login by default (Dashboard & API Authentication)
3. Whitelist your own tools — Postman, monitoring, office IPs (False Positives)
4. Decide your AI policy — which of training crawlers, AI search crawlers, and AI agents you want to block (see Bot Signatures)
5. Review detections for a few days before switching to block or rate_limit mode

Detection Pipeline

Every request passes through this pipeline:

Configuration

After publishing, the config file is at config/ai-guard.php.

Mode

Switching modes is a config change, no code. Budgets on ai-guard.llm routes and the ai-guard.agents rules are access controls, so they apply in every mode.

Confidence Threshold

Bot Signatures (353 signatures, 8 categories)

Blocking training crawlers costs you nothing in AI answers; blocking AI search crawlers and user-triggered agents removes your pages from them. Choose per purpose:

Signatures match on word boundaries, and the strongest match wins — appending "Googlebot" to an attack tool's user-agent does not hide it. The v2 category name ai_assistants is still accepted and means ai_search + ai_agents.

New AI crawlers appear every month. php artisan ai-guard:update-signatures adds the tokens from the community ai.robots.txt list (MIT) that the built-in database lacks, sorted by purpose. Nothing is fetched unless you run it — schedule it weekly if you like:

To flag extra AI crawler tokens of your own, list them in ai_crawlers.user_agents (they score 95):

Prompt Injection

Every pattern carries a weight. Strong signals ("ignore previous instructions", <|im_start|>, "reveal your system prompt") score 85–95 on their own; weak ones ("act as a", "you are now", "debug mode", the bare word "jailbreak") stay below min_score unless they appear together. Additional signals add up to 15 points, and a payload that only matched after de-obfuscation gets +10.

Bot Verification

• Web Bot Auth verifies HTTP Message Signatures (RFC 9421) against the agent's published key directory. Signed AI agents are identified even when they browse with an ordinary Chrome user-agent. Nonces are single-use; untrusted agents' key directories are never fetched, and allow_any_agent still refuses private and internal hosts.
• Published IP ranges — Google, Bing, OpenAI (GPTBot, OAI-SearchBot, ChatGPT-User), and Perplexity.
• Forward-confirmed reverse DNS — the PTR record must end in the operator's domain and resolve back to the same IP.

A request that claims a verifiable crawler but fails every check that could run is logged as spoofed_bot. If a range list is unreachable, the verdict is unverified, never spoofed. Verdicts are stored in the bot_verification column (verified, spoofed, unverified).

Honeypot Traps

28 paths real users never visit — /admin-backup, /wp-admin, /wp-login.php, /.env, /.git/config, /.aws/credentials, /phpinfo.php, /api/v1/users.json, /backup.sql, and more. Any request to one scores 100 confidence instantly.

Note: Honeypot paths are checked against the request path exactly. If your app has a real route at any of these paths, override trap_paths with your own array to avoid conflicts.

Response Scanning

Scans outgoing HTML, JSON, and text responses for leaked secrets and PII before they leave your server.

With scan_hidden_injection, pages are also checked for indirect prompt injection: instructions hidden from human readers but read by AI agents and AI browsers — HTML comments, hidden / aria-hidden / display:none / zero-size / off-screen elements, and invisible Unicode tag text (including JSON-escaped). Useful when you render user-generated content such as reviews, profiles, or comments. Matches are logged as indirect_prompt_injection.

robots.txt Enforcement

Parses your robots.txt per RFC 9309 — grouped User-agent lines, Allow rules with longest-match precedence, bot-specific groups overriding *, and * / $ wildcards — and boosts confidence when a detected bot requests a disallowed path.

Request Fingerprinting

Header signals: missing browser headers (only ones every current engine sends — Chromium-only Sec-CH-UA* and HTTP/2-forbidden Connection are not counted, so Firefox and Safari are not scored as suspicious for lacking them), alphabetical header order, anomalous Accept header, an explicit Connection: close, and no navigation context.

Edge fingerprints. A client's JA4 TLS fingerprint is hard to fake with a user-agent string. CloudFront sends it as CloudFront-Viewer-JA4-Fingerprint; on Cloudflare, add a request header transform rule (cf-ja4 = cf.bot_management.ja4, and cf-bot-score = cf.bot_management.score). A request claiming a browser whose JA4 shows no SNI, no TLS 1.3, or HTTP/1.1-first ALPN is flagged, as is any fingerprint you list in client_ja4. Because anyone can send these headers, they are only read from requests that came through a trusted proxy.

Datacenter IPs. A browser user-agent from AWS, Google Cloud, or Oracle Cloud adds to the score. It is weak evidence alone (VPNs, corporate proxies), so it only tips requests that other signals already make suspicious. Lists are compiled once and cached; warm them with php artisan ai-guard:refresh-ranges (and set fetch_on_request to false to never fetch during a request).

ML Detection (Optional)

By default ML only refines borderline scores: strong regex detections are never sent to a provider, so ML cannot talk them down. On always_run_on paths (your chat endpoints) every input is classified, so ML catches paraphrased attacks that no pattern matches.

To enable, add your API key to .env and set enabled to true:

Rate Limiting

Applies in rate_limit mode. Counters use Laravel's rate limiter, on your default cache store.

Alerts

AI Usage Preferences

Tell AI crawlers how your content may be used. ai-guard:robots-txt writes both into robots.txt, and the ai-guard.preferences middleware sends a Content-Usage response header:

Both standards are drafts and advisory — crawlers may ignore them — so they complement blocking rather than replace it.

Dashboard & API Authentication

For local development without authentication:

Security note: Always re-enable authentication before deploying to production. The dashboard and API expose IP addresses, request URLs, and threat data.

False Positives

If you test your API with Postman, Insomnia, or curl, whitelist them — otherwise your own requests are logged as threats:

AI Agents on Your Site

User-triggered AI agents (ChatGPT-User, Perplexity-User, Operator, Google-Agent, signed Web Bot Auth agents) fetch pages for a person, and many do not read robots.txt. Decide per route who may use a page — checkout, account, and booking pages are the usual candidates:

"Verified" means a valid Web Bot Auth signature or the operator's published IP ranges, so turn on bot_verification. This is an access rule: it is enforced in every mode, refused agents get a 403, and each refusal is logged as ai_agent_denied. People and crawlers that are not agents pass through to the main middleware.

Guarding Your Own LLM Features

The middleware protects inbound traffic. The following protect the LLM features you build — chatbots, agents, RAG, MCP servers.

A note on what to rely on: detecting prompt injection (patterns, ML, spotlighting) catches known and careless attacks, but a determined attacker who adapts can get past any detector. The controls that hold are the ones that do not need to recognise the attack — the tool-call firewall, the egress allow-list, taint tracking, and safe rendering limit what an injected model can actually do. Use detection as a signal; use those for protection.

Routes that call a model

Put ai-guard.llm on the routes that send user input to a model:

It checks, before your controller runs:

• Budgets — requests and tokens per minute, tokens and cost per day, per user (or IP for guests), with per-model prices, a global daily spend limit, and a maximum input size. Budgets are quotas, so they are enforced in every mode: over the limit is a 429 with Retry-After, an oversized prompt a 413.
• Moderation (llm_guard.moderation, opt-in) — harm categories via OpenAI's free omni-moderation endpoint, Llama Guard 3 on Ollama, or your own endpoint; limit it to the categories you care about with block_categories.
• Topic policy (llm_guard.topics, opt-in) — topics the assistant must not discuss, or the only topics it may discuss, by keyword, regex, or a local classifier.
• Multi-turn escalation — gradual "crescendo" jailbreaks spread over several messages. Send the conversation ID in an X-Conversation-Id header or a conversation_id field.

Record what a call actually used, so budgets and cost tracking stay accurate:

Behind the ai-guard.llm middleware, the input was already reserved when the request came in. The first recordUsage() call in that request for the same user and tier settles that reservation, so the input is not counted twice. If you reserved it some other way (for example with consumeBudget()), say how much:

The same checks are available directly: AiGuard::checkBudget() (or consumeBudget(), which reserves the estimate as it checks — what the middleware uses, so simultaneous calls cannot each pass the same check), moderate(), checkTopic(), and observeConversation().

Redact personal data, restore it in the reply

Which types are masked, and which are put back, is set in llm_guard.redaction.

Spotlight untrusted content

Text your app did not write — a web page, an email, a document, a tool result — should reach the model as data, not instructions:

Modes: delimit (random boundary markers), datamark (a marker between every word), and base64.

Scan model output before returning it

scanOutput() flags:

• Zero-click exfiltration — markdown or HTML images whose URL carries data (![](https://evil.example/p.png?d=<base64 of the chat>)), which the browser fetches without a click
• Data-bearing links to other domains (allow your own with llm_guard.allowed_domains)
• System-prompt leaks — a canary token (even if spaced out or base64-encoded), or any system-prompt sentence repeated verbatim
• Secrets and PII in the reply, and harmful content when moderation is on
• Instructions aimed at downstream agents (chat-template tokens, injection phrases)

Render model output safely

@aiSafe (or AiGuard::safeHtml($reply)) renders Markdown with raw HTML escaped, then removes scripts, event handlers, javascript: and data: links, and images that would load from — and leak chat data to — hosts other than yours and llm_guard.allowed_domains. Links get rel="nofollow noopener noreferrer". Options in llm_guard.rendering.

Add a Content-Security-Policy to the pages that show model output, so an injection that slips through still cannot run script or load remote images:

The nonce is shared with Vite, and the policy is set in llm_guard.csp.

Canary tokens

Canaries are HMAC-signed with your APP_KEY (or llm_guard.canary_secret), so AiGuard::isCanary($token) rejects forged ones.

Tool-call firewall

An agent that reads untrusted content and can also act — send email, write files, call APIs — is the combination attackers look for. The firewall checks each tool call before it runs:

• Roles, a JSON Schema for the arguments, and authorize callbacks (ToolFirewall::define('refund', ['authorize' => fn ($args, $user) => ...])). The supported subset covers types, enums, string and numeric rules, arrays, objects, and allOf/anyOf/oneOf/not; a keyword it cannot check ($ref, patternProperties, …) denies the call rather than letting the argument through unchecked
• Egress allow-list — URLs and email addresses in an egress tool's arguments must be on egress_domains, found wherever they hide: nested values, array keys, mailto: addresses, and URL shapes only a browser resolves (https:/host, //host, backslashes)
• Taint tracking — once untrusted content (a fetched page, an email, a flagged tool result) enters the conversation, write and egress tools need a person's approval (or are refused with tainted_action => 'block')
• Approval tokens — signed, single-use, and bound to the tool, the exact arguments, and the user. Signing needs an APP_KEY; without one, minting an approval fails rather than falling back to a guessable key
• A cap on tool calls per conversation, counted across the whole conversation rather than one request

Refusals are logged as tool_call_blocked and held calls as tool_call_held.

MCP

Servers you serve. Put ai-guard.mcp on your MCP route (laravel/mcp or any JSON-RPC endpoint):

Every tools/call is scanned and checked against the tool policies above — decided from the decoded JSON-RPC body, not the Content-Type. A refused call gets a JSON-RPC error; a call that needs approval gets error -32002, and the client retries with the token from AiGuard::approveToolCall() in an X-AI-Guard-Approval header.

Results are scanned (including event-stream responses) and a poisoned result taints the MCP session. A tool whose policy sets untrusted_output taints the session as soon as it is called, so a result that comes back over a stream this middleware cannot read still guards the calls that follow it. The session is keyed to the authenticated client, not to the MCP-Session-Id it sends.

Servers you use. Before handing an MCP server's tools to an agent:

• Server allow-list — llm_guard.mcp.allowed_servers; tools from other servers are dropped (mcp_server_blocked)
• Tool pinning — every tool definition is pinned on first sight. If a name, description, or schema changes later — a "rug pull" — the tool is dropped until you approve the new definition (mcp_tool_changed)
• Poisoning scan — hidden instructions in tool descriptions are dropped (tool_injection)

Scan any tool definition, argument set, or result directly with AiGuard::scanToolCall($payload, 'definition' | 'arguments' | 'result').

laravel/ai agents

With laravel/ai installed, add the prompt guard to an agent and wrap its tools:

GuardPrompt runs the budget, injection, topic, moderation, and escalation checks before the provider is called, can redact the prompt and restore the reply, scans the reply for exfiltration and leaks of the agent's instructions, and records token usage. A blocked prompt throws JayAnta\AiGuard\Exceptions\AiGuardBlockedException, which renders as a JSON 403, 429, or 413 if you do not catch it. Streamed replies are scanned and logged when the stream ends. It works with laravel/ai 0.x and 1.x; under 1.x, where middleware runs once per step of the agent loop, the input is checked on the first step, redaction holds for every step, and token usage is recorded for each one.

AiGuard::guardTools() puts each tool — including sub-agents, ToolSearch tool sets, and MCP client and server tools — behind the tool firewall. A refused call never runs (the model is told why), and a call that needs approval pauses the run through laravel/ai's own approval flow.

Model-written SQL

For "ask your data" features that let a model write SQL:

runReadOnlySql() re-runs the check itself, so pass it the same options — otherwise it checks against llm_guard.sql in your config alone, where no allowed_tables means every table is allowed.

The check accepts a single read-only statement over allowed tables and refuses writes (including data-modifying CTEs), INTO OUTFILE, row locks, sleep and file functions, and system catalogs. Where a statement could be read two ways — backslash escapes, MySQL /*! */ and # comments, an unterminated quote — it fails closed. runReadOnlySql() caps the rows as it reads them and runs the query in a transaction that is always rolled back (read-only on MySQL and PostgreSQL). Still use a database user with SELECT rights only.

Red Teaming

Measure how AI Guard, as configured in your app, handles known attacks:

It runs a bundled corpus — prompt injections, system-prompt extraction, jailbreaks, tool poisoning, output exfiltration, egress destinations hidden in tool arguments, model-written SQL, unsafe rendering, and benign prompts that look like attacks ("ignore the typos in my last message", "act as a reviewer") — through up to 11 encodings (base64, zero-width, homoglyphs, fullwidth, leetspeak, spacing, URL and HTML encoding, Unicode tags, emoji variation selectors, code fences), and reports detection and false-positive rates per category and per encoding.

The bundled corpus is a regression suite, not a benchmark. The v3 patterns were tuned against it: its first run caught 61% of attacks with a 3.3% false-positive rate, and after every miss was fixed — with general patterns and de-obfuscation, not by matching the corpus text — v3.0 catches all 406 attack variants (100 cases with --mutations=all) with no false positives on its 35 benign cases. It measures the detectors as this package configures them, on attacks that are already known; it says nothing about attacks nobody has written down yet. The test suite also checks phrasings that are not in the corpus. For an independent measurement, export the corpus and run garak or promptfoo against your endpoint.

Options: --suite=injection,jailbreak,..., --mutations=none|basic|all|<list>, --format=json, --show-misses.

Audit Trail and Export

• Tamper-evident log — each row stores an HMAC (keyed by your APP_KEY, or audit.chain_key) of the previous row's hash and its own contents, and the newest row is also recorded — signed — outside the database, so deleting the end of the chain, or emptying the table, is caught too. php artisan ai-guard:audit-verify names the first row that was changed, reordered, or removed; someone with database access alone cannot re-seal the chain. Without an APP_KEY the chain refuses to seal rather than signing with a guessable key.
• Retention — php artisan ai-guard:prune --days=90 (or retention_days) deletes old rows and records where the chain now starts, so the rest stays verifiable. Schedule it daily.
• SIEM — every threat as JSON (signed with X-AI-Guard-Signature: sha256=<HMAC of the body>) or ArcSight CEF lines.
• OpenTelemetry — OTLP/HTTP log records with ai_guard.* attributes, gen_ai.tool.name for tool events, and gen_ai.usage.* token usage recorded by budgets and agents.
• Log channel — any Laravel log channel.

Exports are buffered and sent when the request, command, or queued job ends, so they never slow a response; a failed export is logged and never breaks the app. Threats are exported even when database logging is off.

Events

Every detection dispatches a JayAnta\AiGuard\Events\ThreatDetected event, so you can plug in your own notifications, IP banning, or metrics:

This includes tool-firewall, MCP, budget, and agent-policy decisions. Listener exceptions are caught and logged — a broken listener never breaks request handling. AiGuard::log() dispatches the event too.

Interop Contract

ThreatDetected reports what AI Guard acted on. The interop contract, ai-guard.verdict/1, reports who the client is — for other packages and services that want AI Guard's bot identity without depending on AI Guard. It is a published convention, not an API: named events and a request attribute, read by class-name string and array key, with nothing to import. Code that listens keeps working when AI Guard is not installed; the events simply never fire.

Events — at most once per request, when an AI Guard middleware first evaluates it:

Each carries scalar, read-only properties — schema, category, token, identity, status, method, ip, requestMethod, path (no query string), evaluatedAt — and toArray(). Ordinary visitors fire nothing.

Request attribute — after an AI Guard middleware has run, request()->attributes->get('ai_guard.verdict'):

Absent means the request was not evaluated: the package is disabled, the request is whitelisted, or no AI Guard middleware has evaluated it yet (ai-guard.agents:allow lets everyone through without evaluating). Present with nulls means evaluated: not a recognised bot.

What to rely on:

• identity is only confirmed when status is verified. Otherwise it is what the client claimed — anyone can send a request that claims to be chatgpt.com and gets reported as spoofed. Treat a spoofed identity as the name being impersonated, and rate-limit anything that alerts on it.

• Identity, not policy. The category is the client's best match across every category — a verified Googlebot reads as search_engines even though that category is not blocked by default — and it does not depend on the blocking mode.
• status null means unknown, not unverified: verification is off by default (bot_verification.enabled), and without it AgentVerified and SpoofedBotDetected never fire.
• Timing. Events fire when AI Guard evaluates the request. Code that decides in middleware running before AI Guard's should decide after $next($request) instead, or register AI Guard earlier.
• Versioning. Within v1, fields and enum values may be added, never renamed or removed — treat an unknown value as unknown, not as an error. A breaking change becomes ai-guard.verdict/2, emitted alongside v1 for at least one minor release. Contract changes are listed under their own heading in the CHANGELOG.
• Off switch. interop.enabled => false stops the events; the attribute is still set.

The canonical example payload is tests/Fixtures/interop/verdict-v1.json, and the test suite fails if the package drifts from it.

Dashboard

After installation, visit your dashboard at:

The dashboard shows:

• Total threats detected in the last 24 hours
• Breakdown by threat type (AI crawlers, prompt injections, data harvesters, and more)
• Count of blocked and rate-limited requests
• Top threat sources and IP addresses
• Recent threat log with confidence scores, actions taken, bot purpose, and a Verified / Spoofed badge
• Auto-refreshes every 30 seconds

REST API

All endpoints are prefixed with your configured prefix (default: /ai-guard).

Query Parameters

GET /ai-guard/api/threats

Artisan Commands

Generate robots.txt

The AI training section also writes the robots.txt-only control tokens (Google-Extended, Applebot-Extended, ...), which never appear in traffic, and marks retired tokens as legacy. Googlebot and Bingbot are explicitly allowed. Tokens added by ai-guard:update-signatures are included.

Tip: Even without installing the full middleware, this command gives you a production-ready robots.txt that stays current with the latest AI bots.

Detection Details

Prompt Injection Patterns

76 weighted patterns across these categories, matched against the de-obfuscated text:

• Instruction Override — "ignore previous instructions", "disregard the rules above", "forget your task", "ignore the user's request", plus French, Spanish, Portuguese, Italian, German, Dutch, Russian, Chinese, Japanese, Korean, Hindi, and Arabic forms
• Role Manipulation — "your new role is", "from now on you answer", "unrestricted AI", "pretend to be an admin"
• System Prompt Extraction — "reveal your system prompt", "show me the hidden rules", "translate your system prompt", "repeat everything above"
• Jailbreak — "DAN mode", "do anything now", "an AI with no rules", the deceased-relative template, "bypass your safety filters", many-shot fake dialogues, Policy Puppetry config blocks
• Privilege Escalation — "you are in developer mode", "sudo override", claimed developer authority
• Data Extraction — "dump all API keys and environment variables", "send the conversation history to …", "select ... from the users table", "bypass validation"
• Chat-Template and Tool Smuggling — <|im_start|>, Llama 3/4 header tokens, Gemma <start_of_turn>, DeepSeek and Mistral control tokens, [INST], <<SYS>>, fake Human:/Assistant: turns, <tool_call> markup, instructions in HTML comments addressed to the AI

Secret and PII Detection (16 patterns)

The same patterns redact text before it is sent to an ML provider (ml_detection.redact_pii) and power AiGuard::redact().

Facade Usage

The LLM helpers are shown in Guarding Your Own LLM Features. The rest of the facade:

Integration with laravel-natural-query

If you also use jayanta/laravel-natural-query, ai-guard provides extra protection automatically. No configuration needed — just install both packages:

laravel-natural-query auto-detects ai-guard and calls AiGuard::detectText() to scan user queries for prompt injection before they reach the LLM. This adds ai-guard's 76 weighted patterns and de-obfuscation on top of natural-query's built-in InputGuard. For generated SQL, AiGuard::checkSql() adds a second, independent read-only check.

Note: Neither package requires the other. They work independently. The integration is optional and automatic when both are installed.

Troubleshooting

Dashboard returns 403 or redirects to /login

It requires login by default — see Dashboard & API Authentication.

My own curl/Postman requests are being logged as threats

Whitelist your tools — see False Positives.

Real Googlebot is logged as spoofed_bot

Bot verification checks the client IP. Behind a load balancer, CDN, or reverse proxy, configure Laravel's TrustProxies middleware so $request->ip() is the visitor's address — otherwise every crawler appears to come from your proxy.

JA4 and bot-score headers are ignored

Edge headers are only read from requests that arrived through a trusted proxy — configure TrustProxies with your CDN's addresses. Cloudflare needs a transform rule to send them (see Request Fingerprinting).

"ai_threat_logs doesn't exist", or "is missing the v3 columns"

Publish and run the migrations — the same command adds the v3 columns when upgrading:

Until the upgrade migration runs, threats are still logged, just without bot_category, bot_verification, and chain_hash.

ai-guard:audit-verify reports a broken chain

The row it names was edited, moved, or a row before it was deleted outside ai-guard:prune and the API's flush endpoint (for example with DELETE in SQL, TRUNCATE, or migrate:fresh). Rows written before hash_chain was turned on are not part of the chain.

The break stays reported, including after new rows are written: that is what makes a deletion evident. If you emptied the table on purpose and want to start a new chain, also delete the signed record of the chain's end, storage/app/ai-guard/audit-anchor.json (or your audit.anchor_path).

Honeypot conflicts with my real routes

If your app has routes like /admin or /api/v1/users.json, override the trap paths:

Everything is being blocked (403)

Check that mode is set to log_only (not block) and that confidence_threshold is appropriate:

Config changes aren't taking effect

Clear the config cache:

SEO bots (AhrefsBot, SemrushBot) are being logged

SEO tools score 60 confidence by default. If you use these tools and don't want them logged, either:

• Add them to your whitelist: 'whitelist_user_agents' => ['AhrefsBot', 'SemrushBot']
• Or disable the seo_tools category: 'disabled_categories' => ['search_engines', 'seo_tools']

The package is slowing down my app

The in-process detection pipeline (honeypot, signatures, prompt injection, fingerprinting) measured 0.02–0.37 ms per request on PHP 8.1 without OPcache — from a plain browser GET to a 2 KB chat prompt. Database writes happen only for detections, and audit exports are sent after the response. If you notice slowness:

• Disable response scanning (it scans every outgoing response body)
• Keep ML detection and moderation off, or limit them to the routes that need them
• Leave bot verification's cache enabled (cache_minutes) and warm range lists with ai-guard:refresh-ranges
• Check that your ai_threat_logs table has indexes (they're created by the migrations)

How It Compares

crawler-detect answers "is this a bot?"; spatie/laravel-honeypot stops form spam; Cloudflare works at the edge and needs your DNS, with the AI features as paid add-ons. AI Guard covers the AI-scraper and LLM-security threat model inside your Laravel app — and works alongside Cloudflare (it reads Cloudflare's JA4 and bot-score headers).

Testing

The suite has 480 tests. Feature tests run full request → middleware → detection → database → events pipelines against the package's real migrations: bot purpose policies, Web Bot Auth with real Ed25519 signatures, IP-range and reverse-DNS verification, edge fingerprints, ML and moderation drivers against faked providers, budgets, the tool firewall and MCP pinning, laravel/ai agents (when laravel/ai is installed), safe rendering and CSP, the SQL gate, the audit chain and exports, and every Artisan command. Unit tests cover signature matching, RFC 9309 parsing, text normalization, weighted prompt-injection scoring (including held-out phrasings that are not in the red-team corpus and a false-positive corpus), IP range sets, and secret patterns.

Tests never make real network calls (Http::preventStrayRequests()).

Changelog

See UPGRADE.md for upgrade steps.

Contributing

Contributions are welcome — new bot signatures, verification sources, and injection patterns especially. Run php artisan ai-guard:redteam before and after changing a pattern. See CONTRIBUTING.md for guidelines.

Security

If you discover a security vulnerability, please follow the security policy — do not open a public issue.

Credits

Created by ai.robots.txt project (MIT).

License

The MIT License (MIT). See LICENSE for more information.