定制内容部署

本页说明如何把自定义 Module、Playbook、SIEM YAML 和 Python 依赖交付到 Docker Compose 部署。首次安装 ASP 请先完成部署。

1. 定制目录

Compose 发布包把宿主机的 custom/ 挂载到后端容器。按用途放置文件：

路径	用途
custom/modules/*.py	自定义 Module。
custom/playbooks/*.py	自定义 Playbook。
custom/data/modules/<module_slug>/raw_alert_*.json	Module 开发调试样本。
custom/data/siem/*.yaml	自定义 SIEM YAML。
custom/data/playbooks/<playbook_slug>/*.md	自定义 Playbook Prompt。
custom/requirements.txt	Module、Playbook 或公共 helper 所需的额外 Python 包。

init.sh 会创建空的 custom/ 目录结构和 custom/requirements.txt 模板。源码仓库中的 backend/custom/ 仅用于本地开发参考，不会随发布包交付示例内容。

2. 安装 Python 依赖

把额外依赖写入：

custom/requirements.txt

在现有 Compose 部署中安装：

docker compose run --rm asp-custom-deps

依赖会安装到 /opt/asp/custom-packages，该目录由 custom-python-packages Docker named volume 持久化，并挂载到全部后端服务。

如需指定 Python package index，把参数放在服务名后：

docker compose run --rm asp-custom-deps --index-url https://pypi.org/simple

服务名后的参数会传给 uv pip install，例如：

• --extra-index-url https://packages.example.com/simple：增加额外的 Python package index。
• --upgrade：升级已安装的依赖。

如需通过代理安装依赖，把代理环境变量传入容器：

docker compose run --rm \
  -e HTTP_PROXY=http://proxy.example:8080 \
  -e HTTPS_PROXY=http://proxy.example:8080 \
  asp-custom-deps

3. 管理自定义变量

Admin 可以在 Custom > Variables 中管理自定义 Module 和 Playbook 使用的变量。变量 key 只能包含大写字母、数字和下划线，并且创建后不能修改。

创建变量时必须选择 Type：

Type	Python 返回类型	Value 编辑方式
String	str	文本输入框
Integer	int	整数输入框
Float	float	数字输入框
Boolean	bool	开关
List	list	JSON 代码编辑器
Dictionary	dict	JSON 代码编辑器

List 和 Dictionary 支持嵌套的 JSON 值。编辑器提供行号、语法高亮、括号匹配、代码折叠和 Format；保存时会校验 JSON 语法和顶层类型。Dictionary 不保证 key 顺序，需要有序数据时请使用 List。

String 不能为空。Integer 必须是 JavaScript 安全整数，Float 必须是有限数值；Boolean 的 false、数字 0、空 List 和空 Dictionary 都是有效值。单个 Value 最大为 65,536 UTF-8 bytes，List 和 Dictionary 最多嵌套 20 层。

只有 String 可以标记为 Secret。Secret 会在普通 Admin API 响应和编辑表单中隐藏，Admin 需要通过 Reveal 操作查看；修改为其他 Type 时，必须同时关闭 Secret 并重新输入 Value。修改任意变量的 Type 都会清空原 Value，并要求确认。

在自定义代码中通过基类读取变量：

class Playbook(BasePlaybook):
    def run(self):
        base_url = self.get_variable("EDR_BASE_URL")
        token = self.get_variable("EDR_API_TOKEN")
        verify_tls = self.get_variable("EDR_VERIFY_TLS")
        headers = self.get_variable("EDR_HEADERS")

        if base_url is None or token is None:
            raise ValueError("EDR custom variables are not configured.")

        if verify_tls is None:
            verify_tls = True
        if headers is None:
            headers = {}

BaseModule 的读取方式相同：

class Module(BaseModule):
    NAME = "EDR alert processor"
    STREAM_NAME = "EDR-Alerts"

    def run(self, message):
        base_url = self.get_variable("EDR_BASE_URL")
        token = self.get_variable("EDR_API_TOKEN")
        if base_url is None or token is None:
            raise ValueError("EDR custom variables are not configured.")

        # 使用 message、base_url 和 token 处理告警。

BasePlaybook.get_variable() 和 BaseModule.get_variable() 每次都会读取数据库中的当前值，并根据 Type 返回对应的 Python 原生类型，不需要自行解析 JSON。变量不存在、被禁用或已删除时返回 None。

使用 is None 判断变量是否存在

false、0、[] 和 {} 都是合法值。请使用 value is None 判断变量是否缺失，不要使用 if not value。

Secret 不会加密存储

Secret 只会在普通 Admin API 和列表中隐藏，数据库中仍保存明文。数据库管理员和拥有数据库备份的人可以读取这些值。请只安装可信的自定义代码，不要把 Secret 写入日志、任务摘要、Enrichment 或异常信息。

4. 应用变更

只修改 Module、Playbook 或 SIEM YAML 时，在 Custom Console 对应 Tab 中执行 Refresh / Validate。

修改 custom/requirements.txt 或公共 helper module 后，重新安装依赖并重启使用定制代码的服务：

docker compose run --rm asp-custom-deps
docker compose restart asp-web asp-worker-module asp-worker-playbook
./scripts/doctor.sh

5. Compose 覆盖配置

init.sh 会在文件不存在时创建 compose.override.yaml。Docker Compose 会自动将它与官方 compose.yaml 合并。

• 密码、端口和镜像等已有设置写入 .env。
• 定制代码需要增加 volume、环境变量、command 或其他服务级配置时，编辑 compose.override.yaml。
• 不要直接修改官方 compose.yaml。

例如，为 Web 服务增加定制环境变量：

services:
  asp-web:
    environment:
      EXAMPLE_SETTING: value

修改后重新创建受影响的容器：

docker compose up -d
./scripts/doctor.sh

发布包不包含 .env、compose.override.yaml 和 custom/，解压升级时会保留这些内容。升级流程见升级。

下一步

• Custom Console — 查看定制定义的加载状态并执行刷新校验。
• Module 开发 — 编写 Redis Stream 消费逻辑。
• Playbook 开发 — 编写 Case 触发的自动化任务。
• SIEM YAML — 维护 Harness Agent 可查询的索引字段定义。
• 重启 & 运维 — 查看服务状态和日志。