# TIKit

**Repository Path**: nanhu-lab/tikit

## Basic Information

- **Project Name**: TIKit
- **Description**: Trusted Image Kit（TIKit） 
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 3
- **Created**: 2025-07-02
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Trusted Image Kit - 机密虚拟机可信镜像定制工具

Trusted Image Kit 集合了用于机密虚拟机镜像定制和度量的工具：

trustimage build 实现对qcow2格式的机密虚拟机镜像定制，可根据类似 Dockerfile 的配置文件来构建和定制虚拟机镜像。

trustimage measure 实现对镜像的预度量，生成镜像相关的度量值（待实现）。

## 功能特性

- 支持类似 Dockerfile 的 TrustedImageFile 语法
- 基于 virt-customize和RUN、COPY、RESIZE命令实现镜像定制
- 支持镜像完整性保护（DM_VERITY）
- 支持内核命令行参数定制

## 安装

### 系统依赖项

在安装 TrustImage 之前，需要先安装以下系统依赖：

```bash
# Ubuntu/Debian 系统
sudo apt-get update
sudo apt-get install libguestfs-tools cryptsetup-bin qemu-utils pipx

# CentOS/RHEL 系统
sudo yum install libguestfs-tools cryptsetup qemu-img

# 或使用 dnf (较新版本)
sudo dnf install libguestfs-tools cryptsetup qemu-img
```

### 安装 TrustImage

```bash
# 从源码安装
git clone https://gitee.com/nanhu-lab/tikit.git
cd tikit
pipx install .

# 或使用虚拟环境（推荐开发模式）
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt  # 或 pip install requests tqdm

# 直接运行
python run.py --help
```

**Python依赖项：**
- `requests` - 用于在线下载镜像
- `tqdm` - 用于显示下载进度

## 快速开始

### 1. 创建 TrustedImageFile

创建一个名为 `TrustedImageFile` 的配置文件：

```
# 使用在线下载的Ubuntu镜像
FROM ubuntu:24.10

# 上传文件
COPY ./hosts /etc/hosts
COPY netplan.yaml /etc/netplan/01-network-manager-all.yaml

# 执行命令
RUN echo "Hello World" > /root/hello.txt

# 自定义镜像主分区扩容：增加 X GB 或设为 X GB 总容量（二选一）
RESIZE +10G
RESIZE 50G

# 设置 DM_VERITY
DM_VERITY rootfs salt=8f7b6495d922d956ce840ebb8a11883250dc90b8a5765630b3f6393c6a4cb51f

# 设置输出镜像
OUTPUT qcow2 my-custom-image
```

### 2. 构建镜像

```bash
# 使用默认配置文件构建
trustimage build

# 指定配置文件和输出目录
trustimage build -f TrustedImageFile -o output_dir

# 显示详细日志
trustimage build -v
```

## 示例

项目提供了完整的示例来帮助您快速上手 TrustImage。

### Ubuntu 示例

在 `example/ubuntu/` 目录中提供了一个完整的 Ubuntu 镜像定制示例：

```bash
# 进入示例目录
cd example/ubuntu/

# 查看示例配置
cat TrustedImageFile
```

#### 运行示例

```bash
# 在示例目录中构建镜像
cd example/ubuntu/
trustimage build

# 构建完成后会生成以下文件：
# - my-custom-image.qcow2: 主镜像文件
```


## TrustedImageFile 语法参考

### 类 Dockerfile 命令

与 Dockerfile 语法兼容，遵循类似的语义：

#### FROM
指定基础镜像文件，支持本地文件路径和在线下载

**本地镜像：**
```
FROM base-image.qcow2
FROM /path/to/ubuntu-20.04.img
```

**在线镜像下载：**
```
FROM ubuntu:24.10
FROM ubuntu:22.04
```

支持的在线镜像：
- **Ubuntu**: `ubuntu:版本号` 格式，如 `ubuntu:24.10`、`ubuntu:22.04`
- 镜像会自动下载到 `~/.trustimage/cache/` 目录进行缓存
- 会根据系统架构自动选择对应的镜像（amd64/arm64等）

**下载地址解析示例：**
- `ubuntu:24.10` → `https://cloud-images.ubuntu.com/releases/24.10/release/ubuntu-24.10-server-cloudimg-amd64.img`

#### COPY
复制文件或目录到镜像
```
COPY ./local-file.txt /etc/config.txt
COPY ./config-dir /etc/myapp/
```
**注意：** 如果目标路径不是以 `/` 开头的绝对路径，工具会自动将其视为相对于镜像根目录（`/`）的路径。
```
示例：
# "opt/myapp/" 会被工具转换为绝对路径: "/opt/myapp"
COPY ./app.conf opt/myapp/

# 目标 "." 会被工具转换为绝对路径: "/"
COPY ./init_script.sh .
```

#### RUN
在镜像中执行命令
```
RUN systemctl enable myservice
RUN "echo 'Hello World' > /root/hello.txt"
```
> **基础镜像配置限制与建议**
>
> 为确保构建过程中 SSH 连接与网络通畅，本工具会在构建期间注入高优先级的临时配置文件（以 `00-trustimage-builder` 命名，建完成后自动清理），
> 在使用自定义基础镜像时遵守以下规则，以避免配置冲突导致构建失败：
>
> **1. SSH 配置 (`/etc/ssh/sshd_config.d/`)**
> *   请勿在 /etc/ssh/sshd_config.d/ 中预置文件名排序在 00- 之前（如 00-aaa.conf）且包含限制登录（如 PubkeyAuthentication no）的配置，否则工具可能无法连接虚拟机
> *   **示例**：
>     ```text
>     /etc/ssh/sshd_config.d/
>     ├── 00-aaa.conf                 <-- [危险] 排在前面！此处禁止了登录，后续配置均无效
>          PubkeyAuthentication no
>          PasswordAuthentication no
>     └── 00-trustimage-builder.conf  <-- [失效] 工具注入的允许登录配置，因排序靠后被忽略
>     ```
> *   **建议**：自定义SSH配置文件请以 `10-` 或 `50-` 开头（如 `50-security.conf`）
>
> **2. 网络配置 (`/etc/systemd/network/`)**
> *   请勿在 /etc/systemd/network/ 中预置文件名排序在 00-trustimage-builder 之前的配置文件（如 00-aaaa.network），否则可能导致构建环境断网
> *   **示例**：
>     ```text
>     /etc/systemd/network/
>     ├── 00-aaa.network                 <-- [危险] 排在前面！若此处任意配置，很有可能会导致断网
>          [Match]
>           Name=*
>          [Network]
>           DHCP=no
>           Address=169.254.255.254/16
>           DNS=0.0.0.0
>     └── 00-trustimage-builder.network  <-- [失效] 工具注入的临时构建配置，因排序靠后而被忽略
>     ```
> *   **建议**：自定义网络配置文件请以 `10-` 或更大数字开头（如 `10-eth0.network`）

#### RESIZE
在镜像中自定义镜像主分区扩容：增加 X GB 或设为 X GB 总容量（二选一）
```
RESIZE +10G
RESIZE 50G
```





### 快速配置命令

TrustImage 特有的快速配置命令，简化常见的虚拟机配置任务：

#### OUTPUT
设置输出镜像格式和名称
```
OUTPUT qcow2 my-custom-image
OUTPUT raw my-image
```

#### DM_VERITY
快速启用 dm-verity 完整性保护
```
# 使用默认设置
DM_VERITY rootfs

# 指定 salt
DM_VERITY rootfs salt=mysalt
```



## 高级功能

### DM_VERITY 完整性保护

TrustImage 支持为镜像添加 dm-verity 完整性保护，确保运行时文件系统的完整性：

- 自动创建哈希分区
- 配置 initramfs 钩子
- 更新内核命令行参数
- 生成验证信息


## 项目结构

```
trustimage/
├── main.py                  # 主入口文件
├── cli.py                   # 命令行接口
├── core/                    # 核心功能模块
│   ├── builder.py           # 镜像构建器
│   ├── parser.py            # 配置文件解析器
│   ├── dm_verity.py         # DM_VERITY 实现
│   ├── kernel_cmdline.py    # 内核参数管理
│   └── version.py           # 版本信息
├── commands/                # 命令实现
│   └── build.py             # build 命令
├── utils/                   # 工具模块
|   ├── adapters.py          # 发行版适配器
│   ├── command_registry.py  # 命令注册器
│   ├── network.py           # 生成虚拟设备标识
│   ├── qemu_runner.py       # 虚拟机的启动与停止
│   └── ssh_utils.py         # SSH远程操作管理器
|  
└── tests/                   # 测试文件
```

## 开发指南

### 添加新命令

TrustImage 使用插件架构，可以方便地扩展新的命令：

1. 在 `trustimage/commands/` 目录下创建新的命令文件
2. 实现 `setup_parser()` 和 `execute()` 函数
3. 命令会被自动发现和注册

### 添加新的 TrustedImageFile 指令

要添加新的配置文件指令：

1. 在 `CommandType` 枚举中添加新类型
2. 在 `ImageBuilder` 中实现对应的处理方法
3. 在解析器中添加特殊处理逻辑（如需要）


## 许可证

Apache 2.0

## 贡献

欢迎提交 Issue 和 Pull Request！