cccs/assemblyline-v4-service-base

Assemblyline 4 - 服务基础镜像

镜像概述和主要用途

本镜像为Assemblyline 4服务提供基础功能支持，是构建、运行和测试Assemblyline 4自定义服务的核心依赖。开发者可基于此镜像创建符合Assemblyline 4规范的服务，实现文件分析、威胁检测等功能，并集成到Assemblyline 4系统中。

核心功能和特性

• 标准化服务结构：定义统一的服务文件组织方式，确保服务与Assemblyline 4系统兼容
• 服务清单管理：通过service_manifest.yml配置服务元信息、运行参数、启发规则等核心属性
• Docker集成：提供标准化Dockerfile模板，简化服务容器化构建流程
• 独立测试支持：配套run_service_once.py脚本，支持脱离Assemblyline 4系统独立测试服务功能
• 配置灵活性：支持自定义服务配置参数、提交参数、更新规则等，适应多样化分析需求

使用场景和适用范围

• Assemblyline 4服务开发：供开发者创建自定义服务（如静态分析、动态分析、提取工具等）
• 服务功能测试：在本地环境验证服务逻辑、输出结果及资源占用
• 服务集成部署：作为基础镜像构建服务容器，集成到Assemblyline 4系统中运行

使用方法和配置说明

一、创建Assemblyline服务

1.1 服务文件结构

Assemblyline服务需遵循以下文件结构：

text
assemblyline-service-<服务名称>
│
├── Dockerfile          # 服务容器构建文件
├── <服务名称>.py       # 服务核心代码
└── service_manifest.yml # 服务定义清单文件

各文件功能说明：

• Dockerfile：定义服务容器的构建流程，包括基础镜像、依赖安装、代码复制等
• <服务名称>.py：实现服务核心逻辑，需遵循Assemblyline 4服务接口规范
• service_manifest.yml：配置服务元信息、运行参数、支持的文件类型等，是服务与系统交互的关键配置

1.2 服务清单（service_manifest.yml）

服务清单是服务的核心配置文件，需放置于服务根目录，用于向Assemblyline 4系统提供服务必要信息。完整配置示例及说明如下：

yaml
# 服务名称（必填）
name: ResultSample
# 服务版本（必填）
version: 1
# 服务描述（必填）：支持多行文本，说明服务功能、使用场景等
description: >
  ALv4结果示例服务

  本服务演示如何：
     - 定义服务清单
     - 使用不同类型的结果 section
     - 使用标签
     - 通过启发规则为 section 评分
     - 关联ATT&CK矩阵
     - 使用更新框架
     - 定义提交参数
     - 定义服务配置参数

# 文件类型过滤规则（必填）：
#  - accepts：正则表达式，匹配服务接受的文件类型
#  - rejects：正则表达式，匹配服务拒绝的文件类型
accepts: .*
rejects: empty|metadata/.*

# 服务运行阶段（必填）：取值范围为FILTER, EXTRACT, CORE, SECONDARY, POST（按列表顺序执行）
stage: CORE
# 服务分类（必填）：取值范围为Antivirus, Dynamic Analysis, External, Extraction, Filtering, Networking, Static Analysis
category: Static Analysis

# 是否需要访问文件内容（必填）：
#  - true：服务需读取文件内容
#  - false：服务仅需文件元数据（如哈希、大小、类型等）
file_required: true
# 服务超时时间（必填，秒）：服务执行超过此时长将被判定为超时
timeout: 60
# 是否禁用结果缓存（可选）：true表示每次运行结果均不同，禁用缓存；默认false
disable_cache: false

# 是否默认启用（可选）：true表示服务默认启用；默认true
enabled: true
# 是否调用外部API（可选）：true表示服务需调用Assemblyline基础设施外的API（如VirusTotal）；默认false
is_external: false
# 并发运行许可数（可选）：允许同时运行的服务实例数；默认0（无限制）
licence_count: 0

# 服务配置参数（可选）：自定义键值对，供服务内部使用，支持字符串、整数、列表、布尔等类型
config:
  str_config: value1
  int_config: 1
  list_config: [1, 2, 3, 4]
  bool_config: false

# 提交参数（可选）：用户提交文件时可调整的参数列表
submission_params:
  - default: ""       # 默认值
    name: password    # 参数名称
    type: str         # 参数类型（支持bool, int, str, list）
    value: ""         # 当前值（运行时由用户输入覆盖）
  - default: false
    name: extra_work
    type: bool
    value: false

# 启发规则（可选）：定义服务使用的威胁评分规则
heuristics:
  - description: ResultSample服务的第一个启发规则  # 规则描述
    filetype: pdf                                   # 适用文件类型
    heur_id: AL_RESULTSAMPLE_1                      # 规则唯一ID
    name: 掩码包含PDF                               # 规则名称
    score: 100                                      # 威胁评分（正数表示恶意，0表示中性）
    attack_id: T1001                                # 关联ATT&CK战术ID（可选）
  - description: ResultSample服务的第二个启发规则
    filetype: exe
    heur_id: AL_RESULTSAMPLE_2
    name: 释放可执行文件
    score: 1000
  - description: ResultSample服务的第三个启发规则
    filetype: exe
    heur_id: AL_RESULTSAMPLE_3
    name: 提取信息
    score: 0

# Docker配置（必填）：定义服务容器的资源配置
docker_config:
  image: cccs/assemblyline-service-resultsample:latest  # 容器镜像名称
  cpu_cores: 1.0                                       # CPU核心数
  ram_mb_min: 128                                      # 最小内存（MB）
  ram_mb: 256                                          # 最大内存（MB）

# 更新配置（可选）：定义服务规则/数据自动更新逻辑
update_config:
  sources:                                             # 更新源列表：指定文件下载地址及本地文件名
    - uri: https://file-examples.com/wp-content/uploads/2017/02/zip_2MB.zip
      name: sample_2mb_file
    - uri: https://file-examples.com/wp-content/uploads/2017/02/zip_5MB.zip
      name: sample_5mb_file
  update_interval_seconds: 300                         # 更新间隔（秒）
  generates_signatures: false                          # 是否生成系统签名（true表示更新文件用于签名生成）

1.3 Dockerfile编写规范

服务容器需通过Dockerfile构建，需遵循以下要求：

• 基础镜像必须为cccs/assemblyline-v4-service-base:latest
• 必须设置SERVICE_PATH环境变量（指定服务入口类路径）
• 安装服务依赖（系统包或Python包）
• 将服务代码复制到/opt/al/al_service/目录

示例Dockerfile：

dockerfile
FROM cccs/assemblyline-v4-service-base:latest

# 设置服务入口路径（格式：模块名.类名）
ENV SERVICE_PATH result_sample.ResultSample

# 切换至root用户安装依赖（基础镜像默认运行用户为assemblyline）
USER root

# 安装系统依赖（合并命令减少镜像层数）
RUN apt-get update && apt-get install -y my_debian_apt_dependency_package && rm -rf /var/lib/apt/lists/*

# 安装Python依赖（--user指定用户目录，避免权限问题）
RUN pip install --no-cache-dir --user my_pip_dependency && rm -rf ~/.cache/pip

# 切换回assemblyline用户，确保服务非root运行
USER assemblyline

# 复制服务代码至服务目录
WORKDIR /opt/al_service
COPY assemblyline_result_sample_service .

二、测试Assemblyline服务

可使用run_service_once.py脚本在独立模式下测试服务，无需部署完整Assemblyline 4系统，仅需安装Assemblyline Python库。

2.1 开发环境搭建

注意：以下环境配置仅在Ubuntu 20.04测试通过。

1. 安装系统依赖：

   shell
   sudo apt-get install build-essential libffi-dev python3.7 python3.7-dev python3-pip automake autoconf libtool
   

2. 安装Assemblyline v4服务包：

   shell
   pip install --no-cache-dir --user assemblyline-v4-service
   

3. 将服务开发目录路径添加至PYTHONPATH环境变量（如/home/ubuntu/assemblyline-v4-service）：

   shell
   export PYTHONPATH="${PYTHONPATH}:/home/ubuntu/assemblyline-v4-service"
   

2.2 使用run_service_once.py脚本测试

测试步骤

1. 切换至服务根目录：

   shell
   cd assemblyline-service-<服务名称>
   

2. 执行测试命令，格式：

   shell
   python3.11 -m assemblyline_v4_service.dev.run_service_once <服务入口路径> <待分析文件路径>
   

   • <服务入口路径>：服务代码中入口类的完整路径（如result_sample.ResultSample）
   • <待分析文件路径>：本地测试文件的绝对路径

3. 测试结果（result.json及提取/补充文件）将输出至待分析文件所在目录的<文件名>_<服务名称>子目录中。

测试示例（以ResultSample服务为例）

1. 切换至服务根目录：

   shell
   cd assemblyline_result_sample_service
   

2. 执行测试命令：

   shell
   python3.11 -m assemblyline_v4_service.dev.run_service_once assemblyline_result_sample_service.result_sample.ResultSample /home/ubuntu/testfile.doc
   

3. 结果输出路径：/home/ubuntu/testfile_resultsample（包含result.json及提取文件）

配置参数说明

服务清单关键配置项

Dockerfile环境变量