cloud-network-security

云网络安全

管理 Elastic Cloud Serverless 项目的网络安全策略：通过 IP 过滤器将特定 IP 或 CIDR 加入允许列表，以及通过 VPC 过滤器（AWS PrivateLink）限制流量仅来自特定 VPC 端点。

前置条件： 此技能假设已运行 cloud-setup 技能 — EC_API_KEY 已设置在环境中，并且组织上下文已建立。如果缺少 EC_API_KEY，请指示 Agent 先调用 cloud-setup。不要直接向用户索要 API 密钥。

有关项目创建和第 2 天运维（包括将过滤器与项目关联），请参阅 cloud-create-project 和 cloud-manage-project。有关身份和访问管理（用户、角色、API 密钥），请参阅 cloud-access-management。

有关 API 端点和请求架构的详细信息，请参阅 references/api-reference.md。

术语

此技能使用网络安全作为总称，与 Elastic Cloud UI 的方向一致。底层 API 使用的是流量过滤器 — 你会在端点路径中看到 traffic-filters，在 JSON 字段中看到 traffic_filters。当用户或 Agent 说“流量过滤器”时，指的就是“网络安全策略”。两种过滤器类型分别是 IP 过滤器（类型 ip）和 VPC 过滤器（类型 vpce）。

待完成事项

• 创建 IP 过滤器，将入站流量限制为特定 IP 或 CIDR 网段
• 创建 VPC 过滤器（AWS PrivateLink），将流量限制为特定 VPC 端点 ID
• 列出、检查、更新和删除网络安全策略
• 查询 PrivateLink 区域元数据（服务名称、域名、可用区）
• 将过滤器与 Serverless 项目关联或解除关联（交由 cloud-manage-project 处理）
• 审计组织当前的网络安全态势

前置条件和权限

项目	说明
EC_API_KEY	Cloud API 密钥（由 cloud-setup 设置）。所有操作都需要此密钥。
区域	过滤器按区域划分。创建过滤器时，用户必须指定目标区域。
项目 ID	仅在将过滤器与项目关联时需要（由 cloud-manage-project 处理）。

运行 python3 skills/cloud/network-security/scripts/cloud_network_security.py list-filters，验证 EC_API_KEY 有效后再执行任何操作。

操作所需权限

在 Elastic Cloud Serverless 中执行常见网络安全操作需要以下权限。

操作	所需权限
列出过滤器 / 获取元数据	任意组织成员
创建 / 更新 / 删除过滤器	组织所有者（organization-admin）
将过滤器与项目关联	组织所有者或项目 Admin

此技能不会单独预先检查角色。请尝试执行请求的操作，并由 API 强制执行授权。如果 API 返回授权错误（例如 403 Forbidden），请停止操作并要求用户确认所提供的 API 密钥权限。

手动配置备用方案（cloud-setup 不可用时）

如果单独安装了此技能，且 cloud-setup 不可用，请告知用户在运行命令前手动配置 Cloud 环境变量。切勿要求用户在聊天中粘贴 API 密钥。

变量	必填	说明
EC_API_KEY	是	Elastic Cloud API 密钥（各操作所需角色请参阅上方的权限表）。
EC_BASE_URL	否	Cloud API 基础 URL（默认值：https://api.elastic-cloud.com）。

注意： 如果缺少 EC_API_KEY，或者用户还没有 Cloud API 密钥，请指引用户前往 Elastic Cloud API keys 生成密钥，然后按照以下步骤在本地配置。

首选方法（便于 Agent 使用）：在项目根目录创建 .env 文件：

EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com

所有 cloud/* 脚本都会自动从工作目录加载 .env。

替代方法：直接在终端中导出变量：

export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"

在单独 shell 会话中运行的沙盒 Agent 可能无法获取终端导出的变量，因此使用 Agent 时首选 .env。

分解网络安全需求

当用户用自然语言描述网络安全需求时（例如“将我的搜索项目限制为只能通过办公室 IP 访问”），请先将需求拆分为具体任务，再执行。

步骤 1 — 确定组成要素

组成要素	要回答的问题
筛选器类型	IP 筛选器（公共 IP/CIDR）还是 VPC 筛选器（AWS PrivateLink 端点）？
区域	目标项目位于哪个 AWS 区域？
规则	应允许哪些源 IP、CIDR 或 VPC 端点 ID？
范围	默认应用于所有新项目，还是仅应用于指定项目？
项目	应将此筛选器关联到哪些现有项目？

步骤 2 — 检查现有状态

创建新筛选器前，请先检查现有配置：

python3 skills/cloud/network-security/scripts/cloud_network_security.py list-filters --region us-east-1

筛选器管理： 如果现有筛选器已涵盖相同用途的相同源规则，请重复使用，而不是创建重复筛选器。筛选器按区域划分范围，且可关联到多个项目，因此具有适当规则的单个筛选器即可服务多个项目。如果相同源规则的两个筛选器用途不同（例如，由不同团队管理各自的策略），则可以共存；但为相同用途创建第二个筛选器没有必要。

步骤 3 — 创建筛选器

运行 skills/cloud/network-security/scripts/cloud_network_security.py 中相应的命令。

步骤 4 — 关联项目

筛选器关联通过项目 PATCH 端点管理。使用 cloud-manage-project 关联或取消关联筛选器：

PATCH /api/v1/serverless/projects/{type}/{id}
Body: { "traffic_filters": [{ "id": "filter-id-1" }, { "id": "filter-id-2" }] }

更新关联时，请提供筛选器 ID 的完整列表。未包含在列表中的任何筛选器都会与项目取消关联。

步骤 5 — 验证

执行后，再次列出筛选器或 GET 项目，以确认更改已生效。

IP 筛选器与 VPC 筛选器

方面	IP 筛选器（ip）	VPC 筛选器（vpce）
用途	将公共 IP 地址或 CIDR 块加入允许列表	将流量限制到特定的 AWS VPC 端点 ID
使用场景	办公室 IP、CI/CD 运行器、合作伙伴访问	私有连接，无需暴露到公共互联网
来源格式	IP 地址或 CIDR（例如，203.0.113.0/24）	AWS VPC 端点 ID（例如，vpce-0abc123def456）
网络路径	公共互联网	AWS PrivateLink（私有，绝不会离开 AWS 网络）
前提条件	无	先在 AWS 控制台中创建 VPC 端点和 DNS 记录

关键概念： 默认情况下，Elastic Cloud 接受 AWS 中的私有连接。只有在需要将流量限制到特定 VPC 端点 ID 时，才需要创建 VPC 筛选器。如果只需要私有连接（不进行筛选），请在 AWS 中创建 VPC 端点和 DNS 记录——Elastic Cloud 端无需设置筛选器。

示例

将办公室 IP 范围加入允许列表

提示词：“仅允许来自我们办公室网络 203.0.113.0/24 的流量访问 us-east-1 中的项目。”

python3 skills/cloud/network-security/scripts/cloud_network_security.py create-filter \
  --name "Office IP allowlist" \
  --type ip \
  --region us-east-1 \
  --rules '[{"source": "203.0.113.0/24", "description": "Office network"}]'

然后，使用 cloud-manage-project 将筛选器关联到特定项目。

将流量限制到某个 VPC 端点

提示词：“锁定我的可观测性项目，使其只接受来自我们 VPC 端点的流量。”

python3 skills/cloud/network-security/scripts/cloud_network_security.py create-filter \
  --name "Production VPC" \
  --type vpce \
  --region us-east-1 \
  --rules '[{"source": "vpce-0abc123def456", "description": "Production VPC endpoint"}]'

列出某个区域中的所有筛选器

提示词：“显示 eu-west-1 中的所有网络安全策略。”

python3 skills/cloud/network-security/scripts/cloud_network_security.py list-filters --region eu-west-1

更新筛选器以添加新的 IP

提示词：“将 VPN IP 198.51.100.5 添加到我们现有的办公室筛选器中。”

python3 skills/cloud/network-security/scripts/cloud_network_security.py get-filter --filter-id tf-12345
# Review current rules, then update with the complete rule set:
python3 skills/cloud/network-security/scripts/cloud_network_security.py update-filter \
  --filter-id tf-12345 \
  --body '{"rules": [{"source": "203.0.113.0/24", "description": "Office network"}, {"source": "198.51.100.5", "description": "VPN"}]}'

查询某个区域的 PrivateLink 元数据

提示词：“us-east-1 需要使用哪个 PrivateLink 服务名称？”

python3 skills/cloud/network-security/scripts/cloud_network_security.py get-metadata --region us-east-1

删除未使用的筛选器

提示词：“删除旧的暂存环境 IP 筛选器。”

python3 skills/cloud/network-security/scripts/cloud_network_security.py delete-filter --filter-id tf-67890 --dry-run
# Review what would be deleted, then confirm:
python3 skills/cloud/network-security/scripts/cloud_network_security.py delete-filter --filter-id tf-67890

指南

• 如果未设置 EC_API_KEY，不要提示用户，而是指示 Agent 先调用 cloud-setup。
• 执行破坏性操作（删除过滤器）前，务必先征得用户确认。
• 过滤器按区域划分：在 us-east-1 中创建的过滤器只能与该区域中的项目关联。
• 过滤器管理——复用、限定范围并清理：
  • 创建过滤器前，务必先运行 list-filters，检查是否已有用途相同且包含所需源规则的过滤器。过滤器可以与多个项目关联，因此复用规则合适的过滤器优于创建重复项。
  • 重复过滤器是指用途相同且源规则完全一致的过滤器，而不仅仅是 IP 范围重叠。覆盖不同项目组但使用相同 CIDR 的两个过滤器是合理的。
  • 定期检查未使用的过滤器。如果某个过滤器不再与任何项目关联，请提示用户将其删除，以减少杂乱。
• 更新规则会替换整个规则集。 使用 PATCH 添加规则时，必须包含所有现有规则和新增规则。省略现有规则会将其删除。
• 如果过滤器仍与项目关联，则无法删除。 请先使用 cloud-manage-project 取消关联（通过 PATCH 更新项目，从 traffic_filters 列表中移除该过滤器），然后再删除。
• include_by_default 会自动将该过滤器关联到该区域中的所有新项目。请谨慎使用——它会影响未来创建的每个项目。
• 对于项目关联和取消关联，请委派给 cloud-manage-project 技能。此技能仅管理过滤器定义。
• 有关身份和访问管理（用户、角色、API 密钥），请参阅 cloud-access-management。
• 有关 Elasticsearch 级别的安全（原生用户、角色映射、DLS/FLS），请参阅 elasticsearch-authz。