sigstore/rekor-monitor
GitHub: sigstore/rekor-monitor
Rekor 日志监控器，用于验证透明度日志的不可篡改性并监控特定证书身份的签名活动。
Stars: 48 | Forks: 34
# Rekor 日志监控
Rekor Log Monitor 提供了一个易于使用的监控器，用于验证日志一致性，
确保日志是不可变且仅追加的。监控对于
透明度日志生态系统至关重要，因为日志是防篡改证据的，但并非完全防篡改。
Rekor Log Monitor 还提供了一个监控器，用于在日志中搜索身份，
并通过各种通知平台发送找到的身份列表。
## 构建与运行
### 构建监控器
要构建这两个监控器，请使用提供的 Makefile：
```
make build
```
这将在当前目录中创建 `rekor_monitor` 和 `ct_monitor` 二进制文件。
### 配置文件格式
配置文件使用 YAML 格式，并支持监控特定身份和证书属性。结构如下：
```
# 可选：指定搜索的起始和结束日志索引
startIndex: 1000
endIndex: 2000
# 要监控的值
monitoredValues:
# Certificate identities to monitor (subject and optional issuers)
certIdentities:
# certSubject is a regular expression
- certSubject: user@domain\.com
- certSubject: otheruser@domain\.com
issuers:
# issuers are regular expressions
- https://accounts\.google\.com
- https://github\.com/login
- certSubject: https://github\.com/actions/starter-workflows/blob/main/\.github/workflows/lint\.yaml@.*
issuers:
- https://token\.actions\.githubusercontent\.com
# Non-certificate subjects (for SSH, PGP keys, etc.)
# subjects are regular expressions
subjects:
- subject@domain\.com
# Key/certificate fingerprints to monitor
fingerprints:
- A0B1C2D3E4F5
# OID extension matchers (see OID Extension Matchers section below for details)
oidMatchers:
# Fulcio extensions using human-readable field names
fulcioExtensions:
build-config-uri:
- https://example.com/owner/repository/build-config.yml
# OID extensions using integer array format
oidExtensions:
- objectIdentifier: [1, 3, 6, 1, 4, 1, 57264, 1, 1]
extensionValues:
- https://github.com/login/oauth
# Custom OID extensions using dot notation (more human-readable)
customExtensions:
- objectIdentifier: 1.3.6.1.4.1.57264.1.9
extensionValues:
- https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0
# 可选：发现的身份输出文件
outputIdentities: identities.txt
# 可选：发现的身份输出格式（`text` 或 `json`）
outputIdentitiesFormat: text
# 可选：最后检查点输出文件
logInfoFile: logInfo.txt
# 可选：身份元数据输出文件
identityMetadataFile: metadata.json
```
### 示例用法
监控特定证书主体：
```
./rekor_monitor --config-file config.yaml --once=false --interval=1h
```
使用内联 YAML 配置进行监控：
```
./rekor_monitor --config 'monitoredValues:
certIdentities:
- certSubject: user@example\.com'
```
针对特定的 CT 日志运行 ct-monitor：
```
./ct_monitor --url https://ctfe.sigstore.dev/2022 --config-file ct-config.yaml
```
## GitHub 工作流设置
我们提供了可复用的 GitHub 工作流，用于监控 Rekor 和
证书透明度日志。
### 一致性检查
要运行，请创建一个使用
[可复用监控工作流](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) 的 GitHub Actions 工作流。
建议每小时运行一次日志监控器以获得最佳性能。
示例工作流：
```
name: Rekor log monitor
on:
schedule:
- cron: '0 * * * *' # every hour
permissions: read-all
jobs:
run_consistency_proof:
permissions:
contents: read # Needed to checkout repositories
issues: write # Needed if you set "file_issue: true"
id-token: write # Needed to detect the current reusable repository and ref
uses: sigstore/rekor-monitor/.github/workflows/reusable_monitoring.yml@main
with:
file_issue: true # Strongly recommended: Files an issue on monitoring failure
artifact_retention_days: 14 # Optional, default is 14: Must be longer than the cron job frequency
```
注意事项：
* 日志监控作业不应与同一仓库中的其他日志监控作业并发运行
* 如果作为 cron 作业运行，`artifact_retention_days` 必须长于 cron 作业的频率
### 身份监控
您还可以指定要监控的身份列表。目前，仅匹配来自证书
Subject Alternative Name (SAN) 字段的身份，且仅针对 hashedrekord Rekor 条目类型。
注意：`certIdentities.certSubject`、`certIdentities.issuers` 和 `subjects` 期望使用正则表达式。
请阅读[此文档](https://github.com/google/re2/wiki/Syntax)以了解语法参考。
注意：日志监控器仅从最新的检查点开始监控。如果您想搜索以前的
条目，则需要查询日志。
要运行，请创建一个使用
[可复用监控工作流](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) 的 GitHub Actions 工作流，
并将要监控的身份作为 `config` 输入的一部分传递。
建议每小时运行一次日志监控器以获得最佳性能。
示例工作流如下：
```
name: Rekor log and identity monitor
on:
schedule:
- cron: '0 * * * *' # every hour
permissions: read-all
jobs:
run_consistency_proof:
permissions:
contents: read # Needed to checkout repositories
issues: write # Needed if you set "file_issue: true"
id-token: write # Needed to detect the current reusable repository and ref
uses: sigstore/rekor-monitor/.github/workflows/reusable_monitoring.yml@main
with:
file_issue: true # Strongly recommended: Files an issue on monitoring failure
artifact_retention_days: 14 # Optional, default is 14: Must be longer than the cron job frequency
config: |
monitoredValues:
certIdentities:
- certSubject: user@domain\.com
- certSubject: otheruser@domain\.com
issuers:
- https://accounts\.google\.com
- https://github\.com/login
- certSubject: https://github\.com/actions/starter-workflows/blob/main/\.github/workflows/lint\.yaml@.*
issuers:
- https://token\.actions\.githubusercontent\.com
subjects:
- subject@domain\.com
fingerprints:
- A0B1C2D3E4F5
oidMatchers:
fulcioExtensions:
build-config-uri:
- https://example.com/owner/repository/build-config.yml
oidExtensions:
- objectIdentifier: [1, 3, 6, 1, 4, 1, 57264, 1, 1]
extensionValues:
- https://github.com/login/oauth
customExtensions:
- objectIdentifier: 1.3.6.1.4.1.57264.1.9
extensionValues:
- https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0
```
在此示例中，监控器将记录：
* 包含其 SAN 为 `user@domain.com` 的证书的条目
* 其 SAN 为 `otheruser@domain.com` 且[自定义扩展](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#1361415726418--issuer-v2)中指定的 OIDC 提供者与指定的颁发者之一（本例中为 Google 或 GitHub）匹配的条目
* 其 SAN 以 `https://github.com/actions/starter-workflows/blob/main/.github/workflows/lint.yaml@` 开头且 OIDC 提供者与 `https://token.actions.githubusercontent.com` 匹配的条目
* 其主体与 `subject@domain.com` 匹配的非证书条目，例如 PGP 或 SSH 密钥
* 其密钥或证书指纹与 `A0B1C2D3E4F5` 匹配的条目
* 包含其 Build Config URI Extension 与 `https://example.com/owner/repository/build-config.yml` 匹配的证书的条目
* 包含其已弃用的 Fulcio Issuer OID (`1.3.6.1.4.1.57264.1.1`) 与 `https://github.com/login/oauth` 匹配的证书的条目
* 包含其 OID 扩展 `1.3.6.1.4.1.57264.1.9`（Build Signer URI 的 Fulcio OID）且扩展值与 `https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0` 匹配的证书的条目
指纹值如下：
* 对于密钥、证书和 minisign，为 DER 编码的 PKIX 公钥或证书的十六进制编码 SHA-256 摘要
* 对于 SSH 和 PGP，为每个生态系统的标准：
* 对于 SSH，为密钥的未填充 base-64 编码 SHA-256 摘要
* 对于 PGP，为密钥的十六进制编码 SHA-1 摘要，可以是主密钥或子密钥
### OID 扩展匹配器
监控器支持基于 X.509 OID 扩展匹配证书。这对于监控
由 Fulcio 颁发的包含特定 CI/CD 工作流信息的证书非常有用。OID 匹配器可以
通过两种方式指定：使用命名的 Fulcio 扩展或自定义 OID 扩展。
注意：扩展值是完全匹配的（而非正则表达式）。
#### Fulcio 扩展
Fulcio 扩展提供了一种便捷的方法，使用人类可读的
YAML 字段名称来匹配众所周知的 Fulcio OID 扩展。完整的 Fulcio OID 扩展列表记录在
[sigstore/fulcio OID Info](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md)。
示例配置：
```
monitoredValues:
oidMatchers:
fulcioExtensions:
# Match certificates signed by a specific GitHub Actions workflow
build-signer-uri:
- https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v1.4.0
# Match certificates from a specific source repository
source-repository-uri:
- https://github.com/sigstore/cosign
# Match certificates with specific runner environment
runner-environment:
- github-hosted
```
#### OID 扩展（数组格式）
对于编程用例，或者当您希望将 OID 指定为整数数组时，
请使用 `oidExtensions` 格式：
```
monitoredValues:
oidMatchers:
oidExtensions:
# OID specified as an array of integers
- objectIdentifier: [1, 3, 6, 1, 4, 1, 57264, 1, 1]
extensionValues:
- https://github.com/login/oauth
- objectIdentifier: [1, 3, 6, 1, 4, 1, 57264, 1, 8]
extensionValues:
- https://accounts.google.com
```
注意：`objectIdentifier` 被指定为表示 OID 组件的 YAML 整数数组。
例如，`[1, 3, 6, 1, 4, 1, 57264, 1, 8]` 等同于点分表示法中的 `1.3.6.1.4.1.57264.1.8`。
#### 自定义 OID 扩展（点分表示法）
对于 Fulcio 命名字段未涵盖的 OID 扩展，或非 Fulcio OID 扩展，
请使用 `customExtensions` 格式，并以点分表示法指定 OID（更具可读性）：
```
monitoredValues:
oidMatchers:
customExtensions:
# Match the Fulcio Issuer extension (OID 1.3.6.1.4.1.57264.1.1)
- objectIdentifier: 1.3.6.1.4.1.57264.1.1
extensionValues:
- https://github.com/login/oauth
- https://accounts.google.com
# Match a custom OID extension
- objectIdentifier: 1.3.6.1.4.1.57264.1.9
extensionValues:
- https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0
```
注意：每个自定义扩展条目都需要 `objectIdentifier`（点分表示法）和 `extensionValues`（要匹配的值列表）。
即将推出的功能：
* 在发现身份时创建议题
* 支持其他身份
* Fulcio 证书中的 CI 身份值
### 证书透明度日志监控
还可以监控证书透明度日志实例。要运行，请创建一个使用
[可复用证书透明度日志监控工作流](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/ct_reusable_monitoring.yml) 的 GitHub Actions 工作流。
建议每小时运行一次日志监控器以获得最佳性能。
示例工作流如下：
```
name: Fulcio log and identity monitor
on:
schedule:
- cron: '0 * * * *' # every hour
permissions: read-all
jobs:
run_consistency_proof:
permissions:
contents: read # Needed to checkout repositories
issues: write # Needed if you set "file_issue: true"
id-token: write # Needed to detect the current reusable repository and ref
uses: sigstore/rekor-monitor/.github/workflows/ct_reusable_monitoring.yml@main
with:
file_issue: true # Strongly recommended: Files an issue on monitoring failure
artifact_retention_days: 14 # Optional, default is 14: Must be longer than the cron job frequency
config: |
monitoredValues:
certIdentities:
- certSubject: user@domain\.com
- certSubject: otheruser@domain\.com
issuers:
- https://accounts\.google\.com
- https://github\.com/login
- certSubject: https://github\.com/actions/starter-workflows/blob/main/\.github/workflows/lint\.yaml@.*
issuers:
- https://token\.actions\.githubusercontent\.com
subjects:
- subject@domain\.com
fingerprints:
- A0B1C2D3E4F5
oidMatchers:
fulcioExtensions:
build-config-uri:
- https://example.com/owner/repository/build-config.yml
oidExtensions:
- objectIdentifier: [1, 3, 6, 1, 4, 1, 57264, 1, 1]
extensionValues:
- https://github.com/login/oauth
customExtensions:
- objectIdentifier: 1.3.6.1.4.1.57264.1.9
extensionValues:
- https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0
```
## 安全
请按照 Sigstore 的[安全流程](https://github.com/sigstore/.github/blob/main/SECURITY.md)报告任何漏洞。
标签：AMSI绕过, DevSecOps, EVTX分析, EVTX分析, EVTX分析, Go语言, JSONLines, Rekor, Sigstore, SLSA, 上游代理, 不可变性验证, 二进制签名, 威胁检测, 完整性监控, 日志一致性, 日志审计, 构建验证, 程序破解, 证书监控, 身份监控, 透明日志, 零信任