AgentGuard MCP

Авторизация с учётом идентичности для ИИ-агентов.

AgentGuard MCP — это защищённый сервер Model Context Protocol, который выдаёт ИИ-агентам отдельные машинные идентичности, обеспечивает соблюдение OAuth-разрешений с минимальными привилегиями, применяет контекстную политику авторизации и приостанавливает чувствительные действия до подтверждения аутентифицированным человеком перед выполнением.

Это бэкенд авторизации для AgentGuard.

Живой продукт: https://agentguard-eight.vercel.app

Зачем AgentGuard?

Дать ИИ-агенту доступ к инструменту легко.

Контролировать какой агент может использовать какой инструмент, при каких условиях и когда должен вмешаться человек — сложнее.

AgentGuard разделяет эти задачи:

• Auth0 аутентифицирует машинные и человеческие идентичности.

• OAuth-скоупы определяют, что каждой машинной идентичности разрешено запрашивать.

• Политика AgentGuard оценивает контекст действия.

• Подтверждение человеком контролирует операции повышенного риска.

• Supabase сохраняет состояние подтверждений и события аудита безопасности.

• MCP предоставляет защищённые инструменты средам выполнения ИИ.

Таким образом, агент может быть аутентифицирован, но при этом ему не доверяется автоматически выполнение любого действия.

Related MCP server: gov-mcp

Архитектура

flowchart LR
    A[AI Agent] --> B[Auth0 Machine Identity]
    B --> C[OAuth Access Token]
    C --> D[AgentGuard MCP Server]

    D --> E{Required Scope?}

    E -->|Missing| F[DENY]
    E -->|Granted| G[Contextual Policy]

    G -->|Low Risk| H[ALLOW]
    G -->|Sensitive| I[APPROVAL_REQUIRED]
    G -->|Forbidden| F

    I --> J[(Supabase Approval)]
    J --> K[Auth0 Human Login]
    K --> L{Human Decision}

    L -->|Approve| M[APPROVED]
    L -->|Deny| N[DENIED]

    M --> O[Agent Retries Approved Action]
    O --> P[Identity + Approval Verification]
    P --> Q[Execute Once]

    F --> R[(Audit Events)]
    H --> R
    I --> R
    N --> R
    Q --> R

Модель безопасности

AgentGuard использует два отдельных класса идентичностей.

Машинные идентичности

Каждая автономная среда выполнения получает отдельную идентичность Auth0 Machine-to-Machine.

Примеры демонстрационных идентичностей:

Торговый агент не может выполнять возвраты только потому, что это может другой агент.

Слой авторизации проверяет скоупы, содержащиеся в OAuth-токене доступа вызывающей стороны, перед выполнением защищённого инструмента.

Человеческие идентичности

Люди-операторы аутентифицируются отдельно через Auth0 Regular Web Application в панели управления AgentGuard.

Машинные и человеческие идентичности намеренно разделены.

Поэтому чувствительный запрос может выглядеть так:

Finance Agent
    ↓
Authenticated machine identity
    ↓
finance:refund scope
    ↓
Contextual policy
    ↓
APPROVAL_REQUIRED
    ↓
Authenticated human administrator
    ↓
APPROVED
    ↓
Finance Agent executes approved action

Слои авторизации

AgentGuard применяет авторизацию по слоям.

1. Аутентификация

MCP-сервер проверяет токен доступа Auth0 и устанавливает личность вызывающей стороны.

2. Авторизация по OAuth-скоупам

Защищённые инструменты объявляют скоупы, необходимые для их вызова.

Пример:

@require_scopes(["finance:refund"])

Если у вызывающей стороны нет требуемого скоупа, выполнение немедленно прекращается.

3. Контекстная политика

Прохождение проверки OAuth не означает автоматическую авторизацию выполнения.

AgentGuard оценивает контекст запрошенного действия.

Текущие демонстрационные правила включают:

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

4. Подтверждение человеком

Чувствительные операции записываются в хранилище подтверждений и приостанавливаются.

Отдельно аутентифицированный человек может одобрить или отклонить запрос через панель управления AgentGuard.

5. Выполнение, привязанное к подтверждению

Одобренное действие может быть выполнено только той машинной идентичностью, которая изначально его запросила.

AgentGuard проверяет:

• подтверждение существует

• статус подтверждения — APPROVED

• подтверждение принадлежит запрашивающей идентичности

• действие подтверждения соответствует запрошенному инструменту

• подтверждение ещё не было выполнено

6. Защита от повторного воспроизведения

После успешного выполнения:

APPROVED
→ EXECUTED

Повторная попытка выполнения отклоняется и записывается как событие безопасности.

Продемонстрированные сценарии безопасности

Проект включает три сохранённых сценария, которые также видны в публичной демонстрации AgentGuard.

Подтверждено человеком

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator approves
→ Finance Agent executes
→ ALLOW
→ approval becomes EXECUTED

Отклонено человеком

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator denies
→ Finance Agent attempts execution
→ DENY

Скоуп заблокирован

Sales Agent
→ attempts issue_refund
→ missing finance:refund
→ DENY

Contextual policy is never evaluated.
Human review is never reached.

Это демонстрирует разницу между:

• аутентификацией

• авторизацией

• контекстной политикой

• контролем человека

MCP-инструменты

Текущая демонстрация предоставляет пять защищённых MCP-инструментов.

search_accounts

Поиск аккаунтов в CRM.

Требуемый скоуп:

crm:read

issue_refund

Запросить или выполнить возврат средств в зависимости от политики.

Требуемый скоуп:

finance:refund

Политика:

amount <= $500 → ALLOW
amount > $500  → APPROVAL_REQUIRED

list_pending_approvals

Выводит запросы на подтверждение, ожидающие рассмотрения.

Требуемый скоуп:

agent:manage

approve_action

Административный путь подтверждения через MCP, используемый при тестировании машинных сред выполнения.

Требуемый скоуп:

agent:manage

Портфолио-приложение также поддерживает предпочтительный путь подтверждения человеком через защищённую Auth0 панель управления на Next.js.

execute_approved_refund

Выполняет уже одобренный возврат средств.

Требуемый скоуп:

finance:refund

Перед выполнением сервер проверяет, что подтверждение принадлежит вызывающей машинной идентичности.

Жизненный цикл подтверждения

Записи подтверждений используют четыре состояния:

PENDING
APPROVED
DENIED
EXECUTED

Типичный успешный жизненный цикл:

PENDING
   ↓
APPROVED
   ↓
EXECUTED

Жизненный цикл при отказе:

PENDING
   ↓
DENIED

Рассмотрение и подтверждение хранятся отдельно.

Это позволяет AgentGuard представлять:

DENIED
reviewed_by = Human Administrator
approved_by = null

без ошибочной трактовки отказа человека как подтверждения.

События аудита

AgentGuard записывает решения об авторизации и политике в Supabase.

Примеры событий включают:

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

Метаданные безопасности могут включать:

• предоставленные скоупы

• отсутствующие скоупы

• сбои авторизации

• идентификаторы подтверждений

• запрашивающую идентичность

• контекст действия

• попытки повторного воспроизведения

• проверяющего человека

• идентификаторы аккаунтов/ресурсов

Пример сбоя из-за скоупа:

{
  "action": "issue_refund",
  "decision": "DENY",
  "required_scope": "finance:refund",
  "reason": "Missing required scopes: ['finance:refund']",
  "metadata": {
    "granted_scopes": [
      "crm:read",
      "crm:write",
      "support:read"
    ],
    "missing_scopes": [
      "finance:refund"
    ],
    "security_event": "authorization_failure"
  }
}

Секреты и токены доступа никогда не должны записываться в журнал аудита.

Структура репозитория

agentguard-mcp/
│
├── database/
│   └── schema.sql
│
├── src/
│   ├── auth0/
│   │   ├── __init__.py
│   │   ├── authz.py
│   │   ├── errors.py
│   │   └── middleware.py
│   │
│   ├── approvals.py
│   ├── audit.py
│   ├── config.py
│   ├── database.py
│   ├── policy.py
│   ├── server.py
│   ├── tools.py
│   └── __init__.py
│
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md

База данных

AgentGuard в настоящее время использует Supabase/Postgres для:

approvals

Хранит чувствительные запросы и их жизненный цикл рассмотрения.

Важные поля включают:

requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

executed_at

audit_events

Хранит решения безопасности и контекст выполнения.

Важные поля включают:

identity
action
decision
required_scope
reason
approval_id
metadata
created_at

На обеих таблицах включена безопасность на уровне строк (Row Level Security).

Публичные политики для браузера не создаются.

Доверенные серверные компоненты AgentGuard получают доступ к базе данных, используя учётные данные только для сервера.

См.:

database/schema.sql

Локальная настройка

Требования

• Python 3.10+

• тенант Auth0

• проект Supabase

• приложения Auth0 Machine-to-Machine

• API Auth0, настроенный для MCP-ресурса

Клонирование

git clone https://github.com/haisamar/agentguard-mcp.git
cd agentguard-mcp

Создание виртуального окружения

Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Установка зависимостей

С помощью Poetry:

pip install poetry
poetry install

Или при желании установите необходимые зависимости вручную.

Настройка окружения

Скопируйте:

.env.example

в:

.env

и настройте собственные учётные данные.

Никогда не коммитьте .env.

Требуемые переменные окружения

AUTH0_DOMAIN=
AUTH0_AUDIENCE=http://localhost:3001/
MCP_SERVER_URL=http://localhost:3001/
PORT=3001

SALES_AGENT_CLIENT_ID=
SALES_AGENT_CLIENT_SECRET=

FINANCE_AGENT_CLIENT_ID=
FINANCE_AGENT_CLIENT_SECRET=

ADMIN_AGENT_CLIENT_ID=
ADMIN_AGENT_CLIENT_SECRET=

SUPABASE_URL=
SUPABASE_SECRET_KEY=

Разрешения API Auth0

API AgentGuard в настоящее время определяет разрешения, включая:

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

Приложения Machine-to-Machine должны получать только те разрешения, которые необходимы для их роли.

Запуск MCP-сервера

Из корня репозитория:

python -m src.server

Сервер по умолчанию:

http://localhost:3001/

MCP-эндпоинт:

http://localhost:3001/mcp

Метаданные защищённого ресурса:

http://localhost:3001/.well-known/oauth-protected-resource

Тестирование с помощью MCP Inspector

Запустите MCP Inspector:

npx -y @modelcontextprotocol/inspector

Подключитесь, используя:

Transport:
Streamable HTTP

URL:
http://localhost:3001/mcp

Используйте токен доступа Auth0 Machine-to-Machine в заголовке авторизации:

Authorization: Bearer <ACCESS_TOKEN>

Не коммитьте и не раскрывайте токены доступа.

Фронтенд

Сопутствующий интерфейс продукта AgentGuard доступен здесь:

Репозиторий

https://github.com/haisamar/agentguard

Живое демо

https://agentguard-eight.vercel.app

Он предоставляет:

• публичную страницу продукта

• очищенную публичную демонстрацию безопасности

• защищённую Auth0 панель администратора

• элементы управления для подтверждения/отказа человеком

• визуализацию машинной и человеческой идентичности

• обозреватель трассировки авторизации

• интерактивную проверку событий безопасности

• историю подтверждений

Технологии

AgentGuard объединяет:

Auth0
OAuth 2.0
Model Context Protocol
Python
FastMCP
Starlette
Supabase / PostgreSQL
Next.js
Human-in-the-loop authorization

Принцип проектирования

AgentGuard основан на простой идее:

Аутентификация ИИ-агента не должна означать, что у него есть неограниченные полномочия.

Аутентификация доказывает, кем является агент.

OAuth-скоупы определяют, какую категорию действий он может запрашивать.

Контекстная политика определяет, может ли это конкретное действие выполняться автономно.

Подтверждение человеком обеспечивает отдельную границу идентичности для решений с высоким риском.

Текущий охват

AgentGuard — это портфолио-прототип системы безопасности, а не производственная IAM-платформа.

Текущие ограничения намеренно включают:

• демонстрационные правила политики определены в коде

• машинные идентичности сопоставлены с демонстрационными ролями

• MCP-бэкенд предназначен для контролируемого/локального развертывания

• авторизация человека-администратора в настоящее время использует список разрешённых администраторов на уровне приложения

• управление политикой ещё не доступно через плоскость управления

• неизменяемость событий аудита не обеспечивается на уровне базы данных

• распределённая блокировка для параллельного выполнения выходит за рамки текущей демонстрации

Эти границы намеренно задокументированы, а не скрыты.

Возможные расширения

Будущие версии могут добавить:

• администрирование людей на основе ролей Auth0

• политику как код

• версионирование политики

• реестр идентичностей агентов

• федерацию идентичностей рабочих нагрузок

• делегированную авторизацию

• подтверждения с ограничением по времени

• авторизацию на уровне ресурсов

• истечение срока действия подтверждений

• изоляцию на уровне организаций

• подписанные события аудита

• экспорт в SIEM

• симуляцию политики

• продакшн-развертывание MCP

• дополнительные MCP-инструменты и серверы ресурсов

Связанный проект

Фронтенд AgentGuard:

https://github.com/haisamar/agentguard