agentoom / core-sentinel

0.8.0 2026-10-27 08:35 UTC

Requires

• php: ^8.2
• agentoom/core-main: *

MIT

Published on Packagist.org on 2026-10-27 08:45 UTC

README

Real-time security guardrails, human authorization gates, and OTP verification system for Agentoom.

Important

Post-Splitting Versioning & Pre-Release Notice (v0.8.0) Version 0.8.0 represents the initial standalone release following the modular package extraction and architectural splitting from the Agentoom core monorepo. This package is currently in a pre-release state undergoing integration testing and requires appropriate validation and test coverage across target environments before being designated as production-stable (1.0.0).

🌟 Overview

The agentoom/core-sentinel package is Agentoom's tool execution security layer. It prevents prompt injection exploits, unauthorized tool calls, and high-impact automated mistakes by enforcing permission boundaries, parameter validations, email OTP verifications, and interactive confirmations before an agent is permitted to execute sensitive tools or actions.

• Package Name: agentoom/core-sentinel
• Version: 0.8.0 (Pre-release / Post-split testing)
• Namespace: Agentoom\Sentinel\
• Service Provider: Agentoom\Sentinel\SentinelServiceProvider

🚀 Key Features

1. Tool Execution Security Buffer

• Pipeline Interceptor: Hooks into core-main via SecurityBuffer (implementing SecurityBufferInterface).
• Pre-Execution Gate: Whenever an agent attempts to execute an action decorated with #[Sentinelable], the Security Buffer evaluates security policies before execution proceeds.
• Mid-Flight Resumption: Pauses agent execution cleanly while awaiting authorization and resumes seamlessly once approved.

2. Multi-Factor & Verbal Authorization Drivers

• Email OTP Driver (EmailOtpDriver):
  • Automatically dispatches a cryptographically secure One-Time Password to authorized supervisor emails (SecurityOtpMail).
  • Agent requests the OTP code from the user in chat; execution is granted only when the valid token is submitted.
• Verbal / Interactive Driver (VerbalConfirmationDriver):
  • Prompts the user with an explicit confirmation dialog detailing the parameters and expected side effects before running the tool.

3. Dynamic Security Rule Engine

• Rule Evaluator (SecurityRuleEvaluator): Evaluates conditional parameter rules (e.g. amount <= 500, regex matching on email recipients, restricted file paths).
• Context-Aware Scoping: Validates whether the call is originating from an approved user, task, schedule, or autonomous pipeline.
• MCP Tool Protection: Enforces security policies on dynamic Model Context Protocol (MCP) tools matching security keywords.

4. Authorizations & Token Lifecycle

• Authorization Tracking (AiToolAuthorization): Records every grant, approver user ID, expiration timestamp, execution context, and rationale.
• Token Modes: Supports both one-time use tokens (burned immediately after invocation) and time-window duration grants (e.g., valid for 15 minutes).
• Automated Hygiene (CleanupSecurityAuthorizations): Scheduled artisan command to prune expired authorization tokens and stale attempts.

5. Administration & Auditing

• Livewire Admin Console: Review tool definitions (AiToolDefinition), manage required approval tiers, inspect active authorizations, and review audit logs.
• Multi-Language Support: Fully localized in English (en), German (de), Spanish (es), French (fr), and Italian (it).

📁 Package Structure

core-sentinel/
├── database/
│   ├── factories/          # AiToolDefinitionFactory, AiToolAuthorizationFactory
│   └── migrations/         # Schemas for ai_tool_definitions and ai_tool_authorizations
├── resources/
│   ├── lang/               # Translations (de, en, es, fr, it)
│   └── views/
│       ├── emails/         # SecurityOtpMail email templates
│       └── livewire/admin/ # Security policies and authorizations UI
├── routes/
│   └── web.php             # Sentinel admin management routes
└── src/
    ├── Console/Commands/   # CleanupSecurityAuthorizations
    ├── Contracts/          # SecurityDriverInterface
    ├── Drivers/            # EmailOtpDriver, VerbalConfirmationDriver
    ├── Livewire/Admin/     # Livewire admin components
    ├── Mail/               # SecurityOtpMail Mailable
    ├── Models/             # AiToolDefinition, AiToolAuthorization
    ├── Pipes/              # SecurityBuffer execution pipe
    ├── Services/           # SecurityRuleEvaluator
    └── SentinelServiceProvider.php

💻 Console Commands

# Clean up expired and stale security authorization tokens
php artisan sentinel:cleanup-authorizations

🛠️ Decorating Tools with Sentinel

To protect any tool method within Agentoom with Sentinel guardrails, apply the #[Sentinelable] attribute:

use Agentoom\Core\Attributes\Sentinelable;

class PaymentTool
{
    #[Sentinelable(
        name: 'Refund Transaction',
        description: 'Issues a monetary refund to a customer account.',
        category: 'Finance'
    )]
    public function refund(Request $request): string
    {
        // Executes only after security authorization passes
    }
}