GrapheneOS/AttestationServer
GitHub: GrapheneOS/AttestationServer
配合 GrapheneOS Auditor 应用使用的远程证明服务器，用于持续监控 Android 设备的系统完整性并通过邮件告警异常状态。
Stars: 157 | Forks: 55
请参阅 https://attestation.app/about 上的项目概述。
## 安装指南
这是设置 attestation 服务器的通用指南。
同步 libs/ 目录中预构建的 sqlite4java 子模块。
你需要使用本仓库中 nginx 目录下的 nginx 配置来设置 nginx。
你需要根据你的域名对其进行调整。示例配置依赖于 certbot、
[nginx-rotate-session-ticket-keys](https://github.com/GrapheneOS/nginx-rotate-session-ticket-keys)、
和 [certbot-ocsp-fetcher](https://github.com/tomwassenberg/certbot-ocsp-fetcher)。设置 Web 服务器不在本指南的范围之内。
开发机器上的 deploy 和 process 脚本需要安装以下依赖项：
```
rsync, zopfli, parallel, yajl, brotli, nginx-mod-brotli, python3, python-pip, nodejs, npm, libxml2
```
`validatornu` 必须手动从[这里](https://github.com/validator/validator/releases/tag/20.6.30)获取 (vnu.linux.zip)。将其解压到
AttestationServer 的同一目录下，并使用 sed 将 `process-static` 中的二进制路径从
`validatornu` 更改为 `vnu-runtime-image/bin/vnu`：`sed -i
's+validatornu+vnu-runtime-image/bin/vnu+g' process-static`
安装无头 Java 25 运行时环境。基于 Debian 的发行版上的软件包名称为
`openjdk-25-jre-headless`，Arch Linux 上为 `jre-openjdk-headless`。安装 `sqlite3` 以便
为数据库设置电子邮件配置。
以 root 身份在服务器上执行：
```
useradd -m -s /bin/bash -b /var/lib attestation
mkdir -p /opt/attestation/deploy_{a,b}
ln -s /opt/attestation/deploy_a /opt/attestation/deploy
mkdir -p /srv/attestation.app_{a,b}
ln -s /srv/attestation.app_a /srv/attestation.app
```
为 attestation 用户设置 ssh `authorized_keys`。
将 `attestation.service` 复制到 `/etc/systemd/system/attestation.service`。
在你的开发机器上，你需要将 deploy 脚本中的 `remote` 变量更改为你的服务器。你还需要将 AttestationServer.java 中的
[DOMAIN](https://github.com/GrapheneOS/AttestationServer/blob/df53e39706fdc6247ce497cb0776bf77fe931085/src/main/java/app/attestation/server/AttestationServer.java#L85)
更改为你的服务器，以及[应用签名密钥](https://github.com/GrapheneOS/AttestationServer/blob/df53e39706fdc6247ce497cb0776bf77fe931085/src/main/java/app/attestation/server/AttestationProtocol.java#L157-L162)和[应用 ID](https://github.com/GrapheneOS/AttestationServer/blob/df53e39706fdc6247ce497cb0776bf77fe931085/src/main/java/app/attestation/server/AttestationProtocol.java#L154-L156)。
然后部署 attestation 服务器和静态内容：
```
npm i
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./deploy-server
./deploy-static
```
以 root 身份在服务器上，启用并启动 attestation 服务器：
```
systemctl enable attestation
systemctl start attestation
```
默认情况下，服务器将监听 `[::1]:8080`，这[是可以更改的](https://github.com/GrapheneOS/AttestationServer/blob/df53e39706fdc6247ce497cb0776bf77fe931085/src/main/java/app/attestation/server/AttestationServer.java#L320)。
## 电子邮件警报配置
为了发送电子邮件警报，AttestationServer 需要配置有效的 SMTP 服务器凭据。该配置存储在数据库的 `Configuration` 表中，可以在服务器运行时安全地修改，以便在下一个电子邮件警报周期生效。
对于远程邮件服务器，仅支持具有有效证书的 SMTPS（基于 TLS 的 SMTP）。故意不支持 STARTTLS，因为除非强制加密，否则它不太安全，而既然如此，无论如何使用 SMTPS 都更有意义。用户名也必须是用于发送电子邮件的完整地址。
例如，进行初始配置：
```
sqlite3 attestation.db "INSERT INTO Configuration VALUES ('emailUsername', 'attestation'), ('emailPassword', ''), ('emailHost', 'mail.grapheneos.org'), ('emailPort', '465'), ('emailFrom', 'noreply@attestation.app')"
```
默认情况下，`attestation.service` 单元仅允许服务通过 `localhost` 进行通信，因此在使用远程邮件服务器时，需要删除 `IPAddressDeny`/`IPAddressAllow` 配置，或者对其进行扩展以包含你的 DNS 服务器和邮件服务器的 IP 地址。
### 处理滥用行为
[`src/main/java/app/attestation/server/AttestationServer.java`](https://github.com/GrapheneOS/AttestationServer/blob/df53e39706fdc6247ce497cb0776bf77fe931085/src/main/java/app/attestation/server/AttestationServer.java#L92-L94) 中的 `emailBlacklistPatterns` 数组可用于使用正则表达式将电子邮件地址列入黑名单。我们计划将其移至数据库中的表，以便可以在不修改源代码、重新构建和重新部署的情况下动态配置它。目前，添加此项是为了快速提供一种应对滥用的方法。
## Auditor 应用的 API
### 二维码
扫描的二维码包含以空格分隔的纯文本值：` `。`subscribeKey` 应被视为不透明字符串，而不是假设为 base64 编码。未来可能会添加其他字段。
### /auditor/挑战
* 请求方法：POST
* 请求头：n/a
* 请求体：n/a
* 响应体：
返回与 Auditor 应用二维码格式相同的标准质询消息。该质询只能使用一次，并在 1 分钟后过期。
服务器质询索引总是被置零，应改为使用 userId。
### /auditor/验证
* 请求方法：POST
* 请求头：
对于未配对的 attestation，`Authorization` 请求头需要设置为 `Auditor `。如果 subscribeKey 匹配，这也适用于已配对的 attestation，但应将其设置为 `Auditor ` 以允许 subscribeKey 轮换。
* 请求体：
与 Auditor 应用二维码格式相同的标准 attestation 消息。
* 响应体：
返回带有 `verifyInterval` 字段的 JSON。
## 日志
日志通过 stderr 写入 journald。日志规范：
emerg：文件系统或数据库损坏
alert：服务完全无法运行
crit：服务部分无法运行
error：特定请求的服务端错误
warning：登录失败、由客户端触发的意外错误，以及缺少用于完整功能（如发送警报）的设置
info：与安全相关的事件，如登录、由客户端触发的预期错误以及状态记录
debug：未在生产环境中使用
标签：Auditor, Certbot, Debian, GrapheneOS, HTTPS, JS文件枚举, MITM代理, Nginx, OpenJDK, SQLite, SSL/TLS, 前端优化, 域名枚举, 安卓设备验证, 服务器部署, 特权提升, 目录枚举, 移动安全, 篡改检测, 网络安全, 自动化部署, 设备完整性监控, 证书管理, 证明服务器, 远程认证, 远程证明, 邮件告警, 隐私保护