mazze93/secure-container-template
GitHub: mazze93/secure-container-template
一个内置安全最佳实践的 Python 容器化项目模板，提供非 root 运行、SBOM、镜像签名和安全门禁 CI 流水线。
Stars: 1 | Forks: 0
# 安全-container-template
一个具有加固默认安全态势的最小化 Python 容器模板：
- 非 root 容器运行时，由生产级 WSGI 服务器 (gunicorn) 提供服务
- 针对应用 `/health` endpoint 的容器 `HEALTHCHECK`
- GitHub Actions CI，所有 action 均固定到 commit SHA
- 发布镜像上的 SBOM 和 provenance
- Docker Scout 漏洞报告（尽力而为，不阻断流程）
- SemVer 标签、签名的发布镜像以及 GitHub Releases
- 用于 Python、Docker 基础镜像和 Actions 更新的 Dependabot
## 仓库结构
```
.
├── .github/
│ ├── dependabot.yml
│ └── workflows/
│ ├── ci.yml
│ └── release.yml
├── src/
├── tests/
├── CHANGELOG.md
├── Dockerfile
├── LICENSE
├── VERSION
├── build.sh
├── requirements-dev.txt
├── requirements.txt
└── test.sh
```
## 本地开发
运行测试套件：
```
./test.sh
```
构建容器：
```
./build.sh
```
在本地运行服务（Flask 开发服务器）：
```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m src.main
```
健康检查 endpoint 可通过 `http://127.0.0.1:8000/health` 访问。
容器镜像改为使用 **gunicorn**（一个生产级 WSGI
服务器）来提供应用服务，这与 [Dockerfile](Dockerfile) 中的 `CMD` 相匹配。为了像
CI 和生产环境中那样测试镜像：
```
./build.sh
docker run --rm -p 8000:8000 secure-container-template:dev
curl -s http://127.0.0.1:8000/health # {"status":"ok"}
```
镜像声明了 `HEALTHCHECK`，因此 `docker ps` 会报告容器健康状态。
## 可选的 GitHub Secrets
[.github/workflows/ci.yml](.github/workflows/ci.yml) 中的 Docker Scout 阶段
使用以下仓库 secret 向 Docker Hub 进行身份验证：
- `DOCKERHUB_USERNAME`
- `DOCKERHUB_TOKEN`
它们是**可选的**，并且必须同时设置才能运行 Scout。如果缺少其中任何一个，
CI 将跳过 Scout 报告步骤，而流水线的其余部分
（测试、容器构建、推送、非 root 验证）仍会继续运行。Scout 只在
推送到 `main` 分支时执行，从不在 pull request 上执行，并且是**尽力而为**的：
缺少或无效的 Docker Hub 凭证只会记录警告，绝不会导致
发布任务失败。
使用 GitHub CLI 设置它们：
```
gh secret set DOCKERHUB_USERNAME --repo mazze93/secure-container-template
gh secret set DOCKERHUB_TOKEN --repo mazze93/secure-container-template
```
配置好 secret 后，从 Actions 标签页重新运行 `main` 分支上的任何 CI 任务。
## CI 与安全门禁
[.github/workflows/ci.yml](.github/workflows/ci.yml) 中的主工作流强制执行：
- Python 测试必须通过。
- `Dockerfile` 必须声明一个非 root 的 `USER`。
- 构建的镜像必须具有非 root 的 `Config.User`。
- 从 `main` 分支发布的镜像包含 SBOM 和 provenance 证明。
- Docker Scout 的 `quickview` 和 `cves` 报告从 `main` 分支发布的镜像。
非 root 执行是严格的合并阻碍。Docker Scout CVE 发现会被
报告以提高可见性，但默认是**非阻断**的 —— 要将可修复的
`critical`/`high` CVE 恢复为合并门禁，请在 [.github/workflows/ci.yml](.github/workflows/ci.yml) 的 "Docker Scout CVEs" 步骤中设置 `exit-code: true`。
## 发布的镜像
此仓库中的工作流发布了两个镜像：
| 镜像 | Registry | 发布者 | 标签 |
| --- | --- | --- | --- |
| `ghcr.io/mazze93/secure-container-template` | GitHub Container Registry | 推送到 `main` 时的 [`ci.yml`](.github/workflows/ci.yml) | `latest`, `sha-`, 分支名 |
| `docker.io/mazze93/secure-container-base` | Docker Hub | `v*.*.*` 标签上的 [`release.yml`](.github/workflows/release.yml) | ``, `sha-` |
两者都使用 **SBOM** 和 **provenance** 证明进行构建。发布
镜像另外是**多架构**（`linux/amd64`, `linux/arm64`）的，并且
**使用 cosign 签名**（无密钥 / Sigstore）。
拉取并运行最新的 CI 镜像：
```
docker run --rm -p 8000:8000 ghcr.io/mazze93/secure-container-template:latest
```
检查发布镜像上的证明：
```
docker buildx imagetools inspect ghcr.io/mazze93/secure-container-template:latest
```
验证发布镜像签名：
```
cosign verify docker.io/mazze93/secure-container-base: \
--certificate-identity-regexp '^https://github.com/mazze93/secure-container-template/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
```
## 分支保护
`main` 分支应在合并前要求进行 `test_and_container` 状态检查。该任务运行测试和非 root 镜像验证，因此要求进行此检查即可将这些检查转化为仓库策略。
针对 `main` 分支的推荐设置：
- 合并前需要 pull request
- 至少需要 1 个批准
- 合并前需要状态检查通过
- 合并前要求分支保持最新
- 必须检查：`test_and_container`
- 合并前要求解决所有对话
- 规则同样适用于管理员
等效的 GitHub CLI 调用：
```
gh api \
--method PUT \
-H "Accept: application/vnd.github+json" \
/repos/mazze93/secure-container-template/branches/main/protection \
-F required_status_checks.strict=true \
-F required_status_checks.contexts[]=test_and_container \
-F enforce_admins=true \
-F required_pull_request_reviews.dismiss_stale_reviews=true \
-F required_pull_request_reviews.require_code_owner_reviews=false \
-F required_pull_request_reviews.required_approving_review_count=1 \
-F required_conversation_resolution=true \
-F restrictions= \
-F allow_force_pushes=false \
-F allow_deletions=false \
-F block_creations=false \
-F required_linear_history=false \
-F lock_branch=false \
-F allow_fork_syncing=true
```
## 发布流程
该仓库遵循 SemVer。发布是根据匹配 `v*.*.*` 的 Git 标签创建的。
要发布新版本：
```
echo "0.1.1" > VERSION
```
更新 [CHANGELOG.md](CHANGELOG.md)，然后：
```
git add VERSION CHANGELOG.md
git commit -m "release: v0.1.1"
git tag v0.1.1
git push origin main --tags
```
推送标签会触发 [.github/workflows/release.yml](.github/workflows/release.yml)，从而创建 GitHub Release。
标签：DevSecOps, Docker, Python, SBOM, Web截图, 上游代理, 安全防御评估, 容器安全, 无后门, 模板项目, 硬件无关, 请求拦截, 逆向工具