hubertwojcik/ansible-openscap-pipeline
GitHub: hubertwojcik/ansible-openscap-pipeline
基于 GitHub Actions 的端到端安全合规流水线，在临时 EC2 上自动执行 OpenSCAP 扫描、Ansible 加固修复与复测，量化 CIS 基线合规效果。
Stars: 0 | Forks: 0
# ansible-openscap-pipeline
一个自动化的安全合规流水线，它在 AWS 上配置两台 Ubuntu 22.04 EC2 实例，运行 OpenSCAP 基线扫描，应用 Ansible 驱动的修复，重新扫描，并公开前/后报告——以便您可以量化针对 **CIS Ubuntu 22.04 Level 1** 配置文件的强化效果。
该流水线完全在 **GitHub Actions** 中运行——运行器作为 Ansible 控制节点，通过 SSH 连接到 EC2 目标节点。
## 流水线概述
```
GitHub Actions runner (control node)
│
│ 1. terraform apply
│ → EC2 target-1 (Ubuntu 22.04, eu-north-1)
│ → EC2 target-2 (Ubuntu 22.04, eu-north-1)
│
│ 2. setup_targets.yml → install OpenSCAP + SSG on both targets
│
│ 3. OpenSCAP scan BEFORE → reports/pre-remediation/target-{1,2}.{arf.xml,html}
│ (uploaded as artifact: pre-remediation-report)
│
│ 4. site.yml → 4 hardening roles, both targets
│ ssh_hardening · password_policy · audit_logging · filesystem_hardening
│
│ 5. OpenSCAP scan AFTER → reports/post-remediation/target-{1,2}.{arf.xml,html}
│ (uploaded as artifact: post-remediation-report)
│
└ 6. terraform destroy → always runs (if: always()), no orphaned EC2
```
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions runner │
│ (ubuntu-latest — Ansible control node) │
│ │
│ terraform apply / destroy (local state, ephemeral) │
│ ansible-playbook setup_targets.yml / run_scan.yml / site.yml│
└──────────────────┬──────────────────────────────────────────┘
│ SSH (port 22, key auth)
│
┌──────────▼──────────────────────┐
│ AWS eu-north-1 │
│ │
│ VPC ── Public Subnet │
│ │ │
│ ├── EC2 target-1 (t3.micro) │
│ │ Ubuntu 22.04 │
│ │ OpenSCAP + SSG │
│ │ │
│ └── EC2 target-2 (t3.micro) │
│ Ubuntu 22.04 │
│ OpenSCAP + SSG │
│ │
│ Security Group: SSH 0.0.0.0/0 │
│ (GitHub Actions has dynamic IPs)│
└──────────────────────────────────┘
```
状态说明：Terraform 使用 **本地状态**（无远程 S3 后端）。基础设施在单次流水线运行中创建和销毁，因此状态只需要在此次运行期间存在——这使得项目保持简单且免除了额外的 S3/KMS/DynamoDB 成本。
## 技术栈
| 类别 | 工具 |
|---|---|
| 基础设施 | Terraform, AWS EC2 (Ubuntu 22.04, t3.micro) |
| 配置管理 | Ansible, Ansible Roles |
| 合规性扫描 | OpenSCAP (`oscap`), SCAP Security Guide (SSG) |
| 合规配置文件 | CIS Ubuntu 22.04 LTS Level 1 |
| 目标操作系统 | Ubuntu 22.04 LTS (×2 台 EC2 实例) |
| CI/CD | GitHub Actions (同时作为 Ansible 控制节点) |
| 报告 | XCCDF / ARF / HTML |
## 仓库结构
```
.
├── terraform/
│ ├── main.tf # Wires vpc + security-groups + compute
│ ├── variables.tf
│ ├── outputs.tf # EC2 public IPs, generated inventory
│ ├── provider.tf # AWS provider (eu-north-1), local state
│ ├── terraform.tfvars
│ └── modules/
│ ├── vpc/ # VPC, subnet, IGW, route table
│ ├── security-groups/ # SG: SSH from anywhere (GHA dynamic IPs)
│ └── compute/ # 2x EC2 target nodes + key pair + inventory tpl
├── ansible/
│ ├── ansible.cfg
│ ├── inventory/
│ │ └── hosts.ini # Generated from `terraform output`
│ ├── playbooks/
│ │ ├── setup_targets.yml # Install OpenSCAP + SSG on targets
│ │ ├── run_scan.yml # Run oscap scan, fetch ARF/HTML back
│ │ └── site.yml # Apply the 4 hardening roles
│ └── roles/
│ ├── ssh_hardening/
│ ├── password_policy/
│ ├── filesystem_hardening/
│ └── audit_logging/
├── config/
│ └── scan.env # PROFILE_ID and DATASTREAM_PATH
├── scripts/
│ └── run_scan.sh # oscap xccdf eval (copied to targets, run there)
├── reports/
│ ├── pre-remediation/ # ARF + HTML before hardening
│ └── post-remediation/ # ARF + HTML after hardening
├── .github/
│ └── workflows/
│ └── openscap_pipeline.yml # Full pipeline (workflow_dispatch)
├── docs/ # Step-by-step learning docs (PL) — see docs/00
└── CHANGELOG.md
```
## Ansible Roles
| Role | 目标控制 (CIS L1) |
|---|---|
| `ssh_hardening` | 插入式 `sshd_config.d/00-hardening.conf`：关闭 root 登录，关闭密码认证，`MaxAuthTries`，空闲超时，关闭 X11，横幅等。 |
| `password_policy` | `/etc/login.defs` 中的密码时效；`/etc/security/pwquality.conf` 中的复杂性（minlen 14，必须包含数字/大写字母/小写字母/特殊字符） |
| `filesystem_hardening` | 禁用未使用的文件系统模块（cramfs, udf, …）；在 `/dev/shm` 上设置 `nodev`/`nosuid`/`noexec`（`/tmp` 为可选） |
| `audit_logging` | 启用 `auditd` + 针对身份文件、sudoers、时间更改、kernel 模块、特权命令的规则 |
每个 Role 的变量和每一行都在 `docs/10`–`docs/13` 中进行了解释。
## 前置条件
GitHub Secrets（设置一次——参见 `docs` / HUB-38）：
| Secret | 用途 |
|---|---|
| `AWS_ACCESS_KEY_ID` | Terraform → AWS（具有 EC2/VPC 权限的 IAM 用户） |
| `AWS_SECRET_ACCESS_KEY` | — |
| `AWS_DEFAULT_REGION` | `eu-north-1` |
| `EC2_SSH_PRIVATE_KEY` | Ansible 用于连接目标的私钥 |
| `SSH_PUBLIC_KEY` | 部署到 EC2 的公钥（映射到 `TF_VAR_ssh_public_key`） |
对于本地/手动运行：
- [Terraform](https://developer.hashicorp.com/terraform/install) >= 1.5
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/) >= 2.14（`ansible.posix` collection 随完整的 `ansible` 包一起提供）
- [Python](https://www.python.org/) >= 3.9
## 运行流水线 (GitHub Actions)
1. 确保上述所有五个 GitHub Secrets 已设置。
2. 确保 `openscap_pipeline.yml` 位于 **默认分支** 上（`workflow_dispatch` 仅在那里显示“Run workflow”按钮）。
3. **Actions → "OpenSCAP Pipeline" → Run workflow**。
4. 从运行中下载结果：**Artifacts → `pre-remediation-report` / `post-remediation-report`**（打开 `.html` 文件）。
`terraform destroy` 步骤以 `if: always()` 运行，因此即使扫描步骤失败，EC2 也会被销毁。
## 快速开始（手动，从笔记本电脑）
```
# 1. Provision EC2 目标
cd terraform/
export TF_VAR_ssh_public_key="$(cat ~/.ssh/ansible-openscap.pub)"
terraform init
terraform apply
# 2. 从 Terraform output 生成 Ansible inventory
terraform output -raw ansible_inventory > ../ansible/inventory/hosts.ini
cd ../ansible
# 3. 验证到两个目标的连接性
ansible targets -m ping
# 4. 安装 OpenSCAP，扫描，修复，重新扫描
ansible-playbook playbooks/setup_targets.yml
ansible-playbook playbooks/run_scan.yml -e scan_phase=pre
ansible-playbook playbooks/site.yml
ansible-playbook playbooks/run_scan.yml -e scan_phase=post
# 报告会存放在 reports/{pre,post}-remediation/ — 打开 .html 文件
# 5. 销毁（避免产生 EC2 费用）
cd ../terraform && terraform destroy
```
## 里程碑
| # | 里程碑 | 状态 |
|---|---|---|
| 1 | 基础设施 — Terraform EC2, VPC, Security Groups, 密钥对 | ✅ 完成 |
| 2 | 扫描层 — OpenSCAP + SSG, CIS 配置文件, 基线扫描 | ✅ 完成 |
| 3 | 修复层 — 4 个 Ansible roles | ✅ 完成 |
| 4 | 流水线集成 — 完整的扫描 → 修复 → GitHub Actions 中重新扫描 | ✅ 完成 |
| 5 | 报告与 CI/CD — 前/后对比报告, lint 工作流 | 🚧 进行中 |
## 路线图
尚未实现（在 Linear 中跟踪）：
- `scripts/compare_reports.py` — 自动化的前/后 diff（评分 + 每条规则 fail→pass）作为 Markdown artifact (HUB-29 / HUB-31)
- `.github/workflows/ansible-validate.yml` — 在每个 PR 上运行 `ansible-lint` + `yamllint` + `--syntax-check` (HUB-32)
- 最终架构与使用文档 (HUB-33)
## 许可证
MIT
标签：Ansible, DevSecOps, ECS, GitHub Actions, OpenSCAP, Terraform, 上游代理, 安全合规, 系统加固, 系统提示词, 网络代理, 自动化运维, 自动笔记, 逆向工具