📚 课程目录第4章标准模板定义语言

4. 标准模板定义语言：YAML/JSON Schema作为模板基础

环境一致性基线核验的核心在于“模板即契约”。本章聚焦模板的定义语言与结构设计，明确为何选择 YAML/JSON Schema 作为载体，并拆解模板的三层核心结构：元数据、规则集与预期值。

4.1 模板语言选型：YAML vs JSON Schema

YAML 与 JSON Schema 并非对立关系，而是互补组合。YAML 提供人类可读的模板实例描述，JSON Schema 提供机器可执行的校验规则。实际基线模板通常以 YAML 编写模板实例，以 JSON Schema 定义模板结构约束。

特性	YAML（模板实例）	JSON Schema（模板约束）
可读性	极高，缩进结构清晰	中等，适合机器解析
注释支持	原生支持 # 注释	通过 $comment 扩展
类型系统	隐式类型（字符串/数字/布尔）	显式类型（string/integer/object/array）
校验能力	无内置校验	内置 type/pattern/enum/required 等
引用复用	锚点 & 别名	$ref 引用
生态工具	yq、PyYAML	ajv、jsonschema CLI

实践建议：模板实例使用 YAML 编写，模板 Schema 使用 JSON Schema（.json 文件）定义。两者通过 schema 字段在元数据中关联，实现“实例可读、约束可验”的双赢。

4.2 模板结构三层设计

每个标准基线模板由三个逻辑层组成：元数据层描述模板自身信息，规则集层定义核验逻辑，预期值层提供基准数据。三层结构确保模板可管理、可复用、可版本化。

模板三层结构总览：

template:
  metadata:      # 元数据层
    name:        # 模板名称
    version:     # 语义化版本
    schema:      # 关联的 JSON Schema 路径
    tags:        # 分类标签
  rules:         # 规则集层
    - id:        # 规则唯一标识
      type:      # 核验类型（file/process/network）
      target:    # 核验目标路径
  expected:      # 预期值层
    key:         # 配置键
    value:       # 预期基准值
    operator:    # 比较操作符（eq/ne/gt/lt/regex）

4.2.1 元数据层（Metadata）

元数据是模板的“身份证”，用于模板仓库管理、版本追溯与自动发现。每个基线模板必须包含以下核心字段：

name：模板唯一名称，采用 namespace/component/baseline-name 三级命名。
version：遵循 SemVer 2.0，如 1.2.0。
schema：指向 JSON Schema 文件的相对路径或 URI。
tags：用于分类检索的标签列表，如 [os:linux, security:cis]。
created / updated：时间戳，ISO 8601 格式。

注意：元数据中的 schema 字段必须指向一个可访问的 JSON Schema 文件。核验引擎在加载模板时，会先使用该 Schema 对模板实例进行结构校验，拒绝不符合 Schema 约束的模板。

4.2.2 规则集层（Rules）

规则集定义“核验什么”以及“如何核验”。每条规则是一个独立核验单元，包含以下关键属性：

属性	类型	说明	示例
`id`	string	规则唯一标识，模板内唯一	`R001`
`type`	enum	核验类型：file / process / network / registry / custom	`file`
`target`	string	核验目标路径或标识	`/etc/ssh/sshd_config`
`severity`	enum	严重级别：critical / high / medium / low	`high`
`enabled`	boolean	是否启用该规则	`true`

4.2.3 预期值层（Expected）

预期值层提供核验的“基准答案”。每条规则可包含一个或多个预期值条目，每个条目由 key、value、operator 三元组构成：

key：配置项路径，支持点号分隔（如 PermitRootLogin）。
value：基准值，支持字符串、数字、布尔、数组、null。
operator：比较操作符，决定如何比对实际值与预期值。

操作符	含义	适用场景
`eq`	等于（精确匹配）	端口号、布尔开关
`ne`	不等于	禁止项检查
`gt` / `ge`	大于 / 大于等于	内核参数、超时阈值
`lt` / `le`	小于 / 小于等于	最大连接数、内存限制
`regex`	正则匹配	日志格式、版本号模式
`contains`	包含子串	白名单列表、路径前缀
`in`	值在枚举集合中	允许的加密算法列表

4.3 模板结构可视化

下图展示标准基线模板的三层结构及其与 JSON Schema 的关联关系：

4.4 完整模板示例

以下是一个完整的 SSH 安全基线模板，展示三层结构的实际编写方式：

# ssh-baseline.yaml
metadata:
  name: security/ssh-baseline
  version: 1.2.0
  schema: schemas/ssh-schema.json
  tags:
    - os:linux
    - security:cis
    - category:ssh
  created: 2025-01-15T08:00:00Z
  updated: 2025-03-20T14:30:00Z

rules:
  - id: R001
    type: file
    target: /etc/ssh/sshd_config
    severity: high
    enabled: true
    expected:
      - key: PermitRootLogin
        value: "no"
        operator: eq
      - key: PasswordAuthentication
        value: "no"
        operator: eq
      - key: Port
        value: 22
        operator: eq

  - id: R002
    type: process
    target: sshd
    severity: critical
    enabled: true
    expected:
      - key: status
        value: running
        operator: eq
      - key: pid
        value: null
        operator: ne

  - id: R003
    type: network
    target: 0.0.0.0:22
    severity: medium
    enabled: true
    expected:
      - key: state
        value: LISTEN
        operator: eq
      - key: protocol
        value: tcp
        operator: eq

4.5 模板设计最佳实践

  关键原则：
  单一职责：每个模板只针对一个基线领域（如 SSH、Docker、Kernel），避免大而全的“万能模板”。
显式版本：每次修改模板必须升级版本号，核验引擎通过版本号判断模板是否需要重新加载。
Schema 先行：先编写 JSON Schema 定义模板结构，再编写 YAML 实例，确保实例始终符合约束。
操作符精确：优先使用 eq 和 regex，避免模糊匹配导致误报。
规则粒度：每条规则只核验一个目标的一个维度，便于定位失败原因。

常见陷阱：

YAML 缩进不一致导致解析失败——建议使用 yq 或 yamllint 进行预校验。
预期值类型不匹配（如字符串 "22" 与数字 22）——JSON Schema 中应明确 type 约束。
规则 id 重复——核验引擎会拒绝加载重复 id 的模板。

4.6 模板与 Schema 的关联校验流程

下图展示从模板加载到核验任务生成的完整流程：

4.7 本章小结

YAML 与 JSON Schema 组合使用，兼顾人类可读性与机器可校验性。
模板三层结构（元数据、规则集、预期值）是基线核验的标准化基础。
预期值操作符体系（eq/ne/gt/lt/regex/contains/in）覆盖常见比较场景。
JSON Schema 作为前置约束层，确保模板实例在加载阶段即被校验，避免运行时错误。