Drafts und Audit

Synit AD MCP kann optional Request-Entwürfe für ADProxy in Enterprise Active Directory (AD) vorbereiten. Diese Funktion bleibt ohne Seiteneffekte: MCP schreibt nicht, erstellt keinen Plan und wendet nichts an.

Mutation-Drafts für ADProxy vorbereiten

Wenn draft_mutation_request aktiviert ist, kann ein Agent strukturierte Operationen übergeben. MCP gibt einen Body zurück, der für POST /api/v1/mutations/plan gedacht ist.

Der Entwurf enthält:

• method: "POST"
• path: "/api/v1/mutations/plan"
• body mit Operationen
• executes: false
• plan_created: false
• Hinweis, dass der Body außerhalb von MCP geprüft und eingereicht werden muss

Beispiel:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "draft_mutation_request",
    "arguments": {
      "operations": [
        {
          "id": "set_description",
          "operation_type": "modify_attributes",
          "target_dn": "CN=Jane Doe,OU=Users,DC=example,DC=test",
          "object_class": "user",
          "attributes": {
            "description": "Updated by reviewed automation"
          }
        }
      ]
    }
  }
}

Beispielantwort:

{
  "valid": true,
  "method": "POST",
  "path": "/api/v1/mutations/plan",
  "body": {
    "source": "mcp-draft",
    "response_detail": "standard",
    "operations": [
      {
        "id": "set_description",
        "operation_type": "modify_attributes",
        "target": {
          "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
        },
        "object_class": "user",
        "attributes": {
          "description": "Updated by reviewed automation"
        }
      }
    ]
  },
  "executes": false,
  "plan_created": false,
  "requires_user_submission": true,
  "schema_status": {
    "api_schema_available": true,
    "ad_schema_available": true
  },
  "next_step": "Submit this body to POST /api/v1/mutations/plan outside MCP, review the plan, then use the normal approved HTTP apply flow if appropriate.",
  "errors": [],
  "warnings": [
    {
      "field": "$",
      "message": "HTTP plan submission remains authoritative for live AD state, policy, dependency graph, conflict, and apply-time validation",
      "code": "PLAN_VALIDATION_REQUIRED"
    }
  ]
}

Danach gilt:

• Nur das zurückgegebene body-Objekt wird an ADProxy HTTP /api/v1/mutations/plan übergeben.
• Der Plan wird normal geprüft.
• Ein Mensch oder eine freigegebene Automation bewertet den Plan.
• Apply läuft außerhalb von MCP über ADProxy HTTP mit passender Freigabe.

Was Drafts bewusst nicht tun

Kein HTTP Call. Keine Plan-Erstellung. Kein Apply. Kein Resume. Keine versteckten Active-Directory-Schreiboperationen. Keine Passwörter oder Secret Outputs. Keine force-, risk- oder show_secret_outputs-Freigaben. Keine Resume-Operation.

Ablauf mit Agent und ADProxy

Agent ruft tools/list auf. Agent sammelt Kontext über get_schema, get_attribute, lookup_object oder get_object. Agent ruft draft_mutation_request mit strukturierter Operation auf. MCP gibt einen Entwurf zurück. Nur das Feld body wird an POST /api/v1/mutations/plan übergeben. Der Plan wird geprüft und fachlich bewertet. Eine freigegebene HTTP-Integration führt POST /api/v1/mutations/apply aus.

Plan-Submission außerhalb von MCP:

curl -sS -X POST https://adproxy.example.test/api/v1/mutations/plan \
  -H "Authorization: Bearer <review-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "mcp-draft",
    "actor": "external-agent",
    "response_detail": "standard",
    "operations": [
      {
        "id": "set_description",
        "operation_type": "modify_attributes",
        "target": {
          "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
        },
        "object_class": "user",
        "attributes": {
          "description": "Updated by reviewed automation"
        }
      }
    ]
  }'

Apply bleibt ein separater Schritt:

curl -sS -X POST https://adproxy.example.test/api/v1/mutations/apply \
  -H "Authorization: Bearer <write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "<reviewed-plan-id>",
    "actor": "approved-workflow"
  }'

Ungültiges Draft-Beispiel

draft_mutation_request akzeptiert nur ADProxy Operationen. Patch-Verben wie replace sind nicht gültig:

{
  "operations": [
    {
      "id": "bad",
      "operation_type": "replace",
      "target": {
        "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      },
      "attributes": {
        "description": "new value"
      }
    }
  ]
}

Korrekt ist:

{
  "operations": [
    {
      "id": "set_description",
      "operation_type": "modify_attributes",
      "target": {
        "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      },
      "object_class": "user",
      "attributes": {
        "description": "new value"
      }
    }
  ]
}

MCP-Audit

MCP-Audit kann JSONL-Ereignisse für JSON-RPC Requests, Tool Calls, Antworten und Transport-Metadaten schreiben.

Konfiguration:

mcp {
  audit {
    enabled      = true
    file_enabled = true
    file_path    = "/var/log/adproxy/mcp-audit.jsonl"
    audit_level  = "info"
  }
}

Optional zusätzlich Syslog:

mcp {
  audit {
    enabled      = true
    file_enabled = true
    file_path    = "/var/log/adproxy/mcp-audit.jsonl"
    audit_level  = "info"

    syslog {
      enabled         = true
      server          = "tls://mcp-syslog.example.test:6514"
      facility        = "local0"
      app_name        = "adproxy-mcp-audit"
      connect_timeout = "2s"
      write_timeout   = "500ms"
      ca_file         = "/etc/adproxy/syslog-ca.pem"
      server_name     = "mcp-syslog.example.test"
    }
  }
}

Typische Audit-Felder:

Zeitstempel, Transport, Session-ID, Tool-Name, Argumente, Outcome, Dauer, Fehler, redigierte MCP-Antwort.

Authorization wird nicht geloggt. Sensible Active-Directory-Attribute und Secret-ähnliche Felder werden redigiert.

Beispiel für ein Audit-Ereignis

{
  "audit_schema_version": 1,
  "event_type": "mcp_request",
  "level": "info",
  "transport": "streamable-http",
  "session_id": "<session-id>",
  "method": "tools/call",
  "action": {
    "name": "get_object",
    "arguments": {
      "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
    }
  },
  "outcome": "success"
}

Audit kann später gefiltert werden, zum Beispiel nach Tool Calls oder Fehlern:

jq -c 'select(.method=="tools/call") | {time:.timestamp, tool:.action.name, outcome:.outcome}' /var/log/adproxy/mcp-audit.jsonl

jq -c 'select(.outcome=="error") | {time:.timestamp, method:.method, error:.error}' /var/log/adproxy/mcp-audit.jsonl

Praxis für sichere Drafts

MCP nur mit read-only Active-Directory-Zweck einsetzen. Drafts nur aktivieren, wenn der HTTP-Review-Prozess klar ist. MCP-Audit für produktive Agenten- oder Toolnutzung aktivieren. Proxy-Header nur als Hinweise behandeln und Vertrauen am Proxy-Rand regeln. Schreibende Active-Directory-Aktionen ausschließlich über ADProxy HTTP freigeben.