MCP Server for OSCAL

OSCAL MCP 服务

为你喜爱的 AI Agent 即时提供 OSCAL 专业知识

一个模型上下文协议（MCP）服务，为 AI 助手（Claude、Cline、Kiro、Claude Code 等）提供工具，以便使用 NIST 的开放安全控制评估语言（OSCAL）。和许多早期采用者一样，我们需要帮助实现 OSCAL 概念验证，以向业务利益相关者展示其价值。可能是因为公共领域的示例有限，我们发现单靠大多数 AI Agent/大模型，针对 OSCAL 得出的结果并不一致。这个 MCP 服务中的工具最大限度地减少了我们用例中的这一问题，希望也能为你做到这一点。

提示

请参阅下方的安装以开始使用。

功能

这些 MCP 服务提供的工具旨在协助你首选的 AI 助手，就 OSCAL 架构、模型、用例、要求和实现提供准确、权威的指导。使用这些工具不需要了解它们的具体细节，但相关信息位于 tools 目录中。

该服务轻量化，旨在无需额外设置即可在本地运行。默认情况下，它使用 stdio 协议传输 MCP。请勿尝试通过 streamable-http 传输方式使用该服务，因为我们尚未实现传输安全或身份验证。

默认工具不应连接任何远程服务或资源——所有必需内容都与服务打包在一起。作为一项安全措施，我们对打包内容实施了基本的文件完整性验证。在构建时，我们会生成清单，其中包含所有内容文件的 SHA-256 哈希值。每次服务启动时，都会根据哈希清单验证所有内容文件。任何不匹配都应触发错误并阻止服务启动。

除 MCP 服务外，该软件包还包含一个使用 Strands Agents 构建的独立 OSCAL Agent。请参阅下方的 OSCAL Agent 部分。

什么是 OSCAL？

OSCAL（开放安全控制评估语言）是 NIST 开发的一套与框架无关、与供应商无关且可机器读取的架构，用于描述 GRC（治理、风险、合规）工件的完整生命周期，涵盖从控制措施到补救计划。OSCAL 通过使用基于标准的结构化数据格式取代数字化文档（电子表格、PDF 等），实现 GRC 工作流自动化。要了解更多 OSCAL 信息，请安装此 MCP 服务，然后向你的 AI 提问。也可以访问 OSCAL 官方网站。

什么是 MCP？

MCP（Model Context Protocol）是一项开源标准，用于将 AI 应用连接到外部系统。可以把 MCP 看作 AI 应用的 USB-C 接口。正如 USB-C 为连接电子设备提供了标准化方式，MCP 也为将 AI 应用连接到外部系统提供了标准化方式。

使用方法 / 示例

以下示例使用 kiro-cli 创建，但应该适用于任何支持 MCP 服务的 AI 助手。

示例 1：了解可用的 OSCAL 模型

 % kiro-cli

> /tools trust get_oscal_schema list_oscal_models list_oscal_resources


Tools '@oscal/get_oscal_schema', '@oscal/list_oscal_models', '@oscal/list_oscal_resources' are now trusted. I will not ask for confirmation before running these tools.


> How many GA OSCAL models are there? 


> I'll check the available OSCAL models to find out how many are in GA (Generally Available) status.
Running tool list_oscal_models with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.1s

> There are 8 GA OSCAL models:

Control Layer (3):
- Catalog
- Profile  
- Mapping Collection

Implementation Layer (2):
- Component Definition
- System Security Plan (SSP)

Assessment Layer (3):
- Assessment Plan (SAP)
- Assessment Results (SAR)
- Plan of Action and Milestones (POA&M)

All of these models have "GA" (Generally Available) status, meaning they are stable and ready for production use.
 ▸ Time: 8s

示例 2：生成 OSCAL 模板

> generate a minimum, valid, OSCAL mapping in JSON for use as a template.

> I'll help you create a minimal, valid OSCAL mapping in JSON. Let me first check what OSCAL models are available to understand the structure.
Running tool list_oscal_models with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.1s

> Now let me get the schema for the mapping-collection model to understand its structure:
Running tool get_oscal_schema with the param (from mcp server: oscal)
 ⋮  {
 ⋮    "model_name": "mapping-collection",
 ⋮    "schema_type": "json"
 ⋮  }
 - Completed in 0.14s

> Based on the schema, I'll create a minimal, valid OSCAL mapping collection template. Here's the absolute minimum required structure:
I'll create the following file: ./oscal-mapping-template.json (using tool: write)
Purpose: Create minimal OSCAL mapping collection template

+     1: {
+     2:   "mapping-collection": {
+     3:     "uuid": "12345678-1234-4567-8901-123456789012",
+     4:     "metadata": {
+     5:       "title": "Sample Mapping Collection",
+     6:       "last-modified": "2026-01-06T20:46:28.034Z",
+     7:       "version": "1.0",
+     8:       "oscal-version": "1.2.0"
+     9:     },
+    10:     "provenance": {
+    11:       "method": "human",
+    12:       "matching-rationale": "semantic",
+    13:       "status": "draft",
+    14:       "mapping-description": "Sample mapping between two control frameworks"
+    15:     },
+    16:     "mappings": [
+    17:       {
+    18:         "uuid": "87654321-4321-7654-1098-210987654321",
+    19:         "source-resource": {
+    20:           "type": "catalog",
+    21:           "href": "https://example.com/source-catalog.json"
+    22:         },
+    23:         "target-resource": {
+    24:           "type": "catalog", 
+    25:           "href": "https://example.com/target-catalog.json"
+    26:         },
+    27:         "maps": [
+    28:           {
+    29:             "uuid": "11111111-2222-3333-4444-555555555555",
+    30:             "relationship": "equivalent",
+    31:             "sources": [
+    32:               {
+    33:                 "type": "control",
+    34:                 "id-ref": "ac-1"
+    35:               }
+    36:             ],
+    37:             "targets": [
+    38:               {
+    39:                 "type": "control",
+    40:                 "id-ref": "access-control-policy"
+    41:               }
+    42:             ]
+    43:           }
+    44:         ]
+    45:       }
+    46:     ]
+    47:   }
+    48: }

Creating: ./oscal-mapping-template.json
 - Completed in 0.8s

> I've created a minimal, valid OSCAL mapping collection template at ./oscal-mapping-template.json. This template includes:

Required elements:
- uuid: Unique identifier for the mapping collection
- metadata: Document metadata with title, last-modified timestamp, version, and OSCAL version
- provenance: Mapping methodology information including method, matching rationale, status, and description
- mappings: Array containing at least one mapping with:
  - uuid: Mapping identifier
  - source-resource and target-resource: References to the catalogs being mapped
  - maps: Array with mapping entries showing relationships between controls

Key features:
- Uses placeholder UUIDs (replace with actual UUIDs in production)
- Maps a source control "ac-1" to target control "access-control-policy" with "equivalent" relationship
- Includes minimal required fields only
- Valid JSON structure conforming to OSCAL 1.2.0 schema

You can customize this template by:
- Replacing placeholder UUIDs with real ones
- Updating the resource URLs to point to actual catalogs
- Adding more mapping entries in the maps array
- Modifying control IDs and relationships as needed
 ▸ Time: 21s

示例 3：查找开源 OSCAL 目录

> What are some open source OSCAL catalogs?

Running tool list_oscal_resources with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.51s

> Based on the OSCAL community resources, here are some notable open source OSCAL catalogs:

## Government/Official Catalogs

Australian Cyber Security Centre (ACSC)
- Information Security Manual (ISM) controls in OSCAL format
- Essential Eight Maturity Levels (ML1, ML2, ML3)
- Available at: https://www.cyber.gov.au/ism/oscal

CMS Acceptable Risk Safeguards (ARS)
- Tailored NIST SP 800-53 controls for Centers for Medicare and Medicaid Services
- Available at: https://github.com/CMSgov/ars-machine-readable

GovTech Singapore
- ICT&SS Policy catalog and profile for low-risk systems
- Available at: https://github.com/GovtechSG/tech-standards

## Industry/Standards Organizations

Center for Internet Security (CIS)
- CIS Critical Security Controls (formerly Top 18/20)
- Available at: https://github.com/CISecurity/CISControls_OSCAL/

Cloud Security Alliance (CSA)
- Cloud Controls Matrix v4 in OSCAL format
- Available at: https://cloudsecurityalliance.org/artifacts/ccm-machine-readable-bundle-json-yaml-oscal/

NIST SP 800-171 (Community)
- Maintained by Fathom5
- Available at: https://github.com/FATHOM5/oscal/tree/main/content/SP800-171/oscal-content

## Community Collections

CivicActions Component Definitions
- Cloud services, software, security and privacy controls
- Available at: https://github.com/CivicActions/oscal-component-definitions

RedHat OSCAL Content
- Component definitions: https://github.com/RedHatProductSecurity/oscal-component-definitions
- Custom profiles: https://github.com/RedHatProductSecurity/oscal-profiles

Brad Hards ISM Catalog
- Australian Government ISM controls (community version)
- Available at: https://github.com/bradh/ism-oscal

These catalogs provide ready-to-use OSCAL content for various compliance frameworks and can serve as templates or starting points for your own OSCAL implementations.
 ▸ Time: 15s

示例 4：查询组件定义，了解 AWS 服务信息

[OSCAL] > what components are available for Cognito?

Running tool list_components with the param (from mcp server: oscal-dev)
 ⋮  {}
 - Completed in 0.49s

> There are 3 Cognito-related components available:

1. Cognito Identity - from "Cognito Identity Pools" component definition
2. Cognito Sync - from "Amazon Cognito Sync" component definition  
3. Cognito Identity Provider - from "Amazon Cognito Identity User Pools" component definition

 ▸ Time: 7s

[OSCAL] > show me the names and IDs from all 3 components

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "7fd5d354-6ec4-4f8e-8c5f-2904086bb597"
 ⋮  }
Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "a1d82e1d-3733-41f4-bc09-90ab47b9e82f"
 ⋮  }
Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "2519deaf-4612-4c70-aba2-d9080ae3c816"
 ⋮  }
 - Completed in 0.13s

 - Completed in 0.6s

 - Completed in 0.6s

> 1. Cognito Sync
- Service ID: Cognito Sync
- API Endpoint Prefix: cognito-sync
- ARN Namespace: cognito-sync

2. Cognito Identity Provider
- Service ID: Cognito Identity Provider
- API Endpoint Prefix: cognito-idp
- ARN Namespace: cognito-idp

3. Cognito Identity
- Service ID: Cognito Identity
- API Endpoint Prefix: cognito-identity
- ARN Namespace: cognito-identity

 ▸ Time: 12s

[OSCAL] > show me everything in the EC2 component definition

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "component_definition_filter": "Elastic Compute Cloud (EC2)",
 ⋮    "query_type": "all"
 ⋮  }
 - Completed in 0.14s

> The EC2 component definition contains 1 component:

Component: EC2
- UUID: 66345eb9-7c0d-435c-b2b5-675fd977de80
- Type: service
- Description: Empty

Properties:
- Service ID: EC2
- Version: 2016-11-15
- Availability: REGIONAL and ZONAL
- Full Name: Elastic Compute Cloud (EC2)
- API Endpoint Prefix: ec2
- ARN Namespace: ec2

Regional Availability (34 regions):
Africa (Cape Town), Asia Pacific (Hong Kong, Tokyo, Seoul, Osaka, Mumbai, Hyderabad, Singapore, Sydney, Jakarta, Melbourne, Malaysia), Canada (Central, Calgary), China (Beijing, Ningxia), 
Europe (Frankfurt, Zurich, Stockholm, Milan, Spain, Ireland, London, Paris), Israel (Tel Aviv), Middle East (UAE, Bahrain), South America (Sao Paulo), US East (N. Virginia, Ohio), AWS 
GovCloud (US-East, US-West), US West (N. California, Oregon)

 ▸ Time: 10s

[OSCAL] > what's the ID of the Jakarta region?

> Based on the EC2 component data I just retrieved, the Jakarta region's resource fragment ID is:

8041109b-0a0b-46cc-bddb-91d703667637

This is the UUID for the "Asia Pacific (Jakarta)" region component.

 ▸ Time: 3s

[OSCAL] > get the region ID from that component

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "8041109b-0a0b-46cc-bddb-91d703667637"
 ⋮  }
 - Completed in 0.13s

> The region ID for Jakarta is: ap-southeast-3

 ▸ Time: 7s

[OSCAL] > /quit

安装

按照以下说明，为你首选的 IDE、AI Agent、聊天机器人等配置 MCP 服务。该服务以 Python 软件包的形式发布在 PyPI 上。uvx 命令（如下所示）会在启动时自动从 PyPI 下载该服务的最新版本。

说明

若要改为配置开发环境，请参阅 DEVELOPING.md

先决条件

• Python 的 uv 软件包管理器（安装说明）
• Python 3.11 或更高版本（uv install python 3.12）。该服务可能也适用于更高版本的 Python，但目前我们只测试了 3.11 和 3.12。

配置 IDE 和 AI 工具

该服务通过 stdio（标准输入/输出）进行通信，可与各种支持 Model Context Protocol 的 IDE 和 Agent 工具集成。以下配置示例适用于你首选的 IDE / 聊天机器人 / Agent。

配置格式

大多数兼容 MCP 的工具使用 FastMCP 文档中介绍的 JSON 配置格式。基本结构如下：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

对于 MCP 服务的常规运行时使用，通常无需额外配置。如有需要，可按照 FastMCP 文档中的说明，在 "env": {} 对象中配置运行时环境变量。可查看文件 dotenv.example 了解可用选项。

说明

dotenv 文件仅在开发环境中需要。

Kiro 配置

如需了解其他选项，请参阅 Kiro 的 MCP 文档。将以下内容添加到 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "*"
      ]
    }
  }
}

Claude Desktop

将以下内容添加到 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

VS Code

运行 MCP: Open User Configuration 命令，该命令会打开用户配置文件中的 mcp.json 文件。然后，你可以手动将服务配置添加到该文件中。如需了解其他选项和详细信息，请参阅 VSCode/Copilot 文档。

{
  "servers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

使用你自己的 OSCAL 内容

默认情况下，服务附带打包的 OSCAL 内容（AWS 组件定义、OSCAL 文档和架构）。你也可以让服务读取包含自己 OSCAL JSON 文件的目录——例如目录、SSP、配置文件、评估计划、评估结果、POA&M 或映射集合。服务会在启动时为这些文件建立索引，并通过所有查询和列表工具提供访问。

将 OSCAL_DOCUMENTS_DIR 环境变量设置为你的 OSCAL 内容目录路径。该路径可以是绝对路径，也可以是相对于服务包目录的路径。例如，在你的 MCP 配置中：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"],
      "env": {
        "OSCAL_DOCUMENTS_DIR": "/path/to/your/oscal/files"
      }
    }
  }
}

服务会递归扫描该目录中的 .json 文件，并为找到的有效 OSCAL 文档建立索引。你的内容会与打包的内容合并，两者都可以在同一会话中查询。

另外两个环境变量用于控制 OSCAL 存储的行为：

变量	默认值	说明
OSCAL_DOCUMENTS_DIR	(empty)	包含你的 OSCAL JSON 文件的目录。为空时不会扫描。
OSCAL_STORE_DB_PATH	(empty)	持久化 SQLite 数据库的路径。设置后，索引会在服务重启后复用，而不会每次重新构建。
OSCAL_STORE_CACHE_SIZE	100	在内存 LRU 缓存中保留的已解析 OSCAL 文档的最大数量。

提示

如果你有大量 OSCAL 文档，建议设置 OSCAL_STORE_DB_PATH。之后启动服务时，只需为新增或已更改的文件建立索引。

OSCAL Agent

除了 MCP 服务外，该包还包含一个使用 Strands Agents 构建的独立 OSCAL Agent。该 Agent 使用与 MCP 服务相同的工具，并可直接运行：

# Via entry point
oscal-agent

# Or via module
python -m mcp_server_for_oscal.oscal_agent

该 Agent 需要访问 AWS Bedrock，并使用与 MCP 服务相同的配置环境变量。

会话持久化

该 Agent 支持会话持久化，因此对话历史和 Agent 状态可以在多次调用之间保留。你可以选择本地文件系统或 Amazon S3 存储：

# File-based session storage (new session)
oscal-agent --session-storage file

# Resume a previous session
oscal-agent --session-storage file --session-id <your-session-id>

# S3-based session storage
oscal-agent --session-storage s3 --session-s3-bucket my-bucket

启用会话存储但未指定 --session-id 时，系统会自动生成并显示一个 UUID，供你之后恢复会话。也可以通过环境变量设置会话默认值（请参阅 DEVELOPING.md）。

对话管理

对于长时间运行的工作流，你可以选择对话管理器，以控制如何维护 Agent 的上下文窗口：

# Summarize older messages to keep context manageable
oscal-agent --session-storage file --conversation-manager summarizing

# Sliding window (SDK default behavior)
oscal-agent --conversation-manager sliding-window

# No conversation management
oscal-agent --conversation-manager null

现有工具和功能涵盖了各种使用场景，但距离全面支持还_相差甚远_。欢迎通过 GitHub issue 分享反馈、功能请求、问题或错误报告。我们期待并欢迎你直接提交贡献。

开发

请参阅 DEVELOPING 了解如何开始。

安全

请参阅 CONTRIBUTING 了解更多信息。

已知限制

• 由于 ChatGPT 对 MCP 的支持有限，目前还无法将此 MCP 服务与 ChatGPT 搭配使用。
• streamable-http 传输尚未实现身份验证或传输安全。生产环境中请使用 stdio。

相关项目

此 MCP 服务附带 AWS 服务的实验性组件定义。你可以在 AWS Labs 项目 OSCAL Content for AWS Services 中找到相关内容。

OSCAL 的 MCP 服务使用 compliance-trestle 实现某些功能，包括 OSCAL 内容验证。

许可证

本项目采用 Apache-2.0 许可证。