使用 Terraform 管理 Jamf Protect：Jamf Protect Provider

在我们之前的文章中，使用 Terraform 管理 Jamf 配置：简介，我们介绍了基础设施即代码的基本原理，以及如何开始使用 Terraform 和 Jamf Pro。如果您还没有阅读过，我们建议您从那里开始，因为它涵盖了 Terraform 的基础知识、安装、项目结构和状态管理。

这次我们将重点放在 Jamf Protect 上。我们构建了一个专用的 Terraform provider，让您可以以代码的形式管理 Jamf Protect 产品配置——包括计划、操作配置、异常集等等。

为什么为 Jamf Protect 提供专用 provider？

就像 Jamf Pro 一样，Jamf Protect 本身就是一个产品，也是 Jamf Platform 产品系列的一部分。它有自己的 API 表面（基于 GraphQL）以及与 Jamf Pro 和其他 Jamf Platform 微服务（例如 Blueprints 和 Compliance Benchmarks）不同的资源集。端点安全计划、遥测配置和可移动存储策略等都存在于 Jamf Protect 中，需要他们自己的 provider 来正确管理。

如果您一直通过控制台管理 Jamf Protect 配置，您会知道跨租户重新创建设置或回滚更改意味着需要大量手工操作。使用此 provider，您的整个 Jamf Protect 配置可以存储在 Git 中、经过代码审查，并在各个环境中一致地应用。

涵盖的内容有哪些？

该 provider 随附 16 个资源和 18 个数据源。以下是它涵盖的一些关键领域：

威胁检测和防御

自定义防御列表 - 按 Team ID、文件哈希、CDHash 或签名 ID 的允许/阻止列表。
异常集 - 分析和端点安全控制的异常。

端点配置

计划 - 完整的端点安全配置，包括威胁防御模式、通信协议、报告间隔和设备信息收集。
操作配置 - 警报数据丰富化和报告端点（HTTP、Kafka、云）。
遥测 - 事件和日志收集：安全事件、身份验证、文件完整性监控、性能指标等。

设备控制

可移动存储控制集 - USB 设备策略，支持按供应商 ID、产品 ID 或序列号覆盖。

操作设置

数据转发 - 将数据路由到 Amazon S3、Microsoft Sentinel 或云端点。
数据保留 - 租户范围的保留策略。
变更管理 - 配置冻结。
统一日志筛选器 - 使用 NSPredicate 筛选器进行 macOS 统一日志收集。

访问控制

用户、组、角色和 API 客户端 - 以代码形式管理访问和权限。

所有资源都支持完整的 CRUD 操作和 terraform import。

值得注意的是，jamfprotect_change_management、jamfprotect_data_forwarding 和 jamfprotect_data_retention 是单例资源——它们管理租户范围的设置，而不是单独可识别的对象。

入门

如果您遵循了简介文章的步骤，您应该已经安装了 Terraform 并对项目结构有了基本的了解。这里的步骤类似。

1. 在 Jamf Protect 中创建 API 客户端

在您的 Jamf Protect 控制台中转到 Administration > API Clients，并创建一个新的 API 客户端，该客户端具有管理所需资源所需的权限。

2. 配置 provider

将 provider 添加到您的 Terraform 配置：

terraform {
  required_providers {
    jamfprotect = {
      source  = "Jamf-Concepts/jamfprotect"
      version = "~> 0.1.0"
    }
  }
}

provider "jamfprotect" {
  url           = "https://your-tenant.protect.jamfcloud.com"
  client_id     = var.jamfprotect_client_id
  client_secret = var.jamfprotect_client_secret
}

如果您更喜欢保持 provider 块的简洁性，也可以使用环境变量：

export JAMFPROTECT_URL="https://your-tenant.protect.jamfcloud.com"
export JAMFPROTECT_CLIENT_ID="your-client-id"
export JAMFPROTECT_CLIENT_SECRET="your-client-secret"

与 Jamf Pro provider 一样，确保这些凭证不会进入您的 Git 存储库。使用 terraform.tfvars 文件并将其添加到您的 .gitignore。

3. 定义您的资源

以下是一个操作配置示例，定义收集的数据以及警报的发送位置：

resource "jamfprotect_action_configuration" "default" {
  name = "Default Action Config"

  alert_data_collection = {
    binary_included_data_attributes                = ["Sha256", "Signing Information"]
    download_event_included_data_attributes        = ["File"]
    file_included_data_attributes                  = ["Sha256", "Signing Information"]
    file_system_event_included_data_attributes     = ["File", "Process"]
    gatekeeper_event_included_data_attributes      = ["Blocked Process"]
    group_included_data_attributes                 = ["Name"]
    keylog_register_event_included_data_attributes = ["Source Process"]
    process_included_data_attributes               = ["Args", "Signing Information", "Binary", "User", "Parent"]
    process_event_included_data_attributes         = ["Process"]
    screenshot_event_included_data_attributes      = ["File"]
    synthetic_click_event_included_data_attributes = ["Process"]
    user_included_data_attributes                  = ["Name"]
  }

  jamf_protect_cloud_endpoint = {
    collect_alerts = ["low", "medium", "high"]
    collect_logs   = ["telemetry"]
  }
}

一个阻止除已批准加密驱动器外的所有 USB 存储的可移动存储策略：

resource "jamfprotect_removable_storage_control_set" "strict" {
  name                               = "Strict USB Policy"
  description                        = "Block all removable storage except encrypted devices."
  default_permission                 = "Prevent"
  default_local_notification_message = "Removable storage devices are not permitted."

  override_encrypted_devices = [
    {
      permission = "Read and Write"
    },
  ]
}

一个异常集，用于从威胁防御中排除已知的 IT 管理工具：

resource "jamfprotect_exception_set" "it_admin_tools" {
  name        = "IT Admin Tools"
  description = "Exceptions for trusted IT administration software."

  exceptions = [
    {
      type     = "Override Endpoint Threat Prevention"
      sub_type = "Process"
      rules = [
        {
          rule_type = "Team ID"
          value     = "EQHXZ8M8AV"
        },
      ]
    },
  ]
}

您也可以使用数据源来引用现有资源，而不是创建新资源。这里我们查找租户中已存在的 Jamf 托管默认异常集：

data "jamfprotect_exception_sets" "all" {}

locals {
  jamf_managed_default_exceptions = [
    for es in data.jamfprotect_exception_sets.all.exception_sets :
    es if es.name == "Jamf Managed Default Exceptions"
  ][0]
}

然后可以将这些资源组合在一个计划中，该计划是部署到端点的配置：

resource "jamfprotect_plan" "endpoint_security" {
  name        = "Endpoint Security Plan"
  description = "Standard endpoint security plan with threat prevention."

  action_configuration          = jamfprotect_action_configuration.default.id
  removable_storage_control_set = jamfprotect_removable_storage_control_set.strict.id

  exception_sets = [
    jamfprotect_exception_set.it_admin_tools.id,
    local.jamf_managed_default_exceptions.uuid,
  ]

  endpoint_threat_prevention = "Block and report"
  advanced_threat_controls   = "Block and report"
  tamper_prevention          = "Block and report"

  reporting_interval            = 1440
  compliance_baseline_reporting = true
  auto_update                   = true
  communications_protocol       = "MQTT:443"
  log_level                     = "Error"

  report_architecture  = true
  report_hostname      = true
  report_serial_number = true
  report_model_name    = true
  report_os_version    = true
}

该计划通过其 ID 引用其他资源，因此 Terraform 理解依赖关系图并以正确的顺序创建所有内容。

4. 应用您的配置

您在简介中学到的相同命令适用于此处：

terraform init       # 初始化并下载 provider
terraform plan       # 查看将创建、更改或销毁的内容
terraform apply      # 应用更改（系统会要求您确认）

将现有租户纳入管理

如果您已有一个具有现有配置的 Jamf Protect 租户，您不需要从头开始。provider 中的每个资源都支持 terraform import，因此您可以在不重新创建资源的情况下将现有资源纳入 Terraform 管理。

使用 Terraform query 发现现有资源

如果您运行的是 Terraform 1.14+，该 provider 支持列出资源——这是一项新功能，允许您直接从 Terraform 查询现有基础设施。这对于在导入之前发现租户中已有的内容很有用。

创建查询文件（例如 discover.tfquery.hcl）：

list "jamfprotect_plan" "all" {
  provider         = jamfprotect
  include_resource = true
}

list "jamfprotect_exception_set" "custom" {
  provider = jamfprotect

  config {
    name_prefix = "Custom"
  }
}

然后运行：

terraform query -generate-config-out=generated.tf

Terraform 将查询您的 Jamf Protect 租户，返回匹配的资源及其 ID，并将资源块和导入块都生成到 generated.tf。provider 中的所有列表资源都在 config 块中支持 name_prefix 筛选器（或用户的 email_prefix），以便您可以将结果范围缩小到您正在寻找的内容。

除了以下单例资源外，所有资源类型都支持列表查询：

jamfprotect_change_management
jamfprotect_data_forwarding
jamfprotect_data_retention

导入资源

获得所需的 ID 后，您可以使用导入块将其纳入管理。使用 Terraform 1.5+：

import {
  to = jamfprotect_plan.endpoint_security
  id = "your-plan-uuid"
}

运行 terraform plan 为导入的资源生成配置，根据需要精化它，从那时起它就作为代码进行管理。有关批量导入资源的更多信息，请参阅 HashiCorp 的批量导入文档。

与其他 Jamf provider 配合使用

此 provider 设计用于与 Jamf 生态系统中的其他 Terraform provider 配合使用。您可以将其与以下一起使用：

Jamf Platform Provider - 用于通过 Jamf Platform API 管理 Jamf Platform 中的资源（例如 Blueprints 和 Compliance Benchmarks）。
Deployment Theory Jamf Pro Provider - 用于通过其 Classic 和 Pro API 管理 Jamf Pro 产品中的资源。

使用这些 provider，您可以从单个 Terraform 项目以代码的形式管理您的完整 Jamf 环境。

背景

此 provider 最初由 James Smith (@smithjw) 创建，他慷慨地将源代码捐赠给了 Jamf Concepts。感谢 James 提供的基础工作，这使得这一切成为可能。

该 provider 在 MPL 2.0 许可证下是开源的，基于 HashiCorp 的 Terraform Plugin Framework（Protocol v6）构建。它包含贯穿始终的单元测试和验收测试，我们欢迎贡献——错误报告、功能请求和拉取请求。

接下来是什么

这是 v0.1.x 版本，我们正在积极收集反馈。如果您尝试使用它，我们很想听听什么有效以及什么无效。在 GitHub 存储库上提出问题或在 Jamf Nation 上与我们联系。

指南