MatthewGuadron/Docker-security-audit

## 目录 - [概述](#overview) - [为什么这个项目很重要](#why-this-project-matters) - [我的贡献](#my-contributions) - [核心功能](#core-capabilities) - [安全检查](#security-checks) - [演示](#demo) - [技术栈](#technology-stack) - [架构](#architecture) - [安装说明](#installation) - [快速开始](#quick-start) - [用法示例](#usage-examples) - [命令参考](#command-reference) - [报告和 CI/CD](#reporting-and-cicd) - [测试](#testing) - [安全的演示容器](#safe-demonstration-containers) - [项目结构](#project-structure) - [安全测试数据声明](#security-test-data-notice) - [局限性](#limitations) - [未来改进](#future-improvements) - [展示的技能](#skills-demonstrated) - [归属说明](#attribution) - [许可证](#license) ## 概述 DockSec 是一个使用 Go 构建的命令行安全扫描器，用于评估 Docker 环境中是否存在不安全的配置，并将发现结果映射到相关的 CIS Docker Benchmark 控制项。 该项目结合了： - 对活动容器的**运行时检查** - 对 Dockerfile 和 Docker Compose 配置的**静态分析** - **Docker daemon 和镜像审查** - 对高风险容器设置的**基于规则的检测** - 用于自动化和代码扫描工作流的**结构化安全报告** - **严重程度过滤和 CI/CD 安全门禁** - **自动化的单元、集成和端到端测试** 目标是帮助开发者、安全分析师、DevOps 工程师和平台团队在开发生命周期的早期识别可预防的容器安全弱点。 ## 为什么这个项目很重要 容器旨在隔离应用程序，但不安全的配置选择会削弱这种隔离。当容器出现以下情况时，它可能会成为严重的安全风险： - 以特权级别的宿主机访问权限运行 - 被赋予危险的 Linux capabilities - 挂载 Docker daemon socket - 将管理或数据库端口暴露给每个网络接口 - 以 root 用户身份运行 - 使用可变镜像标签（例如 `latest`） - 将凭证直接存储在配置文件中 - 在没有 CPU 或内存限制的情况下运行 - 挂载敏感的宿主机路径 - 使用薄弱的 Dockerfile 或 Compose 做法 DockSec 将这些配置风险转化为清晰的发现结果，可供人工审查或由自动化安全工作流处理。 ## 我的贡献 该代码库是 Docker 安全审计项目的独立作品集版本。我的工作重点是扩展、验证、记录和演示该扫描器。 ### 实现的自定义安全功能 - 增加了对使用可变 `latest` 镜像标签的容器的检测 - 增加了对在所有宿主机接口上发布敏感端口的检测 - 增加了对缺少容器 CPU 和内存限制的检查 - 创建了一个可重用的敏感端口规则映射，涵盖： - SSH — `22` - Telnet — `23` - MySQL — `3306` - PostgreSQL — `5432` - Redis — `6379` - MongoDB — `27017` - RDP — `3389` - VNC — `5900` ### 完成的验证和作品集工作 - 构建并测试了故意包含漏洞的 Docker 容器 - 验证了特权容器检测 - 验证了危险 capability 检测 - 验证了 Docker socket 挂载检测 - 验证了暴露的 Redis 端口检测 - 创建了不安全的 Dockerfile 和 Docker Compose 演示文件 - 生成了 JSON 和 SARIF 安全报告 - 解决了 Go 构建、格式化、方法重复和测试问题 - 运行了完整的 Go 测试套件和最终构建验证 - 为 GitHub 和简历审查创建了基于截图的证据包 - 将项目转换为独立的 GitHub 代码库 ## 核心功能 | 功能 | 描述 | |---|---| | 容器扫描 | 通过 Docker API 检查运行中的容器 | | Daemon 扫描 | 审查 Docker daemon 配置和安全状况 | | 镜像扫描 | 评估本地 Docker 镜像配置和元数据 | | Dockerfile 分析 | 解析 Dockerfile 中不安全的构建和运行时指令 | | Compose 分析 | 审查 Docker Compose YAML 中的危险服务设置 | | CIS 映射 | 将发现结果与 CIS Docker Benchmark 控制项关联 | | 严重程度过滤 | 按 `info`、`low`、`medium`、`high` 或 `critical` 过滤发现结果 | | 容器过滤 | 按名称模式包含或排除容器 | | 结构化输出 | 支持 terminal、JSON、SARIF 和 JUnit 输出 | | CI/CD 强制执行 | 当发现结果达到配置的阈值时返回失败的退出代码 | | 并发扫描 | 支持可配置的 worker 并发 | | Benchmark 参考 | 列出并显示已注册的 CIS 控制信息 | ## 安全检查 该扫描器旨在检测跨多个 Docker 层的安全弱点。 ### 运行时容器检查 | 检查项 | 安全隐患 | |---|---| | 特权容器 | 授予广泛的 Linux capabilities 和设备访问权限 | | 危险的 capabilities | 诸如 `SYS_ADMIN` 之类的 capabilities 可能提供过高的系统级权限 | | Docker socket 挂载 | 可能允许容器控制宿主机上的 Docker | | 敏感的宿主机挂载 | 可能暴露宿主机文件、凭证或操作系统资源 | | 暴露的敏感端口 | 数据库和远程管理服务可能会变得可被网络访问 | | `latest` 镜像标签 | 可变标签会降低构建的可重复性和版本控制能力 | | 缺少资源限制 | 无限制的 CPU 或内存使用会导致拒绝服务条件 | | root 执行 | 被入侵的进程在容器内拥有更大的权限 | | 薄弱的隔离设置 | 宿主机 namespace 或设备访问会降低容器边界 | ### Dockerfile 检查 Dockerfile 分析器评估的不安全模式示例包括： - `USER root` 或未使用非 root 用户 - 硬编码的凭证、API key、密码或 token - 可变的 `latest` 镜像标签 - 不安全的 shell 模式 - 薄弱的包管理实践 - 有风险的 `ADD` 使用 - 缺少 `HEALTHCHECK` - 降低镜像可重复性或运行时安全性的配置选择 ### Docker Compose 检查 有风险的 Compose 设置示例包括： - `privileged: true` - Docker socket 挂载 - 敏感的宿主机路径挂载 - 绑定到 `0.0.0.0` 的服务 - 发布到宿主机的敏感端口 - 环境变量中的硬编码 secret - 使用 `latest` 的镜像 - 缺少资源限制 - 其他服务级别的隔离弱点 ### Daemon 和镜像检查 DockSec 还包含以下分析器： - Docker daemon 配置 - 本地 Docker 镜像元数据和设置 - 与 CIS Docker Benchmark 相关的 daemon、镜像和容器控制项 ## 演示 `demo/` 目录包含故意设置的不安全配置、生成的报告以及展示扫描器行为的截图。 ### 特权容器检测

### Docker socket 挂载检测

### 暴露的 Redis 端口检测

### 机器可读报告

更多截图

**Go 构建成功**  **正常容器扫描** 

## 技术栈 | 技术 | 用途 | |---|---| | Go | 核心应用程序、分析器、并发、测试和 CLI | | Docker Engine / Docker Desktop | 运行时环境和 Docker API | | Docker Go SDK | 对容器、镜像和 daemon 设置的编程式检查 | | Cobra | 命令行界面和 flag 管理 | | YAML v3 | Docker Compose 解析 | | BuildKit 库 | Dockerfile 和与构建相关的分析 | | Testify | Go 测试和断言 | | JSON | 通用机器可读报告 | | SARIF | 安全和静态分析报告 | | JUnit XML | 兼容 CI 的测试风格报告 | | CIS Docker Benchmark | 安全控制映射和修复上下文 | Go 版本和依赖版本定义在 [`go.mod`](go.mod) 中。 ## 架构 DockSec 使用模块化的安全扫描 pipeline： ``` User command │ ▼ Cobra CLI cmd/docksec/main.go │ ▼ Configuration layer internal/config │ ▼ Scanner orchestrator internal/scanner │ ├── Runtime container analyzer ├── Docker daemon analyzer ├── Local image analyzer ├── Dockerfile analyzer └── Docker Compose analyzer │ ▼ Normalized security findings internal/finding │ ▼ CIS control mapping + remediation internal/benchmark │ ▼ Terminal / JSON / SARIF / JUnit reporters internal/report ``` ### 设计原则 - **模块化：** 每个 Docker 目标都有专门的分析器。 - **可扩展性：** 可以通过 `internal/rules` 和分析器包添加新规则。 - **标准化的发现结果：** 结果共享一致的安全严重程度和报告结构。 - **自动化就绪：** 输出格式和退出代码支持安全 pipeline。 - **受控的并发：** worker 设置允许并行扫描。 - **优雅关闭：** 信号感知执行可安全处理中断。 ## 安装说明 ### 前置条件 - Git - 与 [`go.mod`](go.mod) 兼容的 Go 版本 - Docker Engine 或 Docker Desktop - 具有用于运行时扫描的 Docker daemon 访问权限 ### 克隆代码库 ``` git clone https://github.com/MatthewGuadron/Docker-security-audit.git cd Docker-security-audit ``` ### 下载依赖 ``` go mod download ``` ### 运行测试套件 ``` go test ./... ``` ### 构建 CLI ``` go build -o docksec ./cmd/docksec ``` 在 Windows 上： ``` go build -o docksec.exe ./cmd/docksec ``` ### 确认构建 ``` ./docksec --help ./docksec version ``` ## 快速开始 确保 Docker Desktop 或 Docker daemon 正在运行。 ### 扫描完整的 Docker 环境 ``` ./docksec scan ``` ### 扫描运行中的容器 ``` ./docksec scan --target containers ``` ### 扫描 daemon 配置 ``` ./docksec scan --target daemon ``` ### 扫描本地镜像 ``` ./docksec scan --target images ``` ### 扫描不安全的 Dockerfile ``` ./docksec scan --file demo/Dockerfile.insecure ``` ### 扫描不安全的 Docker Compose 文件 ``` ./docksec scan --file demo/docker-compose.insecure.yml ``` ## 用法示例 ### 扫描多个目标 ``` ./docksec scan --target containers,daemon,images ``` ### 扫描多个配置文件 ``` ./docksec scan \ --file demo/Dockerfile.insecure \ --file demo/docker-compose.insecure.yml ``` ### 按严重程度过滤 ``` ./docksec scan --target containers --severity high,critical ``` ### 按 CIS 控制项过滤 ``` ./docksec scan --target containers --cis 5.4,5.31 ``` ### 包含特定容器 ``` ./docksec scan --target containers --include-container "production-*" ``` ### 排除容器 ``` ./docksec scan --target containers --exclude-container "test-*" ``` ### 使用最小化输出 ``` ./docksec scan --target containers --quiet ``` ### 启用详细输出 ``` ./docksec scan --target containers --verbose ``` ### 配置 worker 并发 ``` ./docksec scan --target images --workers 8 ``` ### 在发现中等或更高严重程度问题时使 CI/CD 作业失败 ``` ./docksec scan --file Dockerfile --fail-on medium ``` ### 显示 CIS benchmark 控制项 ``` ./docksec benchmark list ``` ``` ./docksec benchmark show 5.4 ``` ## 命令参考 ### 主要命令 | 命令 | 用途 | |---|---| | `docksec scan` | 扫描 Docker 目标和配置文件 | | `docksec version` | 显示版本、commit 和构建信息 | | `docksec benchmark list` | 列出已注册的 CIS Docker Benchmark 控制项 | | `docksec benchmark show ` | 显示 CIS 控制项的详细信息和修复建议 | ### 扫描 Flags | Flag | 简写 | 描述 | |---|---:|---| | `--target` | `-t` | 目标：`all`、`containers`、`daemon`、`images` | | `--file` | `-f` | 要扫描的 Dockerfile 或 Docker Compose 文件 | | `--output` | `-o` | 格式：`terminal`、`json`、`sarif`、`junit` | | `--output-file` | — | 将结果写入文件 | | `--severity` | — | 按严重程度过滤 | | `--cis` | — | 按 CIS 控制项 ID 过滤 | | `--exclude-container` | — | 按名称模式排除容器 | | `--include-container` | — | 仅包含匹配的容器 | | `--fail-on` | — | 达到或超过严重程度阈值时以代码 `1`退出 | | `--quiet` | `-q` | 显示基于计数的最小输出 | | `--verbose` | `-v` | 启用详细的调试输出 | | `--workers` | — | 设置并发 worker 数量 | 运行内置帮助以获取权威的命令参考： ``` ./docksec scan --help ``` ## 报告和 CI/CD DockSec 将扫描执行与报告格式化分离开来，允许人员、脚本、仪表板和安全平台使用相同的发现结果。 ### 终端输出 ``` ./docksec scan --target containers ``` 最适用于： - 本地测试 - 交互式调查 - 开发故障排除 ### JSON 报告 ``` ./docksec scan \ --file demo/Dockerfile.insecure \ --output json \ --output-file demo/results.json ``` 最适用于： - 自定义自动化 - 数据处理 - 仪表板 - 安全编排 - 与内部工具集成 ### SARIF 报告 ``` ./docksec scan \ --file demo/Dockerfile.insecure \ --output sarif \ --output-file demo/results.sarif ``` 最适用于： - 静态分析生态系统 - 代码扫描工作流 - 安全发现结果摄取 - 标准化的漏洞报告 ### JUnit 报告 ``` ./docksec scan \ --file demo/Dockerfile.insecure \ --output junit \ --output-file demo/results.xml ``` 最适用于： - CI 测试报告界面 - 构建仪表板 - pipeline 结果可视化 ### 基于严重程度的 pipeline 门禁 ``` ./docksec scan --file Dockerfile --fail-on high ``` 这支持如下策略： ### GitHub Actions 工作流示例 ``` name: Docker Security Audit on: push: pull_request: jobs: docksec: runs-on: ubuntu-latest steps: - name: Check out repository uses: actions/checkout@v4 - name: Set up Go uses: actions/setup-go@v5 with: go-version-file: go.mod - name: Run tests run: go test ./... - name: Build DockSec run: go build -o docksec ./cmd/docksec - name: Scan Dockerfile run: | ./docksec scan \ --file Dockerfile \ --output sarif \ --output-file results.sarif \ --fail-on high ``` ## 测试 该代码库包含： - 单元测试 - 分析器测试 - 集成测试 - 端到端测试 - 专门构建的不安全 Dockerfile - 专门构建的不安全 Compose 文件 - 运行时演示容器 ### 运行所有测试 ``` go test ./... ``` ### 运行测试并输出详细日志 ``` go test -v ./... ``` ### 开启竞态检测运行测试 ``` go test -race ./... ``` ### 运行特定包 ``` go test -v ./internal/analyzer ``` ### 格式化代码 ``` gofmt -w ./cmd ./internal ./tests ``` ### 最终验证序列 ``` go test ./... go build -o docksec ./cmd/docksec ./docksec scan --target containers ``` 成功的测试运行会为受测试的包显示 `ok`，对于没有独立测试文件的包可能会显示 `[no test files]`。 ## 安全的演示容器 ### 特权容器 ``` docker run -d --name risky-privileged --privileged nginx ./docksec scan --target containers docker rm -f risky-privileged ``` 预期分类： ``` Privileged container ``` ### 危险的 Linux capability ``` docker run -d --name risky-cap --cap-add=SYS_ADMIN nginx ./docksec scan --target containers docker rm -f risky-cap ``` 预期分类： ``` Dangerous capability ``` ### Docker socket 挂载 ``` docker run -d --name risky-socket \ -v /var/run/docker.sock:/var/run/docker.sock \ nginx ./docksec scan --target containers docker rm -f risky-socket ``` 预期分类： ``` Docker socket mounted ``` ### 暴露的 Redis 端口 ``` docker run -d \ --name redis-exposed \ -p 0.0.0.0:6379:6379 \ redis ./docksec scan --target containers docker rm -f redis-exposed ``` 预期分类： ``` Sensitive Redis port exposed ``` ### 可变的 `latest` 标签 ``` docker run -d --name latest-test nginx:latest ./docksec scan --target containers docker rm -f latest-test ``` 预期分类： ``` Container uses latest image tag ``` ## 项目结构 ``` Docker-security-audit/ ├── cmd/ │ └── docksec/ │ └── main.go # CLI entry point ├── demo/ │ ├── Dockerfile.insecure # Intentionally insecure Dockerfile │ ├── docker-compose.insecure.yml │ ├── results.json # Example JSON report │ ├── results.sarif # Example SARIF report │ └── screenshots/ # Build, findings, and report evidence ├── internal/ │ ├── analyzer/ # Container, daemon, image, file analyzers │ ├── benchmark/ # CIS control definitions and lookups │ ├── config/ # CLI and scanner configuration │ ├── docker/ # Docker client integration │ ├── finding/ # Finding models and severity handling │ ├── parser/ # Dockerfile and Compose parsing │ ├── proc/ # Process and host-related helpers │ ├── report/ # Terminal, JSON, SARIF, and JUnit output │ ├── rules/ # Capabilities, paths, ports, and secret rules │ └── scanner/ # Scan orchestration ├── learn/ # Project learning and reference material ├── tests/ │ ├── e2e/ # End-to-end tests │ ├── integration/ # Integration tests │ └── testdata/ # Purpose-built secure/insecure fixtures ├── Dockerfile ├── go.mod ├── go.sum ├── justfile ├── LICENSE └── README.md ``` ## 安全测试数据声明 `tests/testdata/` 下的文件有意包含**合成的凭证模式**和不安全的设置，以便测试 secret 检测和配置分析规则。 示例包括： ``` tests/testdata/compose/bad-secrets.yml tests/testdata/dockerfiles/bad-secrets.Dockerfile ``` 重要提示： - 这些值是测试夹具。 - 它们不是活动的生产凭证。 - 绝不能用真实的 key 或 token 替换它们。 - Secret 扫描平台可能会正确标记它们，因为它们被设计为类似于凭证。 - 任何 push-protection 的例外情况，只有在确认该值是合成的且专用于测试之后，才应予以批准。 ## 局限性 DockSec 是一个配置和安全状况扫描器。它不能完全替代每一层的容器安全。 当前的局限性包括： - 它不能取代专门的 CVE 或包漏洞扫描器。 - 运行时扫描需要访问 Docker daemon。 - 访问 Docker socket 本身具有高度敏感性，应严加控制。 - 发现结果可识别有风险的配置，但可能需要特定环境的验证。 - 某些控制项可能不适用于每个操作系统、编排平台或业务环境。 - 该扫描器目前不能替代 Kubernetes 准入控制、云安全状况管理、运行时行为监控或镜像签名验证。 - 演示文件故意设置为不安全，不应部署到生产环境中。 成熟的容器安全程序应将 DockSec 式的配置审查与镜像漏洞扫描、最小权限原则、secrets 管理、签名构件、网络控制、监控和策略执行相结合。 ## 未来改进 潜在的增强功能包括： - 直接在代码库中包含 GitHub Actions 工作流 - 自动将 SARIF 上传到 GitHub 代码扫描 - 额外的 CIS Docker Benchmark 控制项 - 抑制和允许列表配置 - 扫描之间的基线比较 - HTML 报告 - SBOM 生成和摄取 - 与镜像漏洞扫描器集成 - Docker context 和远程 daemon 支持 - 修复自动修复建议 - 配置策略文件 - 改进对 Windows 容器的覆盖范围 - 为 macOS、Linux 和 Windows 提供 release 二进制文件 - 签名的发布构件和校验和 - 针对大型 Docker 环境的性能 benchmark - 扩展自定义检测规则的单元测试 ## 展示的技能 该项目展示了对以下方面的实践经验： ### 安全工程 - 容器安全 - Docker 加固 - CIS benchmark 解读 - 最小权限分析 - 攻击面缩减 - Secret 检测 - 安全发现结果优先级排序 - 修复指导 - 安全配置审查 ### 软件工程 - Go 应用程序开发 - 使用 Cobra 设计 CLI - Docker SDK 集成 - YAML 和 Dockerfile 解析 - 模块化架构 - 并发扫描 - 错误处理 - 自动化测试 - Git 版本控制 - 技术文档 ### DevSecOps 和自动化 - 安全即代码 (Security-as-code) - CI/CD 质量门禁 - JSON 和 SARIF 报告 - 兼容 JUnit 的输出 - 可重复的测试环境 - 自动化策略检查 - 机器可读的安全结果 ## 归属说明 这个独立的代码库基于并扩展现有的 DockSec 代码库。原始的源代码结构、版权声明、模块引用和许可信息均保留在代码库中。 我的作品集贡献记录在[我的贡献](#my-contributions)部分，重点在于自定义检测逻辑、测试、调试、报告、演示证据和项目文档。 上游项目源码： - [CarterPerez-dev/Cybersecurity-Projects — Docker 安全审计](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/docker-security-audit) 包含此归属说明是为了清楚地将原始项目基础与本代码库中完成的增强和验证工作区分开来。 ## 许可证 该项目基于 **GNU Affero General Public License v3.0** 授权。 有关完整的许可文本，请参见 [`LICENSE`](LICENSE)。

### 旨在展示实际的容器安全、Go 开发和 DevSecOps 自动化。 **代码库：** [github.com/MatthewGuadron/Docker-security-audit](https://github.com/MatthewGuadron/Docker-security-audit)

标签：EVTX分析, 日志审计