AgentGuard MCP

Identitätsbewusste Autorisierung für KI-Agenten.

AgentGuard MCP ist ein geschützter Model Context Protocol-Server, der KI-Agenten eindeutige Maschinenidentitäten verleiht, OAuth-Berechtigungen mit geringsten Rechten durchsetzt, kontextbezogene Autorisierungsrichtlinien anwendet und sensible Aktionen für die authentifizierte menschliche Genehmigung vor der Ausführung pausiert.

Es ist das Autorisierungs-Backend für AgentGuard.

Live-Produkt: https://agentguard-eight.vercel.app

Warum AgentGuard?

Einem KI-Agenten Zugriff auf ein Tool zu gewähren, ist einfach.

Zu kontrollieren, welcher Agent welches Tool unter welchen Bedingungen verwenden darf und wann ein Mensch eingreifen muss, ist schwieriger.

AgentGuard trennt diese Belange:

• Auth0 authentifiziert Maschinen- und Menschenidentitäten.

• OAuth-Scopes definieren, was jede Maschinenidentität anfordern darf.

• AgentGuard-Richtlinie bewertet den Kontext der Aktion.

• Menschliche Genehmigung sperrt risikoreichere Operationen.

• Supabase speichert Genehmigungsstatus und Sicherheits-Audit-Ereignisse.

• MCP stellt die geschützten Tools für KI-Laufzeiten bereit.

Ein Agent kann daher authentifiziert sein, ohne automatisch die Berechtigung zu haben, jede Aktion auszuführen.

Related MCP server: gov-mcp

Architektur

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

Sicherheitsmodell

AgentGuard verwendet zwei getrennte Identitätsklassen.

Maschinenidentitäten

Jede autonome Laufzeit erhält eine separate Auth0 Machine-to-Machine-Identität.

Beispiel-Demo-Identitäten:

Ein Vertriebsagent kann keine Rückerstattungen ausstellen, nur weil ein anderer Agent dies kann.

Die Autorisierungsschicht prüft die Scopes, die im OAuth-Zugriffstoken des Aufrufers enthalten sind, bevor das geschützte Tool ausgeführt wird.

Menschenidentitäten

Menschliche Bediener authentifizieren sich separat über eine Auth0 Regular Web Application im AgentGuard-Dashboard.

Maschinenidentitäten und Menschenidentitäten sind bewusst getrennt.

Eine sensible Anfrage kann daher wie folgt aussehen:

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

Autorisierungsebenen

AgentGuard wendet Autorisierung in Ebenen an.

1. Authentifizierung

Der MCP-Server validiert das Auth0-Zugriffstoken und stellt die Identität des Aufrufers fest.

2. OAuth-Scope-Autorisierung

Geschützte Tools deklarieren die Scopes, die für ihren Aufruf erforderlich sind.

Beispiel:

@require_scopes(["finance:refund"])

Wenn der Aufrufer nicht über den erforderlichen Scope verfügt, wird die Ausführung sofort gestoppt.

3. Kontextuelle Richtlinie

Das Bestehen der OAuth-Prüfung autorisiert die Ausführung nicht automatisch.

AgentGuard bewertet den Kontext der angeforderten Aktion.

Aktuelle Demo-Regeln umfassen:

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

4. Menschliche Genehmigung

Sensible Operationen werden in den Genehmigungsspeicher geschrieben und pausiert.

Eine separat authentifizierte Person kann die Anfrage über das AgentGuard-Dashboard genehmigen oder ablehnen.

5. Genehmigungsgebundene Ausführung

Eine genehmigte Aktion kann nur von der Maschinenidentität ausgeführt werden, die sie ursprünglich angefordert hat.

AgentGuard prüft:

• Genehmigung existiert

• Genehmigungsstatus ist APPROVED

• Genehmigung gehört zur anfordernden Identität

• Genehmigungsaktion entspricht dem angeforderten Tool

• Genehmigung wurde noch nicht ausgeführt

6. Replay-Schutz

Nach erfolgreicher Ausführung:

APPROVED
→ EXECUTED

Ein zweiter Ausführungsversuch wird abgelehnt und als Sicherheitsereignis protokolliert.

Demonstrierte Sicherheitsfälle

Das Projekt enthält drei persistierte Szenarien, die auch in der öffentlichen AgentGuard-Demo sichtbar sind.

Menschlich genehmigt

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

Menschlich abgelehnt

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

Scope blockiert

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

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

Dies demonstriert den Unterschied zwischen:

• Authentifizierung

• Autorisierung

• kontextueller Richtlinie

• menschlicher Kontrolle

MCP-Tools

Die aktuelle Demo stellt fünf geschützte MCP-Tools bereit.

search_accounts

CRM-Konten durchsuchen.

Erforderlicher Scope:

crm:read

issue_refund

Rückerstattung je nach Richtlinie anfordern oder ausführen.

Erforderlicher Scope:

finance:refund

Richtlinie:

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

list_pending_approvals

Listet Genehmigungsanfragen, die auf Überprüfung warten.

Erforderlicher Scope:

agent:manage

approve_action

Administrativer MCP-Genehmigungspfad, der beim Testen der Maschinenlaufzeit verwendet wird.

Erforderlicher Scope:

agent:manage

Die Portfolio-Anwendung unterstützt auch einen bevorzugten menschlichen Genehmigungspfad über das Auth0-geschützte Next.js-Dashboard.

execute_approved_refund

Führt eine bereits genehmigte Rückerstattung aus.

Erforderlicher Scope:

finance:refund

Der Server überprüft vor der Ausführung, dass die Genehmigung zur aufrufenden Maschinenidentität gehört.

Genehmigungs-Lebenszyklus

Genehmigungsdatensätze verwenden vier Zustände:

PENDING
APPROVED
DENIED
EXECUTED

Typischer erfolgreicher Lebenszyklus:

PENDING
   ↓
APPROVED
   ↓
EXECUTED

Abgelehnter Lebenszyklus:

PENDING
   ↓
DENIED

Überprüfung und Genehmigung werden getrennt gespeichert.

Dies ermöglicht AgentGuard, Folgendes darzustellen:

DENIED
reviewed_by = Human Administrator
approved_by = null

ohne eine menschliche Ablehnung fälschlicherweise als Genehmigung zu behandeln.

Audit-Ereignisse

AgentGuard zeichnet Autorisierungs- und Richtlinienentscheidungen in Supabase auf.

Beispielereignisse umfassen:

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

Sicherheitsmetadaten können enthalten:

• gewährte Scopes

• fehlende Scopes

• Autorisierungsfehler

• Genehmigungs-IDs

• anfordernde Identität

• Aktionskontext

• Replay-Versuche

• menschlicher Prüfer

• Konto-/Ressourcenkennungen

Beispiel für Scope-Fehler:

{
  "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"
  }
}

Geheimnisse und Zugriffstokens sollten niemals in das Audit-Log geschrieben werden.

Repository-Struktur

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

Datenbank

AgentGuard verwendet derzeit Supabase/Postgres für:

approvals

Speichert sensible Anfragen und deren Überprüfungslebenszyklus.

Wichtige Felder umfassen:

requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

executed_at

audit_events

Speichert Sicherheitsentscheidungen und Ausführungskontext.

Wichtige Felder umfassen:

identity
action
decision
required_scope
reason
approval_id
metadata
created_at

Row Level Security ist für beide Tabellen aktiviert.

Es werden keine öffentlichen Browserrichtlinien erstellt.

Vertrauenswürdige AgentGuard-Serverkomponenten greifen mit server-only-Anmeldeinformationen auf die Datenbank zu.

Siehe:

database/schema.sql

Lokale Einrichtung

Voraussetzungen

• Python 3.10+

• Auth0-Tenant

• Supabase-Projekt

• Auth0 Machine-to-Machine-Anwendungen

• Auth0-API, die für die MCP-Ressource konfiguriert ist

Klonen

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

Virtuelle Umgebung erstellen

Windows:

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

macOS/Linux:

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

Abhängigkeiten installieren

Mit Poetry:

pip install poetry
poetry install

Oder installieren Sie die erforderlichen Abhängigkeiten manuell, falls bevorzugt.

Umgebung konfigurieren

Kopieren:

.env.example

nach:

.env

und konfigurieren Sie Ihre eigenen Anmeldeinformationen.

.env niemals committen.

Erforderliche Umgebungsvariablen

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=

Auth0-API-Berechtigungen

Die AgentGuard-API definiert derzeit Berechtigungen, einschließlich:

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

Machine-to-Machine-Anwendungen sollten nur die Berechtigungen erhalten, die für ihre Rolle erforderlich sind.

MCP-Server ausführen

Vom Repository-Stammverzeichnis:

python -m src.server

Standard-Server:

http://localhost:3001/

MCP-Endpunkt:

http://localhost:3001/mcp

Metadaten der geschützten Ressource:

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

Testen mit MCP Inspector

Starten Sie den MCP Inspector:

npx -y @modelcontextprotocol/inspector

Verbinden mit:

Transport:
Streamable HTTP

URL:
http://localhost:3001/mcp

Verwenden Sie ein Auth0 Machine-to-Machine-Zugriffstoken im Autorisierungsheader:

Authorization: Bearer <ACCESS_TOKEN>

Committen oder exponieren Sie keine Zugriffstokens.

Frontend

Die begleitende AgentGuard-Produktoberfläche ist hier verfügbar:

Repository

https://github.com/haisamar/agentguard

Live-Demo

https://agentguard-eight.vercel.app

Es bietet:

• öffentliche Produktseite

• bereinigte öffentliche Sicherheitsdemo

• Auth0-geschütztes Administrator-Dashboard

• menschliche Genehmigen/Ablehnen-Steuerungen

• Visualisierung von Maschinen- vs. Menschenidentität

• Autorisierungs-Trace-Explorer

• interaktive Sicherheitsereignis-Inspektion

• Genehmigungsverlauf

Technologie

AgentGuard kombiniert:

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

Designprinzip

AgentGuard basiert auf einer einfachen Idee:

Ein KI-Agent, der authentifiziert ist, sollte nicht bedeuten, dass er unbegrenzte Autorität hat.

Authentifizierung beweist, wer der Agent ist.

OAuth-Scopes bestimmen, welche Kategorie von Aktionen er anfordern darf.

Kontextuelle Richtlinie bestimmt, ob diese spezifische Aktion autonom ausgeführt werden kann.

Menschliche Genehmigung bietet eine separate Identitätsgrenze für risikoreiche Entscheidungen.

Aktueller Umfang

AgentGuard ist ein Portfolio-Sicherheitsprototyp und keine Produktions-IAM-Plattform.

Aktuelle Einschränkungen umfassen bewusst:

• Demo-Richtlinienregeln sind im Code definiert

• Maschinenidentitäten sind Demo-Rollen zugeordnet

• Das MCP-Backend ist für kontrollierte/lokale Bereitstellung ausgelegt

• Die menschliche Admin-Autorisierung verwendet derzeit eine Administrator-Allowlist auf Anwendungsebene

• Richtlinienverwaltung ist noch nicht über eine Control Plane verfügbar

• Unveränderlichkeit von Audit-Ereignissen ist nicht auf Datenbankebene erzwungen

• Verteiltes Sperren für gleichzeitige Ausführung liegt außerhalb des aktuellen Demo-Umfangs

Diese Grenzen sind bewusst dokumentiert und nicht versteckt.

Mögliche Erweiterungen

Zukünftige Versionen könnten hinzufügen:

• Auth0-rollenbasierte menschliche Administration

• Policy-as-Code

• Richtlinienversionierung

• Agenten-Identitätsregister

• Workload-Identitätsföderation

• delegierte Autorisierung

• zeitlich begrenzte Genehmigungen

• Ressourcenebenen-Autorisierung

• Genehmigungsablauf

• Organisationsweite Isolierung

• signierte Audit-Ereignisse

• SIEM-Export

• Richtliniensimulation

• Produktions-MCP-Bereitstellung

• zusätzliche MCP-Tools und Ressourcenserver

Verwandtes Projekt

AgentGuard-Frontend:

https://github.com/haisamar/agentguard