wildwildangel/setcap-static

setcap-static

setcap-static是setcap(8)的静态链接精简版本，用于设置指定文件的capabilities（权限能力）。它专为无依赖的scratch镜像设计，解决容器化应用在最小权限原则下需要特定root权限的场景。

核心功能与特性

• 静态链接：无需依赖动态库，可在scratch等极简镜像中直接运行
• 轻量精简：仅保留设置文件capabilities的核心功能，体积小巧
• 自删除机制：当可执行文件名以/!开头（如/!setcap-static），操作成功后会自动删除自身，避免在目标镜像中遗留额外文件
• 兼容性：支持标准capabilities语法，与原生setcap(8)的capabilities设置格式兼容

使用场景

• 容器最小权限优化：需遵循KubeSec安全指南以非root用户运行，但应用需要特定root权限（如绑定小于1024的端口）
• scratch镜像环境：基于scratch构建的极简镜像中，无法使用动态链接的标准setcap工具
• capabilities持久化：解决Docker的COPY命令不保留扩展属性导致capabilities丢失的问题

构建说明

构建依赖

• Alpine系统：cmake、make、libcap-dev、libcap-static
• Ubuntu系统：cmake、make、libcap-dev

构建命令

bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=MinSizeRel
cmake --build build --config MinSizeRel

使用方法

基本命令格式

bash
setcap-static <capabilities> <filename>

参数说明

• <capabilities>：符合cap_from_text(3)语法的capabilities字符串，如cap_net_bind_service=+ep（允许绑定低端口）
• <filename>：目标文件路径，必须为实际文件（不支持符号链接）

自删除功能

当setcap-static的执行路径前两个字符为/!（如/!setcap-static）时，成功设置capabilities后会自动删除自身。此特性适用于scratch镜像，避免遗留工具文件。

Docker部署示例

问题场景（错误示例）

Docker的COPY命令不保留扩展属性，直接复制在构建阶段设置好capabilities的文件到scratch镜像会失效：

Dockerfile
FROM docker.xuanyuan.run/alpine:3.13 as build
# 构建应用...
RUN \
    apk add --no-cache libcap \
    && setcap 'cap_net_bind_service=+ep' my-cool-application \  # 构建阶段设置capabilities
    && apk del --no-cache libcap

FROM docker.xuanyuan.run/scratch
COPY --from=build /path/to/my-cool-application /my-cool-application  # 扩展属性丢失，capabilities无效

正确使用示例

通过setcap-static在目标scratch镜像中设置capabilities：

Dockerfile
FROM docker.xuanyuan.run/scratch
# 复制静态链接的setcap-static，命名以/!开头启用自删除
COPY --from=wildwildangel/setcap-static /setcap-static /!setcap-static
# 复制应用程序
COPY --from=build /build/build/tiny-ssh-honeypot /tiny-ssh-honeypot
# 设置capabilities并自动删除setcap-static
RUN ["/!setcap-static", "cap_net_bind_service=+ep", "/tiny-ssh-honeypot"]

上述配置中，/!setcap-static会在成功为tiny-ssh-honeypot设置cap_net_bind_service=+ep权限后自动删除，最终镜像中仅保留应用程序。