CISA M365 MCP Server

CISA M365 MCP Server

A Model Context Protocol (MCP) server implementing CISA Binding Operational Directive 25-01 security controls for Microsoft 365 (Azure AD/Entra ID).

Table of Contents

• Overview
• Security Controls
• Architecture
• Prerequisites
• Installation
• Configuration
• Usage
• API Reference
• Error Handling
• Testing
• Security Considerations
• Contributing
• License

Overview

This MCP server provides tools for configuring and managing Microsoft 365 security settings in accordance with BOD 25-01 requirements. It integrates with Microsoft Graph API to enforce security controls, monitor compliance, and provide detailed reporting.

Key Features

• Legacy authentication controls
• Risk-based access controls
• Multi-factor authentication management
• Application registration and consent controls
• Password policy management
• Privileged role management
• Cloud-only account enforcement
• PAM system integration
• Comprehensive compliance reporting
• Token-based authentication
• Type-safe argument validation
• Detailed error handling and logging

Security Controls

MS.AAD.1.1v1

Due Date: 06/20/2025

Block legacy authentication:

• Disables legacy authentication protocols
• Reduces attack surface
• Improves security posture

Implementation details:

await graphClient
  .api('/policies/authenticationMethodsPolicy')
  .patch({
    allowLegacyAuthentication: false,
    blockLegacyAuthenticationMethods: true,
  });

MS.AAD.2.1v1 & MS.AAD.2.3v1

Due Date: 06/20/2025

Block high-risk users and sign-ins:

• Blocks users detected as high risk
• Blocks sign-ins detected as high risk
• Leverages Microsoft's threat intelligence

Implementation details:

await graphClient
  .api('/policies/identitySecurityDefaultsEnforcementPolicy')
  .patch({
    blockHighRiskUsers: true,
    riskLevelForBlocking: 'high',
  });

MS.AAD.3.1v1, MS.AAD.3.2v1, MS.AAD.3.3v1

Due Date: 06/20/2025

MFA configuration:

• Enforces phishing-resistant MFA
• Configures alternative MFA methods
• Shows login context in Microsoft Authenticator

Implementation details:

await graphClient
  .api('/policies/authenticationMethodsPolicy')
  .patch({
    policies: {
      fido2: {
        isEnabled: true,
        isSelfServiceRegistrationAllowed: true,
      },
      windowsHelloForBusiness: {
        isEnabled: true,
        isSelfServiceRegistrationAllowed: true,
      },
    },
  });

MS.AAD.5.1v1, MS.AAD.5.2v1, MS.AAD.5.3v1, MS.AAD.5.4v1

Due Date: 06/20/2025

Application controls:

• Restricts app registration to admins
• Restricts app consent to admins
• Configures admin consent workflow
• Blocks group owner consent

Implementation details:

await graphClient
  .api('/policies/applicationRegistrationManagement')
  .patch({
    restrictAppRegistration: true,
    restrictNonAdminUsers: true,
  });

MS.AAD.6.1v1

Due Date: 06/20/2025

Password policy:

• Disables password expiration
• Follows modern security best practices

Implementation details:

await graphClient
  .api('/policies/passwordPolicy')
  .patch({
    passwordExpirationPolicy: {
      passwordExpirationDays: 0,
      neverExpire: true,
    },
  });

MS.AAD.7.1v1 through MS.AAD.7.8v1

Due Date: 06/20/2025

Privileged role management:

• Limits Global Administrator count
• Enforces granular roles
• Requires cloud-only accounts
• Enforces PAM system usage
• Configures approval workflows
• Sets up alerting

Implementation details:

await graphClient
  .api('/policies/roleManagementPolicies')
  .patch({
    enforceGranularRoles: true,
    blockGlobalAdminForGeneralUse: true,
    requireApprovalForGlobalAdmin: true,
  });

Architecture

Components

1. Server Class

   • Handles MCP protocol implementation
   • Manages tool registration and execution
   • Implements error handling and logging

2. Authentication

   • Token-based authentication with Microsoft Graph API
   • Automatic token refresh
   • Secure credential management

3. Graph Client

   • Wrapper around Microsoft Graph API
   • Type-safe request/response handling
   • Retry logic and error handling

4. Tools

   • Legacy authentication control
   • Risk-based access management
   • MFA configuration
   • Application control
   • Password policy management
   • Role management
   • Alert configuration
   • Policy status reporting

Data Flow

graph TD
    A[MCP Client] -->|Request| B[MCP Server]
    B -->|Authentication| C[Token Manager]
    C -->|Access Token| D[Graph Client]
    D -->|API Calls| E[Microsoft Graph]
    E -->|Response| D
    D -->|Results| B
    B -->|Response| A

Prerequisites

• Node.js 18.x or higher
• Microsoft 365 tenant with admin access
• Azure AD application with required permissions:
  • Policy.ReadWrite.All
  • RoleManagement.ReadWrite.All
  • User.Read.All
  • Application.ReadWrite.All

Installation

Installing via Smithery

To install CISA M365 MCP Server automatically via Smithery:

npx -y @smithery/cli install cisa-m365

You can also directly copy the MCP settings and definitions from Smithery Protocol Directory and add the MCP server to your Claude or LLM setup that supports MCP protocol.

1. Clone the repository:

git clone https://github.com/DynamicEndpoints/BOD-25-01-CSA-MCP.git
cd cisa-m365

2. Install dependencies:

npm install

3. Build the server:

npm run build

Configuration

1. Create Azure AD application:

   • Navigate to Azure Portal > Azure Active Directory
   • Register a new application
   • Add required API permissions
   • Create a client secret

2. Configure environment variables:

cp .env.example .env

Edit .env file:

TENANT_ID=your-tenant-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret

3. Configure MCP settings:

{
  "mcpServers": {
    "cisa-m365": {
      "command": "node",
      "args": ["path/to/cisa-m365/build/index.js"],
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Usage

Available Tools

block_legacy_auth

Block legacy authentication methods.

{}

block_high_risk_users

Block users detected as high risk.

{}

enforce_phishing_resistant_mfa

Enforce phishing-resistant MFA for all users.

{}

configure_global_admins

Configure Global Administrator role assignments.

{
  "userIds": ["user1-id", "user2-id"]
}

get_policy_status

Get current status of all security policies.

{}

Example Usage

// Block legacy authentication
const result = await client.callTool('block_legacy_auth', {});

// Get policy status
const status = await client.callTool('get_policy_status', {});

API Reference

Policy Settings API

interface PolicySettings {
  legacyAuthentication: {
    blocked: boolean;
    compliant: boolean;
  };
  highRiskUsers: {
    blocked: boolean;
    compliant: boolean;
  };
  mfa: {
    phishingResistant: boolean;
    alternativeEnabled: boolean;
    compliant: boolean;
  };
  applications: {
    registrationRestricted: boolean;
    consentRestricted: boolean;
    compliant: boolean;
  };
  passwords: {
    expirationDisabled: boolean;
    compliant: boolean;
  };
  roles: {
    globalAdminCount: number;
    granularRolesEnforced: boolean;
    pamEnforced: boolean;
    compliant: boolean;
  };
}

Error Handling

The server implements comprehensive error handling:

1. Authentication Errors

   • Token acquisition failures
   • Permission issues
   • Tenant configuration problems

2. API Errors

   • Graph API request failures
   • Rate limiting
   • Service unavailability

3. Validation Errors

   • Invalid arguments
   • Missing required parameters
   • Type mismatches

4. Runtime Errors

   • Network issues
   • Timeout problems
   • Resource constraints

Example error response:

{
  "error": {
    "code": "InvalidParams",
    "message": "Invalid role assignment arguments",
    "details": {
      "parameter": "userIds",
      "constraint": "Must have between 2 and 8 users",
      "received": "1 user"
    }
  }
}

Testing

1. Run unit tests:

npm test

2. Run integration tests:

npm run test:integration

3. Run compliance tests:

npm run test:compliance

Security Considerations

1. Authentication

   • Use secure token storage
   • Implement token rotation
   • Monitor for suspicious activity

2. API Access

   • Follow least privilege principle
   • Regular permission audits
   • Monitor API usage

3. Data Protection

   • No sensitive data logging
   • Secure configuration storage
   • Regular security scans

4. Compliance

   • Regular compliance checks
   • Automated policy verification
   • Audit logging

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

Guidelines:

• Follow existing code style
• Add tests for new features
• Update documentation
• Keep commits atomic

License

MIT