# TIKit

**Repository Path**: ltinerary/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**: 0
- **Forks**: 3
- **Created**: 2025-07-22
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

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

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

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

## 功能特性

- 支持类似 Dockerfile 的 TrustedImageFile 语法
- 基于 virt-customize 实现镜像定制
- 支持镜像完整性保护（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

# 安装软件包
INSTALL vim
INSTALL git curl

# 上传文件
COPY ./hosts /etc/hosts
COPY ./myapp.conf /etc/myapp.conf

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

# 设置内核参数
SET_KERNEL_CMDLINE console=tty0 console=ttyS0

# 设置 root 密码
SET_ROOTPASSWD 123456

# 设置输出镜像
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/
```

#### RUN
在镜像中执行命令
```
RUN systemctl enable myservice
RUN "echo 'Hello World' > /root/hello.txt"
```

### 快速配置命令

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

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

#### INSTALL
安装软件包（简化的包管理）
```
INSTALL vim
INSTALL "git curl wget"
```

#### SET_ROOTPASSWD
快速设置 root 用户密码
```
SET_ROOTPASSWD mypassword
```

#### SET_KERNEL_CMDLINE
快速设置内核启动参数
```
# 更新模式：添加或更新指定参数
SET_KERNEL_CMDLINE console=tty0 console=ttyS0

# 替换模式：完全替换内核参数
SET_KERNEL_CMDLINE replace quiet splash
```

#### SSH_INJECT
快速注入 SSH 公钥
```
SSH_INJECT root /path/to/public/key
```

#### SELINUX_RELABEL
快速控制 SELinux 重新标记
```
SELINUX_RELABEL false
```

#### 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/               # 工具模块
│   └── command_registry.py # 命令注册器
└── tests/               # 测试文件
```

## 开发指南

### 添加新命令

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

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

### 添加新的 TrustedImageFile 指令

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

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

## 许可证

Apache 2.0

## 贡献

欢迎提交 Issue 和 Pull Request！