AI Agent Tool Sandboxing in Laravel

<?php

declare(strict_types=1);

namespace App\Services\Ai;

use Illuminate\Support\Facades\DB;

class VulnerableAgentExecutor
{
    /**
     * [INSECURE]: Dynamically invoking arbitrary methods and running unchecked SQL.
     */
    public function executeAgentFunction(string $functionName, array $arguments): mixed
    {
        // Vulnerable: Blindly executing whatever function name the LLM outputs
        if (method_exists($this, $functionName)) {
            return $this->$functionName(...$arguments);
        }

        // Dangerous: Raw query execution tool given to model
        if ($functionName === 'execute_query') {
            return DB::statement($arguments['sql']);
        }

        return 'Unknown tool';
    }
}

<?php

declare(strict_types=1);

namespace App\Services\Ai\Tools;

use App\Models\User;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Validator;
use InvalidArgumentException;
use RuntimeException;

interface AgentToolInterface
{
    public function name(): string;
    public function description(): string;
    public function schema(): array;
    public function execute(User $caller, array $arguments): array;
}

final class SendNotificationTool implements AgentToolInterface
{
    public function name(): string
    {
        return 'send_user_notification';
    }

    public function description(): string
    {
        return 'Sends a plain-text notification message to an authenticated team member.';
    }

    public function schema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'recipient_id' => ['type' => 'integer'],
                'message' => ['type' => 'string'],
            ],
            'required' => ['recipient_id', 'message'],
        ];
    }

    public function execute(User $caller, array $arguments): array
    {
        // 1. Authorize: Verify caller has permission to perform this action
        if (!Gate::forUser($caller)->allows('send-team-notifications')) {
            throw new RuntimeException('Unauthorized: Caller lacks permission to invoke notification tool.');
        }

        // 2. Validate tool arguments strictly with Laravel Validator
        $validated = Validator::make($arguments, [
            'recipient_id' => ['required', 'integer', 'exists:users,id'],
            'message' => ['required', 'string', 'max:500'],
        ])->validate();

        // 3. Execute safely within tenant boundary
        $recipient = User::where('tenant_id', $caller->tenant_id)
            ->findOrFail($validated['recipient_id']);

        // Dispatch notification safely
        return [
            'status' => 'success',
            'message' => "Notification dispatched to user {$recipient->id}.",
        ];
    }
}

final class SecureAgentDispatcher
{
    /** @var array<string, AgentToolInterface> */
    private array $allowedTools = [];

    public function registerTool(AgentToolInterface $tool): void
    {
        $this->allowedTools[$tool->name()] = $tool;
    }

    /**
     * [SECURE]: Explicit allowlist dispatch, argument validation, and authorization check.
     */
    public function dispatchTool(User $user, string $toolName, array $rawArguments): array
    {
        if (!array_key_exists($toolName, $this->allowedTools)) {
            throw new InvalidArgumentException("Tool [{$toolName}] is not in the approved agent tool allowlist.");
        }

        $tool = $this->allowedTools[$toolName];

        // Critical safety: Destructive tools require human confirmation token
        if ($this->isDestructive($toolName)) {
            return [
                'status' => 'pending_confirmation',
                'action_token' => bin2hex(random_bytes(16)),
                'message' => 'Action requires human approval before execution.',
            ];
        }

        return $tool->execute($user, $rawArguments);
    }

    private function isDestructive(string $toolName): bool
    {
        return in_array($toolName, ['delete_record', 'process_refund', 'transfer_funds'], true);
    }
}