securing-container-registry-with-harbor

# 使用 Harbor 保护容器镜像仓库

## 概述

Harbor 是一个开源容器镜像仓库，提供安全功能包括漏洞扫描（集成 Trivy）、镜像签名（Notary/Cosign）、RBAC、内容信任策略、复制和审计日志。保护 Harbor 需要配置这些功能来强制执行镜像来源验证、防止有漏洞的镜像部署，并维护仓库访问控制。

## 前置条件

- Harbor 2.10+（通过 Helm 或 Docker Compose 安装）
- HTTPS 的 TLS 证书
- Trivy 扫描器集成
- 用于认证的 OIDC/LDAP
- Kubernetes 集群（部署目标）

## 实施步骤

### 步骤 1：使用安全配置安装 Harbor

```yaml
# 用于 Helm 部署的 harbor-values.yaml
expose:
  type: ingress
  tls:
    enabled: true
    certSource: secret
    secret:
      secretName: harbor-tls
      notarySecretName: harbor-tls
  ingress:
    hosts:
      core: harbor.example.com
      notary: notary.example.com

externalURL: https://harbor.example.com

persistence:
  enabled: true
  resourcePolicy: "keep"

harborAdminPassword: "<强密码>"

trivy:
  enabled: true
  gitHubToken: "<github-token>"
  severity: "CRITICAL,HIGH,MEDIUM"
  autoScan: true

notary:
  enabled: true

core:
  secretKey: "<32字符密钥>"

database:
  type: external
  external:
    host: postgres.example.com
    port: "5432"
    username: harbor
    password: "<数据库密码>"
    sslmode: require
```

```bash
helm repo add harbor https://helm.getharbor.io
helm install harbor harbor/harbor -f harbor-values.yaml -n harbor --create-namespace
```

### 步骤 2：配置漏洞扫描策略

```bash
# 启用推送时自动扫描（通过 Harbor API）
curl -k -X PUT "https://harbor.example.com/api/v2.0/projects/myproject" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "auto_scan": "true",
      "severity": "critical",
      "prevent_vul": "true",
      "reuse_sys_cve_allowlist": "true"
    }
  }'
```

### 步骤 3：配置内容信任

```bash
# 在项目级别启用内容信任
curl -k -X PUT "https://harbor.example.com/api/v2.0/projects/myproject" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "enable_content_trust": "true",
      "enable_content_trust_cosign": "true"
    }
  }'

# 使用 Cosign 签署镜像
cosign sign --key cosign.key harbor.example.com/myproject/myapp:v1.0.0

# 验证签名
cosign verify --key cosign.pub harbor.example.com/myproject/myapp:v1.0.0
```

### 步骤 4：配置 RBAC 和项目隔离

```bash
# 创建具有私有可见性的项目
curl -k -X POST "https://harbor.example.com/api/v2.0/projects" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "production",
    "metadata": {
      "public": "false",
      "auto_scan": "true",
      "prevent_vul": "true",
      "severity": "high"
    }
  }'

# Harbor 角色：ProjectAdmin、Maintainer、Developer、Guest、LimitedGuest
# 以特定角色添加成员
curl -k -X POST "https://harbor.example.com/api/v2.0/projects/production/members" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 3,
    "member_user": {"username": "developer1"}
  }'
```

### 步骤 5：配置不可变标签和保留策略

```bash
# 创建标签不可变规则（防止覆盖发布标签）
curl -k -X POST "https://harbor.example.com/api/v2.0/projects/production/immutabletagrules" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_filter": "v*",
    "scope_selectors": {
      "repository": [{"kind": "doublestar", "decoration": "repoMatches", "pattern": "**"}]
    }
  }'

# 配置保留策略（保留最新 10 个标签，7 天后删除未标记的镜像）
curl -k -X POST "https://harbor.example.com/api/v2.0/retentions" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "or",
    "rules": [
      {
        "action": "retain",
        "template": "latestPushedK",
        "params": {"latestPushedK": 10},
        "tag_selectors": [{"kind": "doublestar", "decoration": "matches", "pattern": "**"}],
        "scope_selectors": {"repository": [{"kind": "doublestar", "decoration": "repoMatches", "pattern": "**"}]}
      }
    ],
    "trigger": {"kind": "Schedule", "settings": {"cron": "0 0 * * *"}}
  }'
```

### 步骤 6：OIDC 认证集成

```yaml
# Harbor OIDC 配置
auth_mode: oidc_auth
oidc_name: "Okta"
oidc_endpoint: "https://company.okta.com/oauth2/default"
oidc_client_id: "harbor-client-id"
oidc_client_secret: "harbor-client-secret"
oidc_groups_claim: "groups"
oidc_admin_group: "harbor-admins"
oidc_scope: "openid,profile,email,groups"
oidc_verify_cert: true
oidc_auto_onboard: true
```

## 验证命令

```bash
# 测试漏洞防护（应阻止拉取有漏洞的镜像）
docker pull harbor.example.com/production/vulnerable-app:latest
# 预期：错误 - 镜像因漏洞被阻止

# 验证内容信任执行
DOCKER_CONTENT_TRUST=0 docker push harbor.example.com/production/unsigned:latest
# 预期：因内容信任策略拒绝推送

# 通过 API 检查扫描结果
curl -k "https://harbor.example.com/api/v2.0/projects/production/repositories/myapp/artifacts/v1.0.0/additions/vulnerabilities" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)"

# 审计日志检查
curl -k "https://harbor.example.com/api/v2.0/audit-logs?page=1&page_size=10" \
  -H "Authorization: Basic $(echo -n admin:Harbor12345 | base64)"
```

## 参考资料

- [Harbor 文档](https://goharbor.io/docs/)
- [Harbor 安全最佳实践](https://goharbor.io/docs/2.10.0/administration/vulnerability-scanning/)
- [Harbor GitHub 仓库](https://github.com/goharbor/harbor)