framework-mcp
Version:
Dual-architecture server (MCP + HTTP API) for determining vendor tool capability roles against CIS Controls Framework. Supports Microsoft Copilot custom connectors and DigitalOcean App Services deployment.
532 lines (427 loc) ā¢ 20.7 kB
Markdown
# Vendor Framework Analyzer MCP Server
[](https://badge.fury.io/js/framework-mcp)
[](https://creativecommons.org/licenses/by/4.0/)
[](https://github.com/therealcybermattlee/FrameworkMCP)
[](https://cyberrise.org)
A Model Context Protocol (MCP) server that determines vendor tool **capability roles** (Full Implementation, Partial Implementation, Facilitates, Governance, Validates) against the **CIS Controls Framework**. This tool helps security professionals accurately categorize vendor capabilities for specific CIS Control safeguards through comprehensive content-based analysis.
## šÆ Purpose
This MCP server enables security teams to:
- **Determine vendor tool capability roles** for specific CIS Control safeguards (1.1, 5.1, 6.3, etc.)
- **Validate implementation capability claims** through comprehensive content analysis
- **Accurately categorize vendor roles** across 5 capability types: Full, Partial, Facilitates, Governance, and Validates
- **Generate evidence-based assessments** showing capability alignment and confidence scores
## šÆ The 5 Capability Roles
| Capability Role | Description | Assessment Approach |
|-----------------|-------------|--------------------|
| **FULL** | Complete implementation of safeguard requirements | Comprehensive content analysis for complete coverage |
| **PARTIAL** | Limited scope implementation with clear boundaries | Content analysis identifies explicit scope limitations |
| **FACILITATES** | Enhancement capabilities that enable others to implement safeguards better/faster/stronger | Analysis identifies facilitation language and indirect support |
| **GOVERNANCE** | Policy/process management and oversight capabilities | Analysis identifies policy, process, and oversight elements |
| **VALIDATES** | Verification capabilities providing evidence and reporting | Analysis identifies audit, monitoring, and reporting capabilities |
## šØ CIS Controls Framework Integration
The server uses the CIS Controls visual framework with color-coded categorization:
- **š Orange Elements**: Governance requirements that MUST be met
- **š¢ Green Elements**: Core "what" of the safeguard
- **š” Yellow Elements**: Sub-taxonomical components
- **ā« Gray Elements**: Implementation suggestions and methods
## š Installation & Deployment
### Prerequisites
- Node.js 18+
- Claude Code CLI tool (for MCP usage)
- Microsoft Copilot Studio (for custom connector usage)
### Install from npm
```bash
npm install -g framework-mcp
```
### Update to Latest Version
```bash
npm update -g framework-mcp
```
Or reinstall to get the latest version:
```bash
npm uninstall -g framework-mcp
npm install -g framework-mcp
```
### Install from source
```bash
git clone https://github.com/therealcybermattlee/FrameworkMCP.git
cd FrameworkMCP
npm install
npm run build
```
### Cloud Deployment Options
#### Option 1: DigitalOcean App Services
```bash
# Deploy using the included configuration
doctl apps create .do/app.yaml
```
#### Option 2: Railway
```bash
railway login
railway up
```
#### Option 3: Render
Connect your GitHub repository and use:
- **Build Command**: `npm install && npm run build`
- **Start Command**: `npm run start:http`
- **Port**: 8080
#### Option 4: Microsoft Copilot Custom Connector
Deploy to any cloud platform and use the included `swagger.json` for Copilot integration.
## āļø Configuration
### Claude Code MCP Integration
Add to your MCP configuration file (`~/.config/claude-code/mcp.json`):
```json
{
"mcpServers": {
"framework-analyzer": {
"command": "node",
"args": ["/path/to/FrameworkMCP/dist/index.js"],
"env": {}
}
}
}
```
### Microsoft Copilot Custom Connector Setup
#### Step 1: Deploy HTTP API
Deploy the Framework MCP HTTP API to any cloud platform (DigitalOcean, Railway, Render, etc.)
#### Step 2: Create Custom Connector in Copilot Studio
1. Open **Microsoft Copilot Studio**
2. Navigate to **Data** ā **Custom connectors**
3. Click **+ New custom connector** ā **Import from OpenAPI file**
4. Upload the `swagger.json` file from this repository
5. Update the **Host** field to your deployed API URL
6. Save and test the connector
#### Step 3: Configure Connection
1. Create a new connection using your custom connector
2. No authentication required (public API)
3. Test with the `/health` endpoint to verify connectivity
#### Step 4: Create Copilot Actions
In your Copilot, create actions for capability assessment:
**Primary Action - Validate Vendor Capability:**
```
Action: Validate Vendor Mapping
Description: Validate vendor capability claims against CIS Controls through content analysis
Connector: Framework MCP Custom Connector
Operation: validateVendorMapping
Parameters:
- vendor_name: {User provided vendor name}
- safeguard_id: {CIS safeguard ID like "1.1"}
- claimed_capability: {full|partial|facilitates|governance|validates}
- supporting_text: {Vendor response text}
```
**Secondary Action - Analyze Response:**
```
Action: Analyze Vendor Response
Description: Determine appropriate capability role for vendor response
Connector: Framework MCP Custom Connector
Operation: analyzeVendorResponse
Parameters:
- vendor_name: {User provided vendor name}
- safeguard_id: {CIS safeguard ID}
- response_text: {Vendor response to analyze}
```
#### Step 5: Example Copilot Prompts
Once configured, users can interact with your Copilot:
```
"Validate this vendor capability: CrowdStrike Falcon claims FULL coverage for safeguard 1.1 with this response: 'Our platform provides comprehensive enterprise asset inventory with real-time discovery, automated classification, and continuous monitoring of all hardware and software assets.'"
"Analyze this vendor response for safeguard 5.1: Microsoft Entra ID - 'We provide centralized identity management with automated user provisioning, role-based access controls, and integration with all major business applications.'"
"What are the requirements for CIS safeguard 6.3?"
```
### Verify Installation
```bash
# For MCP usage
claude-code "List available CIS Control safeguards"
# For HTTP API usage
curl https://your-api-url.com/health
# For Copilot testing
curl -X POST https://your-api-url.com/api/validate-vendor-mapping \
-H "Content-Type: application/json" \
-d '{"vendor_name":"Test Vendor","safeguard_id":"1.1","claimed_capability":"facilitates","supporting_text":"We provide supplemental asset tracking capabilities that enhance existing inventory systems."}'
```
## š Usage Examples
### Analyze Single Vendor Response
```bash
claude-code "Determine the capability role for this vendor response to safeguard 5.1:
Vendor: SecureIAM Corp
Response: 'Our tool is a full identity provider with comprehensive account management. We maintain detailed user inventories including names, usernames, departments, and access rights. Automated quarterly reviews ensure all accounts are authorized and compliant.'"
```
### Validate Implementation Capability Claims
```bash
claude-code "Validate this implementation capability claim:
Vendor: ComplianceBot
Safeguard: 5.1
Claimed Capability: FULL
Response: 'We provide automated account lifecycle management with real-time inventory tracking and compliance reporting.'"
```
### Analyze Multiple Vendors from File
Create `vendors.csv`:
```csv
vendor,safeguard,response
VendorA,5.1,"Complete IAM solution with policy management and quarterly reviews"
VendorB,5.1,"Basic user directory with manual account tracking"
VendorC,6.3,"MFA enforcement for all external applications with SSO integration"
```
```bash
claude-code "Determine capability roles for the vendor responses in vendors.csv and provide recommendations"
```
### Get Safeguard Details
```bash
claude-code "Show me the detailed breakdown of safeguard 5.1 including all sub-elements"
```
### Validate Vendor Capability Claims
**PRIMARY TOOL**: Validate whether a vendor's stated capability mapping is actually supported by their explanatory text.
```bash
claude-code "Use validate_vendor_mapping with vendor_name 'SecureAssets Corp', safeguard_id '1.1', claimed_capability 'full', and supporting_text 'Our comprehensive asset management platform performs automated discovery of all enterprise devices, maintains detailed hardware and software inventories, tracks ownership and location data, provides real-time asset status monitoring, and includes documented inventory procedures with bi-annual review capabilities.'"
```
## š Sample Output
### Standard Capability Role Analysis Output
```json
{
"vendor": "SecureIAM Corp",
"safeguardId": "5.1",
"safeguardTitle": "Establish and Maintain an Inventory of Accounts",
"capabilityRole": "full",
"additionalRoles": ["governance", "validates"],
"confidence": 87,
"contentAnalysis": {
"implementationLanguage": "strong",
"scopeDefinition": "comprehensive",
"evidenceQuality": "high"
},
"evidenceAnalysis": {
"coreRequirements": 85,
"subElements": 75,
"governance": 90,
"languageConsistency": 88
},
"evidence": [
"comprehensive account management",
"detailed user inventories",
"automated quarterly reviews"
]
}
```
### Primary Validation Tool Output (validate_vendor_mapping)
```json
{
"vendor": "SecureAssets Corp",
"safeguard_id": "1.1",
"safeguard_title": "Establish and Maintain a Detailed Enterprise Asset Inventory",
"claimed_capability": "full",
"validation_status": "SUPPORTED",
"confidence_score": 85,
"evidence_analysis": {
"core_requirements_coverage": 100,
"sub_elements_coverage": 47,
"governance_alignment": 80,
"language_consistency": 90
},
"content_validation": {
"implementation_depth": "comprehensive",
"scope_clarity": "well_defined",
"evidence_strength": "strong",
"capability_aligned": true
},
"gaps_identified": [],
"strengths_identified": [
"High coverage of core requirements and sub-elements",
"Strong implementation language consistency",
"Comprehensive coverage with clear implementation details"
],
"recommendations": [],
"detailed_feedback": "Validation of FULL capability claim: SUPPORTED (85% alignment)\n\nSTRENGTHS:\nā¢ High coverage of core requirements and sub-elements\nā¢ Strong implementation language consistency\nā¢ Comprehensive coverage with clear implementation details\n\nASSESSMENT: The vendor's supporting evidence strongly aligns with their claimed capability."
}
```
### Insufficient Evidence Example Output
```json
{
"vendor": "BasicTracker Pro",
"safeguard_id": "1.1",
"safeguard_title": "Establish and Maintain a Detailed Enterprise Asset Inventory",
"claimed_capability": "full",
"validation_status": "UNSUPPORTED",
"confidence_score": 35,
"evidence_analysis": {
"core_requirements_coverage": 40,
"sub_elements_coverage": 15,
"governance_alignment": 25,
"language_consistency": 60
},
"content_validation": {
"implementation_depth": "limited",
"scope_clarity": "vague",
"evidence_strength": "weak",
"capability_aligned": false
},
"gaps_identified": [
"Insufficient detail on asset tracking capabilities",
"Missing governance and review processes",
"Limited coverage of sub-elements"
],
"strengths_identified": [
"Basic asset visibility mentioned"
],
"recommendations": [
"Provide more detailed implementation specifics",
"Consider repositioning as FACILITATES capability based on limited scope"
],
"detailed_feedback": "Validation of FULL capability claim: UNSUPPORTED (35% alignment)\n\nGAPS IDENTIFIED:\nā¢ Insufficient detail on asset tracking capabilities\nā¢ Missing governance and review processes\nā¢ Limited coverage of sub-elements\n\nASSESSMENT: The vendor's supporting evidence does not adequately support their FULL capability claim. Consider FACILITATES role instead."
}
```
## š§ Available Tools
| Tool | Description |
|------|-------------|
| `validate_vendor_mapping` | **PRIMARY** Validate vendor's claimed capability role against supporting evidence through content analysis |
| `analyze_vendor_response` | Determine vendor tool capability role for specific safeguard |
| `get_safeguard_details` | Get detailed safeguard breakdown |
| `list_available_safeguards` | List all available CIS safeguards |
## š File Formats Supported
### JSON Format
```json
[
{
"name": "VendorName",
"safeguard_id": "5.1",
"response": "Vendor response text..."
}
]
```
### CSV Format
```csv
vendor,safeguard,response
VendorName,5.1,"Response text..."
```
### Text Format
```
Vendor: VendorName - Safeguard: 5.1
Response text here...
Vendor: AnotherVendor - Safeguard: 6.3
Another response...
```
## š Vendor Mapping Validation
The **validate_vendor_mapping** tool provides evidence-based validation of vendor capability claims. This addresses a critical need: vendors often self-assess their capabilities, but practitioners need to verify whether the supporting evidence actually justifies the claimed mapping.
### Validation Criteria
| Capability | Requirements | Validation Thresholds |
|------------|-------------|----------------------|
| **FULL** | Complete implementation within scope | ā„70% core requirements + ā„40% sub-elements |
| **PARTIAL** | Limited scope with clear boundaries | ā„30% core requirements OR some core + ā„20% sub-elements |
| **FACILITATES** | Enables/enhances implementation | Facilitation language present, no direct implementation claims |
| **GOVERNANCE** | Policy/process management | ā„60% governance elements + policy language |
| **VALIDATES** | Evidence collection & reporting | Audit/monitoring/reporting capabilities present |
### Content-Based Validation Approach
**APPROACH**: The validation tool uses comprehensive content analysis to assess capability claims:
| Analysis Dimension | Description | Assessment Focus |
|-------------------|-------------|------------------|
| **Core Requirements Coverage** | Alignment with primary safeguard elements | Direct implementation language and specific capabilities |
| **Sub-Elements Coverage** | Support for detailed safeguard components | Breadth of coverage across safeguard sub-requirements |
| **Governance Alignment** | Policy/process management elements | Governance language and oversight capabilities |
| **Implementation Depth** | Specificity and detail of implementation | Technical depth and implementation specifics |
| **Language Consistency** | Alignment between claim and evidence | Consistency between stated capability and supporting text |
**Content Analysis Logic**: Evidence is evaluated across multiple dimensions:
- **Strong Evidence**: Detailed implementation specifics with comprehensive coverage
- **Moderate Evidence**: Good coverage with some gaps or general language
- **Weak Evidence**: Limited specifics or scope, vague implementation details
### Validation Statuses
- **SUPPORTED** (70-100%): Evidence strongly supports the claimed capability
- **QUESTIONABLE** (40-69%): Evidence partially supports but has notable gaps or inconsistencies
- **UNSUPPORTED** (0-39%): Evidence does not adequately support the claim
### Usage Examples
```bash
# Validate a FULL coverage claim with strong evidence
claude-code "Use validate_vendor_mapping for vendor 'AssetMax Pro', safeguard '1.1', claimed capability 'full', with supporting text: 'Our platform provides comprehensive automated discovery, detailed inventory management, and complete asset lifecycle tracking for all enterprise devices including servers, workstations, and network equipment.'"
# Validate a FACILITATES claim
claude-code "Use validate_vendor_mapping for vendor 'ThreatIntel Feed', safeguard '1.1', claimed capability 'facilitates', with supporting text: 'Our threat intelligence service provides supplemental risk data that enriches existing asset management systems, enabling organizations to prioritize asset security based on threat exposure.'"
# Partial capability claim with clear scope limitations
claude-code "Use validate_vendor_mapping for vendor 'NetworkScanner Pro', safeguard '1.1', claimed capability 'partial', with supporting text: 'Our scanner provides comprehensive network device discovery and maintains detailed hardware inventories, but is limited to network-accessible devices and does not track software installations or offline systems.'"
# Insufficient evidence example
claude-code "Use validate_vendor_mapping for vendor 'BasicTracker', safeguard '1.1', claimed capability 'full', with supporting text: 'We help track computers and provide some visibility into your IT environment.'"
```
## šÆ CIS Controls Coverage
**Complete CIS Controls v8.1 Framework Implementation**
- **153 total safeguards** across all 18 controls
- **Full framework coverage** from Controls 1-18
- **Comprehensive vendor analysis** capability for all CIS safeguards
### Current Version Highlights
- ā
**All 18 Controls** implemented (Enterprise Assets through Penetration Testing)
- ā
**Color-coded element categorization** (Orange/Green/Yellow/Gray)
- ā
**Enhanced capability detection** (Governance, Facilitates, Coverage, Validates)
- ā
**Production-ready** vendor analysis for complete compliance assessments
## š ļø Development
### Build from Source
```bash
git clone https://github.com/therealcybermattlee/FrameworkMCP.git
cd FrameworkMCP
npm install
npm run build
```
### Add New Safeguards
Edit `src/core/safeguard-manager.ts` and add to the `initializeSafeguards()` method:
```typescript
"X.Y": {
id: "X.Y",
title: "Safeguard Title",
description: "Description...",
implementationGroup: "IG1",
governanceElements: [...], // Orange - MUST be met
coreRequirements: [...], // Green - The "what"
subTaxonomicalElements: [...], // Yellow - Sub-elements
implementationSuggestions: [...], // Gray - Suggestions
// ...
}
```
### Testing
```bash
npm test
```
## š¤ Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Guidelines
- Follow the existing code style
- Add tests for new features
- Update documentation
- Ensure all tests pass
## š Documentation
- [Installation Guide](docs/installation.md)
- [API Reference](docs/api-reference.md)
- [CIS Safeguards Reference](docs/safeguards-reference.md)
- [Example Usage](examples/example-usage.md)
- **[Microsoft Copilot Integration Guide](COPILOT_INTEGRATION.md)** - Complete setup guide for custom connectors
- [Deployment Guide](DEPLOYMENT_GUIDE.md) - Cloud deployment instructions
- [OpenAPI Specification](swagger.json) - Complete API schema for integrations
## š Troubleshooting
### Common Issues
**Permission denied:**
```bash
chmod +x dist/index.js
```
**Module not found:**
```bash
npm install
npm run build
```
**MCP server not connecting:**
- Check Claude Code MCP configuration
- Verify file paths are absolute
- Ensure Node.js version compatibility
## š License
This project is licensed under the Creative Commons Attribution 4.0 International License by Cyber RISE, Inc - see the [LICENSE](LICENSE) file for details.
You are free to:
- **Share** ā copy and redistribute the material in any medium or format
- **Adapt** ā remix, transform, and build upon the material for any purpose, even commercially
Under the following terms:
- **Attribution** ā You must give appropriate credit to Cyber RISE, Inc, provide a link to the license, and indicate if changes were made
## š Acknowledgments
- **Center for Internet Security (CIS)** for the CIS Controls Framework
- **Pax8** and community contributors for the CIS Controls visualizations
- **Anthropic** for the Model Context Protocol and Claude Code
## š Support
- š§ **Issues**: [GitHub Issues](https://github.com/therealcybermattlee/FrameworkMCP/issues)
- š **Documentation**: [Project Wiki](https://github.com/therealcybermattlee/FrameworkMCP/wiki)
- š¬ **Discussions**: [GitHub Discussions](https://github.com/therealcybermattlee/FrameworkMCP/discussions)
- š¦ **Updates**: Follow [@cybermattlee](https://twitter.com/cybermattlee) for project updates
---
**Built with ā¤ļø for the cybersecurity community by [Matt Lee](https://github.com/therealcybermattlee)**