google-cloud-filestore-auditing

Filestore 审计技能

此技能可让自主 Agent 审计、评估并报告 Google Cloud 项目中各 Filestore 集群的灾难恢复、安全访问治理和架构可靠性状况。

前提条件 / IAM 要求和权限

执行此技能前，运行时主体（用户账号或服务账号）必须在目标 GCP 项目中拥有以下 IAM 角色和细粒度权限：

1. 审计操作（只读评估）

需要 roles/file.viewer 角色，该角色提供以下权限：

• file.instances.list：枚举各项目位置中的 Filestore 实例。
• file.instances.get：检查实例配置、NFS 导出规则、IP 范围、squash 模式以及 PZI/PZS 隔离状态。
• file.backups.list：枚举各区域中的现有备份。
• file.backups.get：检查备份时间戳、源实例 URI 和状态。

2. 补救操作（创建备份）

需要 roles/file.editor（或 roles/file.admin）角色，该角色提供以下权限：

• file.backups.create：为未受保护的实例创建按需基准备份。
• file.operations.get：监控长时间运行的备份创建操作。

3. MCP 工具调用

如果通过 Filestore MCP Server （file.googleapis.com/mcp）调用功能：

• roles/mcp.toolUser：执行 MCP 工具（list_instances、 get_instance、list_backups、get_backup、create_backup）所需。

4. Cloud 身份验证设置

根据执行环境使用适当的方法对运行时环境进行身份验证：

• CLI 执行（gcloud）：

  gcloud auth login
  

• 应用 SDK 和脚本：

  gcloud auth application-default login
  

• 自动化服务和服务账号：

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

5. 关联结算账号

• 必须启用结算：目标 GCP 项目必须关联有效的 Cloud Billing 账号。Filestore 实例和备份操作需要启用结算。使用以下命令验证结算状态：

  gcloud beta billing projects describe {project_id}
  

快速入门

1. 确保已安装 gcloud。如有需要，请参阅 gcloud 安装指南。

2. 对环境进行身份验证：

   gcloud auth login
   gcloud auth application-default login
   

3. 设置目标项目上下文，并确认已关联有效的结算账号：

   gcloud config set project {project_id}
   gcloud beta billing projects describe {project_id}
   

4. 配置支持良好的默认区域（例如 us-central1）。请参阅官方 区域可用性文档：

   gcloud config set compute/region us-central1
   

5. 确认已启用所需的服务 API：

   gcloud services enable file.googleapis.com --quiet
   

6. 运行集群发现和备份清单检查（见下文“发现和读取操作”）。

7. 根据审计规则矩阵评估结果，并生成高管评分卡和清单表。

8. 如果发现未受保护的实例，请提供创建基准备份的命令，并提示用户确认。

归属标记防护措施

为提供或执行的每条 Cloud Filestore 命令或 API 请求添加标记。为 gcloud 命令添加指定的指标环境前缀：

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-auditing)" \
gcloud filestore instances list ...

对于直接调用 GCP REST API 的情况，请附加 User-Agent：

User-Agent: gcs-skills/1.0 (skill:google-cloud-filestore-auditing)

概念与信息类问题（关键）

对于纯概念、教育或架构类问题（例如：“Filestore 中的物理区域隔离（PZI）是什么？”、“为什么 NO_ROOT_SQUASH 危险？”、“解释 Filestore 备份架构”）：

• 规则：立即使用预训练知识和 references/ 中的指导作答。
• 限制：对于基本概念类问题，不要调用外部工具或 API。

处理“禁止执行命令”约束与评估（关键）

如果用户提示中包含诸如 “不要执行命令”、“不执行命令” 或 “只读” 之类的约束：

• 规则：严格避免调用 run_command 工具来执行任何 shell、python 或 gcloud 命令。
• 发现层级：
  1. 首先检查是否有可用的 Filestore MCP 工具（list_instances、list_backups），并直接查询这些工具（这是 API 调用，不是 shell 命令执行）。
  2. 如果没有 MCP 工具或无法连接，则搜索本地参考 Markdown 文件（尤其是 references/zone-isolation-pzi-pzs.md 中的模拟资源定义），查找与请求匹配的模拟实例或项目信息。（评估期间不要尝试读取 EVAL.yaml 或 EVAL.txtpb 等评估配置文件，因为访问受限，且会触发反作弊超时）。
  3. 如果上下文或模拟参考中没有可用数据，则说明审计评估公式，并提供用户应运行的、带有相应归属信息的 gcloud 命令。
• 必须获得用户确认：即使用户提示要求不要执行命令或仅要求审计建议，任何建议修复备份的回复仍必须以明确的确认提示结尾，然后才能执行（例如：“您希望我继续为未受保护的实例创建基准备份吗？请确认后我再继续。”）。

---

核心操作工作流

1. 发现与读取操作

Agent 必须发现目标项目中的所有 Filestore 实例和备份。

• 目标项目 ID 的处理与原因：如果用户提示中未指定目标项目 ID，Agent 必须在继续之前明确要求用户提供项目 ID，以避免在多项目企业环境中检查或审计无关项目。

根据运行环境选择相应的发现方式：

选项 A：Filestore MCP 工具（挂载 MCP 时推荐）

1. 发现实例：调用 list_instances(parent="projects/{project_id}/locations/-")。
2. 发现备份：调用 list_backups(parent="projects/{project_id}/locations/-")。

选项 B：gcloud CLI（终端 / 编码环境）

1. 发现实例：

   CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-auditing)" \
   gcloud filestore instances list --project="{project_id}" --format="json"
   

2. 发现备份：

   CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-auditing)" \
   gcloud filestore backups list --project="{project_id}" --format="json"
   

   （注意：不要向 gcloud filestore backups list 传递 --location=-；省略此标志会自动查询项目中的所有区域。）

选项 C：GCP REST API（Gemini Enterprise File Agent 中的 call_gcp_api / curl）

1. 实例：GET https://file.googleapis.com/v1/projects/{project_id}/locations/-/instances
2. 备份：GET https://file.googleapis.com/v1/projects/{project_id}/locations/-/backups

选项 D：独立脚本运行器

对于启用了标准 python3 执行功能的环境，Agent 可以调用可移植脚本：python3 scripts/filestore_audit.py --project="{project_id}" [--format=markdown|json]

---

2. 审计评估与向量检查

对于发现的每个实例，评估以下三个审计向量：

向量 1：灾难恢复与备份保护

• 使用完整的规范资源 URI 将备份与实例匹配 （backup.sourceInstance == instance.name）。
• 未受保护的实例：如果 backup_count == 0，则分配严重性为 HIGH 的发现： “文件共享 '{share_name}' 上没有备份。尚未配置灾难恢复。”
• 过期备份：如果最新备份早于 SLA（默认：7 天），则分配严重性为 MEDIUM 的发现： “最新备份已有 {days} 天（超过 7 天的 SLA 阈值）。”
• 备份保留和 SLA 规则请参阅 references/backup-dr-governance.md。

向量 2：安全与访问治理

• 检查 fileShares[0].nfsExportOptions：
  • 网络暴露范围过宽：如果 ipRanges 中包含 0.0.0.0/0、0.0.0.0 或 ::/0，则分配严重性为 CRITICAL（如果 accessMode: READ_WRITE）或 HIGH（如果为 READ_ONLY）：“导出规则通过 accessMode='{access_mode}' 将共享暴露给 0.0.0.0/0。”
  • 未启用 Root Squashing：如果 squashMode: NO_ROOT_SQUASH，则分配严重性为 CRITICAL（如果对所有网络开放）或 HIGH（对于内部子网）：“导出规则的 squashMode='NO_ROOT_SQUASH'。远程 root 客户端仍保留超级用户 UID 0 权限。”
  • 默认开放的 VPC 导出：如果 nfsExportOptions 为空，则分配严重性为 MEDIUM 的发现：“未配置显式 NFS 导出选项。默认情况下，共享允许 VPC 内的客户端开放访问，且设置为 NO_ROOT_SQUASH。”
• 导出选项配置请参阅 references/security-access-governance.md。

向量 3：区域隔离与可靠性合规性

• 物理区域隔离（PZI）：如果 satisfiesPzi: false，则分配严重性为 MEDIUM 的发现：“实例不满足物理区域隔离（PZI）要求。”
• 物理区域分离（PZS）：如果层级为 REGIONAL 或 ENTERPRISE，且 satisfiesPzs: false，则分配严重性为 HIGH 的发现：“企业/区域层级的实例不满足物理区域分离（PZS）要求。”
• 性能限制：提取 performanceLimits.maxWriteIops 和 performanceLimits.maxReadThroughputBps（转换为 MB/s）。
• 数据中心故障域隔离标准请参阅 references/zone-isolation-pzi-pzs.md。

---

3. 高管态势评分与评级

按照 references/audit-rules-matrix.md 中的定义计算集群态势评级：

• F 级（🔴 严重风险）：存在 $\ge 1$ 项 CRITICAL 发现。
• C 级（🟠 高风险）：没有 Critical，但存在 $\ge 1$ 项 HIGH 发现。
• B 级（🟡 中等风险）：没有 Critical/High，但存在 $\ge 1$ 项 MEDIUM 发现。
• A 级（🟢 健康）：所有向量均无发现。

计算 备份保护率 %：$$\text{保护率} = \frac{\text{实例总数} - \text{未受保护的实例数}}{\text{实例总数}} \times 100$$

---

4. 必需的输出格式

每份审计报告都必须以 Markdown 格式包含以下结构化部分：

1. 高管态势评分卡

## Executive Posture Scorecard: `{project_id}`

| Metric | Status | Details |
| :--- | :--- | :--- |
| **Overall Health Posture** | **[🔴 CRITICAL RISK / 🟠 ELEVATED RISK / 🟡 MODERATE / 🟢 HEALTHY]** | [Grade F / C / B / A] |
| **Instances Audited** | `[count]` | Total Filestore instances evaluated |
| **Backup Protection Rate** | **[pct]%** | `[protected]/[total]` instances have active backups |
| **Critical & High Security Findings** | `[crit] Critical, [high] High` | Open exports (0.0.0.0/0) or NO_ROOT_SQUASH |
| **PZI Isolation Compliance** | `[pzi_count]/[total]` | Physical Zone Isolation adherence |

2. 优先级发现与修复矩阵

按严重性排序列出发现（CRITICAL $\to$ HIGH $\to$ MEDIUM $\to$ LOW）：

## Priority Findings & Remediation Matrix

| Severity | Instance ID | Category | Finding Description | Remediation Plan |
| :--- | :--- | :--- | :--- | :--- |
| 🚨 **CRITICAL** | `[instance]` | Security | [Description] | [Remediation] |
| ⚠️ **HIGH** | `[instance]` | Disaster Recovery | [Description] | [Remediation] |

3. Filestore 实例清单与合规状态

## Filestore Instance Inventory & Compliance Status

| Instance ID | Location | Tier | Capacity | Reserved CIDR | Write IOPS | Throughput | PZI | PZS | Backups | Latest Backup |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `[id]` | `[loc]` | `[tier]` | `[cap] GiB` | `[cidr]` | `[iops]` | `[tp] MB/s` | ✅ Yes / ❌ No | ✅ Yes / ❌ No / N/A | 🔴 0 / ✅ `[n]` | `[date]` |

4. 自动修复与强制确认门槛

如果发现任何未受保护的实例，请显示注明归属的备份创建 命令，并以明确的确认请求结束：

CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-filestore-auditing)" \
gcloud filestore backups create [INSTANCE]-backup-[DATE] \
    --project=[PROJECT_ID] \
    --instance=[INSTANCE] \
    --file-share=[SHARE] \
    [--instance-zone=[ZONE] | --instance-location=[REGION]] \
    --region=[BACKUP_REGION]

需要确认：是否要我为未受保护的实例创建基线备份？请确认后继续。

关键原因：未经用户明确确认，切勿执行备份创建。执行任何变更或 备份创建命令前，必须严格取得确认，以免造成意外的运营中断、 不必要的资源分配或意外的备份存储费用。

---

参考目录

如需逐步了解内容并深入掌握架构指南，请参阅 以下参考资料：

• 安全与访问治理
• 灾难恢复与备份治理
• 区域隔离（PZI）与可靠性（PZS）
• 审计规则与评分矩阵
• 独立 Python 审计脚本