SurePassID Compliance Manager User Guide

SurePassID Authentication Server

SurePassID Compliance Monitoring - AI Agent Integration Guide

Version: 2.0.0 Date: 2025-07-11 Project: SurePassID.Compliance.Agent.Tools

Overview

The SurePassID.Compliance.Agent.Tools library exposes compliance monitoring as tool definitions that AI agents can invoke. It provides:

ComplianceTools -- A static class that emits MCP-style JSON Schema tool definitions.
IToolExecutor / ComplianceToolExecutor -- Receives a tool name + JSON parameters, executes the compliance operation, and returns structured JSON.

The library is a thin wrapper. It calls the same IComplianceRunner.RunAsync() entrypoint used by the CLI and Windows Service.

This guide provides exact, step-by-step instructions for wiring these tools into specific AI systems.

Architecture

AI Agent / LLM
    |
    | Tool call: { name: "run_compliance_check", args: { lookbackHours: 48 } }
    |
    v
+-- Integration Host (you build this) -----------+
|                                                |
|   Translates between the AI framework's        |
|   tool-calling protocol and IToolExecutor      |
|                                                |
+------------------------------------------------+
    |
    | IToolExecutor.ExecuteAsync("run_compliance_check", params)
    |
    v
+-- SurePassID.Compliance.Agent.Tools ------------+
|   ComplianceToolExecutor                        |
|   Routes to handler -> calls core libraries     |
+-------------------------------------------------+
    |
    v
+-- Core Libraries (Runner, Events, Identity) ----+
|   IComplianceRunner, IAuthEventSource,          |
|   IIdentityProvider, ICorrelationEngine         |
+-------------------------------------------------+
    |
    v
  AD / SurePassID / Entra ID / Syslog / JSON files

The "Integration Host" is the piece you create. It varies by AI framework. The sections below show exactly how to build it for each one.

Available Tools

Nine tools are defined in ComplianceTools.GetToolDefinitions(). Call ComplianceTools.ToJson() to get the full JSON Schema.

Tool Name	Required Params	Description
`run_compliance_check`	(none)	Full CMMC 2.0 / HIPAA compliance check
`get_compliance_status`	(none)	Current status and active alerts
`list_privileged_users`	(none)	Members of privileged AD groups
`get_user_auth_history`	`username`	Auth history for a specific user
`get_sfa_violations`	(none)	SFA violations for privileged users
`get_privilege_drift`	(none)	Changes in privileged group membership
`generate_compliance_report`	`reportType`	Formal audit-ready report
`acknowledge_alert`	`alertId`	Acknowledge a compliance alert
`get_monitoring_statistics`	(none)	Real-time monitoring metrics

To inspect the full schema at any time:

Console.WriteLine(ComplianceTools.ToJson(indented: true));

Integration Method 1: MCP Server

Targets: GitHub Copilot (VS Code / Visual Studio), Claude Desktop, Cursor, any MCP client.

MCP (Model Context Protocol) uses a stdio-based JSON-RPC transport. The solution includes a pre-built MCP server at src/SurePassID.Compliance.McpServer -- no assembly required.

The server uses the official ModelContextProtocol NuGet package (v1.2.0) and registers all nine compliance tools via [McpServerTool] attributes. It reads configuration from appsettings.json and COMPLIANCE_ environment variables, then communicates over stdin/stdout.

Project structure

src/SurePassID.Compliance.McpServer/
  Program.cs                 # Host setup: config, DI, stdio transport
  ComplianceMcpTools.cs      # 9 tools with [McpServerTool] attributes
  appsettings.json           # Template configuration
  SurePassID.Compliance.McpServer.csproj

Step 1: Configure credentials

Edit src/SurePassID.Compliance.McpServer/appsettings.json with your SurePassID and/or Active Directory credentials, or pass them as environment variables (shown in Steps 3-5).

The MCP server supports the same multi-source event configuration as the CLI and Service:

{
  "EventSources": {
    "SurePassID": { "Enabled": true },
    "WindowsEventLog": { "Enabled": false },
    "JsonFile": { "Enabled": false }
  },
  "MfaCoverage": {
    "Enabled": true,
    "TimeWindowMinutes": 5,
    "RequireIpMatch": false,
    "EnableFindUserLookup": true,
    "PrivilegedUsersOnly": true
  }
}

When both Windows Event Log and SurePassID are enabled, the MFA coverage correlator automatically matches Windows SFA logons to SurePassID MFA events.

A commented template with all options is available at appsettings.template.jsonc.

Step 2: Build

dotnet build src/SurePassID.Compliance.McpServer

# For deployment to another machine:
dotnet publish src/SurePassID.Compliance.McpServer -c Release -o ./publish

Step 3: Register with GitHub Copilot (VS Code)

A .vscode/mcp.json file is already included in the repository. Edit it with your credentials:

{
  "servers": {
    "surepassid-compliance": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "src/SurePassID.Compliance.McpServer/SurePassID.Compliance.McpServer.csproj", "--no-build"],
      "env": {
        "COMPLIANCE_SurePassID__Endpoint": "https://mfa.company.com/api/mfa/v1",
        "COMPLIANCE_SurePassID__ApiKeyId": "your-api-key-id",
        "COMPLIANCE_SurePassID__ApiKey": "your-api-key",
        "COMPLIANCE_ActiveDirectory__Server": "dc01.company.com",
        "COMPLIANCE_ActiveDirectory__BaseDn": "DC=company,DC=com"
      }
    }
  }
}

Then in VS Code:

Build the project first: dotnet build src/SurePassID.Compliance.McpServer
Open the Copilot Chat panel.
The compliance tools appear automatically. Copilot invokes them when you ask compliance questions.

Step 4: Register with Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "surepassid-compliance": {
      "command": "C:/path/to/publish/SurePassID.Compliance.McpServer.exe",
      "env": {
        "COMPLIANCE_SurePassID__Endpoint": "https://mfa.company.com/api/mfa/v1",
        "COMPLIANCE_SurePassID__ApiKeyId": "your-api-key-id",
        "COMPLIANCE_SurePassID__ApiKey": "your-api-key",
        "COMPLIANCE_ActiveDirectory__Server": "dc01.company.com",
        "COMPLIANCE_ActiveDirectory__BaseDn": "DC=company,DC=com"
      }
    }
  }
}

Restart Claude Desktop. The compliance tools appear in the tools menu.

Step 5: Register with Visual Studio

Create or edit .vs/mcp.json in your solution root:

{
  "servers": {
    "surepassid-compliance": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "src/SurePassID.Compliance.McpServer/SurePassID.Compliance.McpServer.csproj", "--no-build"],
      "env": {
        "COMPLIANCE_SurePassID__Endpoint": "https://mfa.company.com/api/mfa/v1",
        "COMPLIANCE_SurePassID__ApiKeyId": "your-api-key-id",
        "COMPLIANCE_SurePassID__ApiKey": "your-api-key",
        "COMPLIANCE_ActiveDirectory__Server": "dc01.company.com",
        "COMPLIANCE_ActiveDirectory__BaseDn": "DC=company,DC=com"
      }
    }
  }
}

Integration Method 2: OpenAI Function Calling

Targets: ChatGPT (via API), GPT-4, GPT-4o, any OpenAI-compatible API.

OpenAI function calling requires you to send tool definitions as part of the chat completion request, then execute the tool when the model returns a tool_calls response.

Step 1: Convert tool definitions to OpenAI format

using SurePassID.Compliance.Agent.Tools;
using System.Text.Json;

// Get the MCP-style definitions
var mcpTools = ComplianceTools.GetToolDefinitions();

// Convert to OpenAI function format
var openAiTools = mcpTools.Select(t => new
{
    type = "function",
    function = new
    {
        name = t.Name,
        description = t.Description,
        parameters = new
        {
            type = t.InputSchema.Type,
            properties = t.InputSchema.Properties.ToDictionary(
                p => p.Key,
                p => new
                {
                    type = p.Value.Type,
                    description = p.Value.Description,
                    @enum = p.Value.Enum,
                    @default = p.Value.Default
                }),
            required = t.InputSchema.Required
        }
    }
}).ToArray();

string openAiToolsJson = JsonSerializer.Serialize(openAiTools,
    new JsonSerializerOptions { WriteIndented = true });

Step 2: Chat completion loop with tool execution

using System.Text.Json;
using OpenAI;
using OpenAI.Chat;
using SurePassID.Compliance.Agent.Tools;

// Set up compliance tool executor (with DI configured as shown in Method 6)
var executor = serviceProvider.GetRequiredService<IToolExecutor>();

// Build the OpenAI client
var client = new ChatClient("gpt-4o", Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

var messages = new List<ChatMessage>
{
    new SystemChatMessage(
        "You are a compliance assistant. Use the provided tools to answer " +
        "questions about CMMC 2.0 and HIPAA MFA compliance status."),
    new UserChatMessage("Are there any SFA violations in the last 24 hours?")
};

// Send request with tool definitions
var options = new ChatCompletionOptions();
foreach (var toolDef in ComplianceTools.GetToolDefinitions())
{
    options.Tools.Add(ChatTool.CreateFunctionTool(
        toolDef.Name,
        toolDef.Description,
        BinaryData.FromString(JsonSerializer.Serialize(toolDef.InputSchema))));
}

var response = await client.CompleteChatAsync(messages, options);

// Handle tool calls
if (response.Value.FinishReason == ChatFinishReason.ToolCalls)
{
    messages.Add(new AssistantChatMessage(response.Value));

    foreach (var toolCall in response.Value.ToolCalls)
    {
        var parameters = string.IsNullOrEmpty(toolCall.FunctionArguments.ToString())
            ? null
            : JsonDocument.Parse(toolCall.FunctionArguments.ToString());

        var result = await executor.ExecuteAsync(toolCall.FunctionName, parameters);

        messages.Add(new ToolChatMessage(toolCall.Id, result.Output ?? result.Error ?? ""));
    }

    // Get final response
    var finalResponse = await client.CompleteChatAsync(messages, options);
    Console.WriteLine(finalResponse.Value.Content[0].Text);
}

Integration Method 3: Microsoft Semantic Kernel

Targets: Any application using Microsoft.SemanticKernel (Azure OpenAI, OpenAI, local models).

Semantic Kernel uses "plugins" with KernelFunction attributes. You create a plugin class that wraps IToolExecutor.

Step 1: Add packages

dotnet add package Microsoft.SemanticKernel --version 1.*

Step 2: Create the plugin class

using Microsoft.SemanticKernel;
using SurePassID.Compliance.Agent.Tools;
using System.ComponentModel;
using System.Text.Json;

public class CompliancePlugin
{
    private readonly IToolExecutor _executor;

    public CompliancePlugin(IToolExecutor executor)
    {
        _executor = executor;
    }

    [KernelFunction("run_compliance_check")]
    [Description("Run a CMMC 2.0 and HIPAA compliance check against authentication events")]
    public async Task<string> RunComplianceCheckAsync(
        [Description("Hours to look back (default: 24)")] int lookbackHours = 24,
        [Description("Generate evidence pack")] bool generateEvidencePack = false)
    {
        var parameters = JsonDocument.Parse(JsonSerializer.Serialize(
            new { lookbackHours, generateEvidencePack }));
        var result = await _executor.ExecuteAsync("run_compliance_check", parameters);
        return result.Output ?? result.Error ?? "";
    }

    [KernelFunction("get_compliance_status")]
    [Description("Get current compliance status and active alerts")]
    public async Task<string> GetComplianceStatusAsync(
        [Description("Include active alerts")] bool includeAlerts = true)
    {
        var parameters = JsonDocument.Parse(JsonSerializer.Serialize(
            new { includeAlerts }));
        var result = await _executor.ExecuteAsync("get_compliance_status", parameters);
        return result.Output ?? result.Error ?? "";
    }

    [KernelFunction("get_sfa_violations")]
    [Description("Get SFA violations for privileged users (CMMC IA.L2-3.5.3)")]
    public async Task<string> GetSfaViolationsAsync(
        [Description("Hours to look back (default: 24)")] int lookbackHours = 24)
    {
        var parameters = JsonDocument.Parse(JsonSerializer.Serialize(
            new { lookbackHours }));
        var result = await _executor.ExecuteAsync("get_sfa_violations", parameters);
        return result.Output ?? result.Error ?? "";
    }

    [KernelFunction("get_user_auth_history")]
    [Description("Get authentication history for a specific user")]
    public async Task<string> GetUserAuthHistoryAsync(
        [Description("Username (samAccountName, UPN, or email)")] string username,
        [Description("Hours to look back (default: 168)")] int lookbackHours = 168)
    {
        var parameters = JsonDocument.Parse(JsonSerializer.Serialize(
            new { username, lookbackHours }));
        var result = await _executor.ExecuteAsync("get_user_auth_history", parameters);
        return result.Output ?? result.Error ?? "";
    }

    [KernelFunction("list_privileged_users")]
    [Description("List members of privileged Active Directory groups")]
    public async Task<string> ListPrivilegedUsersAsync()
    {
        var result = await _executor.ExecuteAsync("list_privileged_users", null);
        return result.Output ?? result.Error ?? "";
    }
}

Step 3: Register and use with Semantic Kernel

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

// Build kernel
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddAzureOpenAIChatCompletion(
    "gpt-4o",
    "https://your-resource.openai.azure.com",
    "your-api-key");

var kernel = kernelBuilder.Build();

// Register compliance plugin (executor comes from DI)
var executor = serviceProvider.GetRequiredService<IToolExecutor>();
kernel.Plugins.AddFromObject(new CompliancePlugin(executor), "compliance");

// Enable automatic function calling
var settings = new OpenAIPromptExecutionSettings
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

// Chat
var response = await kernel.InvokePromptAsync(
    "Are there any SFA violations for privileged users today?",
    new KernelArguments(settings));

Console.WriteLine(response);

Integration Method 4: LangChain (.NET)

Targets: LangChain for .NET projects.

Step 1: Create tool wrappers

using LangChain.Abstractions.Schema;
using LangChain.Providers;

public class ComplianceLangChainTool : ITool
{
    private readonly IToolExecutor _executor;
    private readonly string _toolName;

    public string Name { get; }
    public string Description { get; }

    public ComplianceLangChainTool(
        IToolExecutor executor, string toolName, string description)
    {
        _executor = executor;
        _toolName = toolName;
        Name = toolName;
        Description = description;
    }

    public async Task<string> InvokeAsync(string input, CancellationToken ct = default)
    {
        var parameters = string.IsNullOrWhiteSpace(input)
            ? null
            : JsonDocument.Parse(input);
        var result = await _executor.ExecuteAsync(_toolName, parameters, ct);
        return result.Output ?? result.Error ?? "";
    }
}

// Create all tools from definitions
public static IEnumerable<ITool> CreateLangChainTools(IToolExecutor executor)
{
    return ComplianceTools.GetToolDefinitions()
        .Select(d => new ComplianceLangChainTool(executor, d.Name, d.Description));
}

Integration Method 5: CLI Pipe / Shell Agent

Targets: Bash scripts, PowerShell automation, any agent that can execute shell commands and parse JSON.

No .NET hosting required. Use the existing compliance-cli with --quiet mode.

Using the CLI as a tool

The CLI --quiet flag outputs machine-readable JSON to stdout:

# Run compliance check, get JSON output
compliance-cli run --quiet --lookback 24 --groups "Domain Admins"

Output:

{"success":true,"runId":"8a2f3b4c-...","privilegedUsers":23,"eventsIngested":1250,"mfaCompliant":false,"sfaEvents":2,"mfaEvents":1248}

Exit codes:

Code	Meaning
0	Compliant
1	Error
2	Non-compliant (SFA detected)

Python agent example (subprocess)

import subprocess
import json

def run_compliance_check(lookback_hours=24, groups=None):
    cmd = ["compliance-cli", "run", "--quiet", "--lookback", str(lookback_hours)]
    if groups:
        for g in groups:
            cmd.extend(["--groups", g])
    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

# Use with any Python AI framework
status = run_compliance_check(lookback_hours=48)
print(f"Compliant: {status['mfaCompliant']}, SFA Events: {status['sfaEvents']}")

PowerShell agent example

function Invoke-ComplianceCheck {
    param([int]$LookbackHours = 24)
    $output = & compliance-cli run --quiet --lookback $LookbackHours 2>&1
    return ($output | ConvertFrom-Json)
}

$result = Invoke-ComplianceCheck -LookbackHours 48
if (-not $result.mfaCompliant) {
    Write-Warning "SFA violations detected: $($result.sfaEvents)"
}

Integration Method 6: Custom .NET Host

Targets: Custom applications, REST APIs, background services, Blazor apps.

This is the foundational pattern. All other integration methods build on top of this DI setup.

Step 1: Add project references

<ItemGroup>
  <ProjectReference Include="..\SurePassID.Compliance.Agent.Tools\..." />
  <ProjectReference Include="..\SurePassID.Compliance.Runner\..." />
  <ProjectReference Include="..\SurePassID.Compliance.Events.RestApi\..." />
  <ProjectReference Include="..\SurePassID.Compliance.Identity.ActiveDirectory\..." />
</ItemGroup>

Step 2: Configure DI and execute tools

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using SurePassID.Compliance.Agent.Tools;
using SurePassID.Compliance.Events.RestApi;
using SurePassID.Compliance.Identity.ActiveDirectory;
using SurePassID.Compliance.Runner;
using System.Text.Json;

// 1. Build services
var services = new ServiceCollection();

services.AddLogging(b => b.AddConsole().SetMinimumLevel(LogLevel.Warning));

services.AddSurePassIdRestApiEventSource(options =>
{
    options.Endpoint = "https://mfa.company.com/api/mfa/v1";
    options.ApiKeyId = "your-api-key-id";
    options.ApiKey = "your-api-key";
    options.IgnoreSyncStatus = true;
    options.PreferJsonBulkFormat = true;
});

services.AddActiveDirectoryIdentityProvider(options =>
{
    options.Server = "dc01.company.com";
    options.BaseDn = "DC=company,DC=com";
    options.UseIntegratedAuth = true;
});

services.AddComplianceRunner();
services.AddComplianceAgentTools();

var serviceProvider = services.BuildServiceProvider();

// 2. Get the executor
var executor = serviceProvider.GetRequiredService<IToolExecutor>();

// 3. List available tools
foreach (var tool in executor.GetAvailableTools())
{
    Console.WriteLine($"  {tool.Name}: {tool.Description}");
}

// 4. Execute a tool
var parameters = JsonDocument.Parse("""{ "lookbackHours": 48 }""");
var result = await executor.ExecuteAsync("run_compliance_check", parameters);

if (result.Success)
{
    Console.WriteLine(result.Output);
}
else
{
    Console.Error.WriteLine($"Error: {result.Error}");
}

Step 3: Expose as a REST API (optional)

// In a minimal API or controller
app.MapPost("/api/tools/{toolName}", async (
    string toolName,
    JsonDocument? body,
    IToolExecutor executor) =>
{
    var result = await executor.ExecuteAsync(toolName, body);
    return result.Success
        ? Results.Ok(result.Data)
        : Results.BadRequest(new { error = result.Error });
});

app.MapGet("/api/tools", (IToolExecutor executor) =>
{
    return Results.Ok(executor.GetAvailableTools());
});

Security Model

All integration methods inherit the same security constraints:

Restricted API surface -- The agent can only call the nine defined tools. It cannot query AD, SurePassID, or file systems directly.
Read-only operations -- All tools are read-only except acknowledge_alert (which only updates alert metadata).
Credential isolation -- API keys and AD credentials live in the host configuration, never in tool responses.
Transport security -- TLS 1.2/1.3 enforced for all backend connections.
Audit logging -- Every tool invocation is logged with tool name, timestamp, and parameters.

Credential handling by integration method

Method	Where credentials live
MCP Server	`appsettings.json` or environment variables in `mcp.json`
OpenAI / Semantic Kernel	Host application configuration
CLI Pipe	`appsettings.json` next to the CLI binary
Custom .NET Host	DI configuration (user secrets, env vars, Key Vault)

Never pass SurePassID API keys or AD credentials through the AI model. They must be configured in the host process only.

Configuration Reference

The agent tools use the same appsettings.json as the CLI and Windows Service. Run compliance-cli configure to generate one interactively.

Section	Purpose
`SurePassID`	API credentials, `IgnoreSyncStatus`, `PreferJsonBulkFormat`
`ActiveDirectory`	LDAP server, base DN, auth method
`EventSources`	Which data sources to query
`PrivilegedGroups`	Default groups monitored by tools
`ComplianceService`	Schedule and lookback defaults

Troubleshooting

MCP server not appearing in Copilot

Verify the command path in mcp.json is correct and the binary exists.
Check that environment variables for credentials are set.
Run the MCP server manually to confirm it starts: dotnet run --project SurePassID.Compliance.McpServer
Check the VS Code Output panel (select "GitHub Copilot" or "MCP" channel) for errors.

Tool returns "Compliance runner not available"

The IComplianceRunner was not registered in DI. Ensure services.AddComplianceRunner() is called, along with at least one event source and one identity provider.

Tool returns "Identity provider not available"

No IIdentityProvider is registered. Add either services.AddActiveDirectoryIdentityProvider(...) or services.AddSurePassIdIdentityProvider(...).

JSON format warning in logs

The SurePassID server returned legacy piped format instead of JSON bulk format. Events are still processed, but some fields (SsoIdentity, UserEmail) may be missing. Upgrade the MFA server for full JSON support, or set PreferJsonBulkFormat = false.

FAQ

Q: Do I need to build an MCP server to use the tools? A: No. The MCP server is only needed for GitHub Copilot and Claude Desktop integration. For OpenAI function calling, Semantic Kernel, or custom apps, you call IToolExecutor directly from .NET code.

Q: Can I use multiple integration methods simultaneously? A: Yes. The IToolExecutor is stateless. You can host an MCP server for Copilot, expose a REST API for ChatGPT, and use Semantic Kernel in a Blazor app -- all pointing at the same compliance backend.

Q: Does the AI model see my AD passwords or API keys? A: No. Credentials are configured in the host process. Tool results contain compliance data only -- never credentials.

Q: What if the SurePassID server or AD is unreachable? A: Tool execution returns a structured error: { "success": false, "error": "..." }. The AI agent can relay this message to the user.

Q: Is the agent integration required to use the compliance system? A: No. The CLI, Windows Service, and IComplianceRunner API all work independently without any agent layer.

The software and information contained herein are proprietary to, and comprise valuable trade secrets of, SurePassID Authentication, Inc., which intends to preserve as confidential trade secrets such software and information. Such software and information shall not be reproduced, published, or disclosed to others, or used for any purpose other than that for which it is expressly provided, without the prior written consent of SurePassID Authentication, Inc.

© 2024–2026 SurePassID. All rights reserved. Protected by patents pending. SurePassID, the SurePassID logo and design, and Secure SSO are registered trademarks or trademarks of SurePassID, Corp. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

SurePassID 360 Central Avenue #800 St. Petersburg, FL 33701 USA +1 (888) 200-8144 surepassid.com