Kubernetes Pod 安全治理與容器映像漏洞掃描完整實戰指南

# 定義一個限制性的 PodSecurityPolicy
# 此策略實施嚴格的安全控制，適用於高安全要求的生產環境
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  name: restricted-psp
  labels:
    app.kubernetes.io/name: restricted-psp
    app.kubernetes.io/component: security-policy
    security-level: high
    environment: production
  annotations:
    # 提供策略的說明文件，方便團隊成員理解
    description: "嚴格限制的安全策略，適用於無特殊權限需求的應用程式"
    seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'runtime/default'
    apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
spec:
  # 禁止容器以特權模式執行
  # 特權模式讓容器擁有主機的所有能力，包括載入核心模組、修改系統參數等
  # 這是最危險的配置，應該在絕大多數情況下禁止
  privileged: false

  # 禁止容器透過 setuid/setgid 機制提升權限
  # 這是防止權限提升攻擊的重要防線
  allowPrivilegeEscalation: false

  # 移除容器的所有預設 Linux 能力
  # 採用白名單模式，只保留應用程式實際需要的能力
  requiredDropCapabilities:
    - ALL
    
  # 可以選擇性地允許特定能力（這裡保持空白表示不允許任何額外能力）
  # 例如，若應用需要綁定特權連接埠，可以加入：
  # allowedCapabilities:
  #   - NET_BIND_SERVICE

  # 禁止容器使用主機的各種命名空間
  # 這些設定防止容器直接存取主機資源，維持隔離性
  hostNetwork: false   # 禁止使用主機網路命名空間
  hostIPC: false       # 禁止使用主機 IPC 命名空間
  hostPID: false       # 禁止使用主機 PID 命名空間
  
  # 禁止容器綁定主機連接埠
  # 若需要對外暴露服務，應透過 Service 資源
  hostPorts:
    - min: 0
      max: 0

  # 限制可以使用的 Volume 類型
  # 只允許安全的 Volume 類型，明確排除 hostPath
  volumes:
    - 'configMap'              # 允許掛載 ConfigMap 注入組態
    - 'emptyDir'               # 允許使用節點上的暫存目錄
    - 'projected'              # 允許使用 projected volume（可組合多種來源）
    - 'secret'                 # 允許掛載 Secret 注入敏感資料
    - 'downwardAPI'            # 允許存取 Pod 與容器的後設資料
    - 'persistentVolumeClaim'  # 允許使用 PVC 掛載持久化儲存
    # 明確不包含的危險類型：
    # - 'hostPath'：會暴露主機檔案系統
    # - 'flexVolume'：可能執行任意外掛程式
    # - 'gcePersistentDisk', 'awsElasticBlockStore' 等：
    #   雲端廠商特定的 Volume，應透過 StorageClass 與 PVC 使用

  # 強制容器以非 root 使用者執行
  # 這是最重要的安全設定之一，大幅降低容器逃逸的風險
  runAsUser:
    rule: MustRunAsNonRoot
    # 注意：此規則不指定具體的 UID，只要求不是 0（root）
    # 容器映像應該在 Dockerfile 中設定適當的使用者

  # 限制可使用的群組 ID 範圍
  # 避免使用系統預留的低 GID（通常 0-999）
  runAsGroup:
    rule: MustRunAs
    ranges:
      - min: 1000
        max: 65535

  # 設定補充群組的規則
  # supplementalGroups 用於控制容器程序的額外群組成員資格
  supplementalGroups:
    rule: MustRunAs
    ranges:
      - min: 1000
        max: 65535

  # 設定檔案系統群組的規則
  # fsGroup 控制 Volume 的群組擁有者，影響檔案權限
  fsGroup:
    rule: MustRunAs
    ranges:
      - min: 1000
        max: 65535

  # 強制使用唯讀根檔案系統
  # 防止容器內的程序修改系統檔案或植入惡意程式
  # 應用程式若需要寫入檔案，應使用 emptyDir 或 PVC
  readOnlyRootFilesystem: true

  # 配置 SELinux 規則（適用於 RHEL/CentOS/Fedora）
  # RunAsAny 表示允許容器使用任意 SELinux 標籤
  # 在更嚴格的環境中，可以指定特定的標籤類型
  seLinux:
    rule: RunAsAny
    
  # 禁止使用不安全的 sysctl 參數
  # sysctl 可以修改核心參數，某些參數會影響主機或其他容器
  # 此處保持空白表示不允許任何 unsafe sysctl
  allowedUnsafeSysctls: []
  
  # 禁止使用 proc mount（實驗性功能）
  # 預設值已經是最安全的 Default 模式
  allowedProcMountTypes:
    - Default

# 將上述 YAML 配置儲存為檔案
# 檔案名稱建議與策略名稱保持一致
cat > restricted-psp.yaml <<EOF
# ... (上述 YAML 內容) ...
EOF

# 套用 PodSecurityPolicy 到叢集
# 這個操作需要叢集管理員權限
kubectl apply -f restricted-psp.yaml

# 驗證 PodSecurityPolicy 是否成功建立
# 輸出應該顯示剛建立的策略
kubectl get psp restricted-psp

# 檢視 PSP 的詳細資訊
# 確認所有屬性都正確設定
kubectl describe psp restricted-psp

# 查看叢集中所有的 PodSecurityPolicy
# 可能還包含系統預設的策略
kubectl get psp

# 以 YAML 格式輸出策略內容
# 方便檢查與備份
kubectl get psp restricted-psp -o yaml

# 第一步：建立 ClusterRole 以授權使用特定的 PodSecurityPolicy
# ClusterRole 是叢集範圍的資源，可以在多個 Namespace 中引用
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: use-restricted-psp
  labels:
    app.kubernetes.io/name: use-restricted-psp
    app.kubernetes.io/component: rbac
    security-policy: restricted
  annotations:
    description: "授權使用限制性 PodSecurityPolicy 的角色"
rules:
  # 定義此 ClusterRole 可以執行的操作
  - apiGroups: ['policy']
    # 指定資源類型為 podsecuritypolicies
    resources: ['podsecuritypolicies']
    # 只授予 use 動詞，表示可以使用此 PSP
    # 注意：這是一個特殊的動詞，只適用於 PSP
    verbs: ['use']
    # 限定只能使用名為 restricted-psp 的策略
    # 透過 resourceNames 限制可以操作的具體資源
    resourceNames:
      - restricted-psp
---
# 第二步：建立 ServiceAccount 供應用程式使用
# ServiceAccount 提供 Pod 在叢集內的身份識別
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: production
  labels:
    app.kubernetes.io/name: app-sa
    app.kubernetes.io/component: service-account
    app.kubernetes.io/part-of: my-application
  annotations:
    description: "應用程式專用的服務帳號，已授權使用限制性安全策略"
# ServiceAccount 會自動產生對應的 Secret，包含 API token
# Pod 可以使用這個 token 與 API Server 通訊
---
# 第三步：建立 RoleBinding 將 ClusterRole 繫結到 ServiceAccount
# 使用 RoleBinding 而非 ClusterRoleBinding 可以限制在特定 Namespace
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: use-restricted-psp-binding
  namespace: production
  labels:
    app.kubernetes.io/name: use-restricted-psp-binding
    app.kubernetes.io/component: rbac-binding
    security-policy: restricted
  annotations:
    description: "將限制性 PSP 使用權限繫結到應用程式服務帳號"
# roleRef 指定要繫結的角色
# 這個欄位一旦設定就無法修改，只能刪除後重建
roleRef:
  kind: ClusterRole
  name: use-restricted-psp
  apiGroup: rbac.authorization.k8s.io
# subjects 指定被授權的主體
# 可以是 User、Group 或 ServiceAccount
subjects:
  - kind: ServiceAccount
    name: app-sa
    namespace: production
---
# 示範：使用此 ServiceAccount 的 Pod 定義
apiVersion: v1
kind: Pod
metadata:
  name: secure-app
  namespace: production
  labels:
    app: secure-app
spec:
  # 指定此 Pod 使用 app-sa ServiceAccount
  # Pod 會繼承 ServiceAccount 的所有權限，包括 PSP 使用權
  serviceAccountName: app-sa
  
  # 以下配置必須符合 restricted-psp 的要求
  securityContext:
    # Pod 層級的安全上下文
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000
    
  containers:
    - name: app
      image: my-registry/my-app:1.0.0
      
      # 容器層級的安全上下文
      securityContext:
        # 允許權限提升必須設為 false
        allowPrivilegeEscalation: false
        # 使用唯讀根檔案系統
        readOnlyRootFilesystem: true
        # 以非 root 使用者執行
        runAsNonRoot: true
        runAsUser: 1000
        # 移除所有能力
        capabilities:
          drop:
            - ALL
      
      # 掛載可寫入的暫存目錄
      # 因為根檔案系統是唯讀的，應用需要寫入的路徑要特別掛載
      volumeMounts:
        - name: tmp
          mountPath: /tmp
        - name: cache
          mountPath: /app/cache
  
  volumes:
    # 使用 emptyDir 提供暫存儲存空間
    - name: tmp
      emptyDir: {}
    - name: cache
      emptyDir: {}

# 套用所有 RBAC 配置
kubectl apply -f rbac-config.yaml

# 驗證 ClusterRole 是否建立
kubectl get clusterrole use-restricted-psp

# 驗證 ServiceAccount 是否建立
kubectl get serviceaccount app-sa -n production

# 驗證 RoleBinding 是否建立
kubectl get rolebinding use-restricted-psp-binding -n production

# 檢視 RoleBinding 的詳細資訊
# 確認繫結關係正確
kubectl describe rolebinding use-restricted-psp-binding -n production

# 嘗試建立符合策略的 Pod
kubectl apply -f secure-app-pod.yaml

# 檢查 Pod 是否成功建立
kubectl get pod secure-app -n production

# 嘗試建立違反策略的 Pod（例如以 root 執行）
# 這應該會失敗並回傳錯誤訊息
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: insecure-app
  namespace: production
spec:
  serviceAccountName: app-sa
  containers:
    - name: app
      image: nginx:latest
      securityContext:
        runAsUser: 0  # 嘗試以 root 執行
EOF

# 預期輸出錯誤訊息：
# Error from server (Forbidden): error when creating "STDIN": 
# pods "insecure-app" is forbidden: unable to validate against 
# any pod security policy: [spec.containers[0].securityContext.runAsUser: 
# Invalid value: 0: must be non-root]

# 第一步：安裝 krew（kubectl 外掛管理工具）
# 如果已經安裝 krew，可以跳過這一步

# macOS 使用者可透過 Homebrew 快速安裝
brew install krew

# Linux 或其他作業系統使用者可使用官方安裝腳本
(
  set -x; cd "$(mktemp -d)" &&
  OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
  ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')" &&
  KREW="krew-${OS}_${ARCH}" &&
  curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&
  tar zxvf "${KREW}.tar.gz" &&
  ./"${KREW}" install krew
)

# 將 krew 的執行路徑加入系統 PATH 環境變數
# 將以下指令加入 ~/.bashrc 或 ~/.zshrc
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

# 重新載入 shell 設定或手動執行上述 export 指令
source ~/.bashrc  # 或 source ~/.zshrc

# 驗證 krew 是否正確安裝
kubectl krew version

# 第二步：使用 krew 安裝 advise-psp 外掛
kubectl krew install advise-psp

# 更新 krew 的外掛索引（確保能取得最新版本）
kubectl krew update

# 驗證 advise-psp 是否成功安裝
kubectl advise-psp --help

# 輸出應該顯示工具的使用說明與可用參數

# 基本用法：掃描 default Namespace 中的工作負載
# inspect 命令會分析 Namespace 中的所有 Pod
# --grant 參數表示同時生成 RBAC 相關資源
kubectl advise-psp inspect --grant --namespace default

# 將生成的配置輸出到檔案
# 這樣可以方便檢視、修改與版本控制
kubectl advise-psp inspect --grant --namespace default > default-ns-psp.yaml

# 掃描特定的 Deployment
# --name 參數指定要分析的工作負載名稱
kubectl advise-psp inspect --grant --namespace production --name my-deployment > my-deployment-psp.yaml

# 掃描整個叢集的所有 Namespace
# 注意：在大型叢集中這可能需要較長時間
kubectl advise-psp inspect --grant --all-namespaces > cluster-wide-psp.yaml

# 只生成 PodSecurityPolicy，不生成 RBAC 資源
# 適用於需要自訂 RBAC 配置的場景
kubectl advise-psp inspect --namespace production > psp-only.yaml

# 以表格格式顯示分析結果
# --format table 參數會以表格形式展示各個 ServiceAccount 需要的權限
kubectl advise-psp inspect --namespace production --format table

# 輸出範例：
# NAMESPACE   SERVICE ACCOUNT   PRIVILEGED   HOST NETWORK   HOST PID   HOST IPC
# production  app-sa           false        false          false      false
# production  monitoring-sa    false        true           false      false

# kube-psp-advisor 自動生成的配置
# 這是針對 psp-test Namespace 中 sa-1 ServiceAccount 的工作負載生成的策略

# 第一部分：PodSecurityPolicy 定義
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  # 命名格式：psp-for-<namespace>-<serviceaccount>
  # 這種命名方式清楚標示了策略的適用範圍
  name: psp-for-psp-test-sa-1
  labels:
    generated-by: kube-psp-advisor
    namespace: psp-test
    serviceaccount: sa-1
  annotations:
    # 記錄生成時間與工具版本
    generated-at: "2025-11-28T03:00:00Z"
    generator-version: "1.0.0"
spec:
  # 根據工作負載實際使用的能力來設定
  # 此工作負載需要 SYS_ADMIN 能力，可能用於執行特定的系統管理操作
  # 例如掛載檔案系統或修改命名空間設定
  allowedCapabilities:
    - SYS_ADMIN
  
  # 根據工作負載掛載的主機路徑來設定
  # 此工作負載需要存取 /usr/bin 目錄，且限制為唯讀
  # 可能是為了執行主機上的某些工具程式
  allowedHostPaths:
    - pathPrefix: /usr/bin
      readOnly: true
  
  # 此工作負載需要存取主機的各種命名空間
  # 這些設定雖然較為寬鬆，但反映了工作負載的實際需求
  # 可能是監控代理或系統管理工具
  hostIPC: true      # 允許使用主機 IPC 命名空間
  hostNetwork: true  # 允許使用主機網路命名空間
  hostPID: true      # 允許使用主機 PID 命名空間
  
  # 允許綁定主機連接埠
  # 這通常用於需要直接暴露在主機網路上的服務
  hostPorts:
    - min: 0
      max: 65535
  
  # fsGroup 設定允許任意群組 ID
  # 這是因為工作負載沒有特別指定 fsGroup
  fsGroup:
    rule: RunAsAny
  
  # runAsUser 設定允許任意使用者 ID
  # 工作負載可能需要以 root 身份執行某些操作
  runAsUser:
    rule: RunAsAny
  
  # SELinux 設定允許任意標籤
  seLinux:
    rule: RunAsAny
  
  # supplementalGroups 設定允許任意補充群組
  supplementalGroups:
    rule: RunAsAny
  
  # 根據工作負載使用的 Volume 類型來設定
  # 此工作負載使用了 configMap、secret 與 hostPath
  volumes:
    - configMap
    - secret
    - hostPath
    - emptyDir
    
  # 允許權限提升
  # 這是因為工作負載需要執行需要提權的操作
  allowPrivilegeEscalation: true
  
  # 不要求唯讀根檔案系統
  # 工作負載可能需要寫入檔案
  readOnlyRootFilesystem: false

---
# 第二部分：ClusterRole 定義
# 授權使用上述 PodSecurityPolicy
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: use-psp-by-psp-test:sa-1
  labels:
    generated-by: kube-psp-advisor
    namespace: psp-test
    serviceaccount: sa-1
rules:
  - apiGroups:
      - policy
    # 指定此 ClusterRole 可以使用的 PSP
    resourceNames:
      - psp-for-psp-test-sa-1
    resources:
      - podsecuritypolicies
    # use 是一個特殊的動詞，只適用於 PSP
    verbs:
      - use

---
# 第三部分：RoleBinding 定義
# 將 ClusterRole 繫結到 ServiceAccount
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: use-psp-by-psp-test:sa-1-binding
  namespace: psp-test
  labels:
    generated-by: kube-psp-advisor
    serviceaccount: sa-1
# 指定要繫結的角色
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: use-psp-by-psp-test:sa-1
# 指定被授權的主體
subjects:
  - kind: ServiceAccount
    name: sa-1
    namespace: psp-test

# 建立 Anchore Engine 的工作目錄
# 所有相關檔案都會放在這個目錄中
mkdir -p ~/anchore-engine && cd ~/anchore-engine

# 下載官方提供的 docker-compose.yaml 檔案
# 這個檔案定義了 Anchore Engine 的所有元件與相依服務
curl -O https://engine.anchore.io/docs/quickstart/docker-compose.yaml

# 檢視 docker-compose.yaml 的內容
# 瞭解會啟動哪些服務
cat docker-compose.yaml

# docker-compose.yaml 通常包含以下服務：
# - anchore-engine：核心引擎
# - anchore-db：PostgreSQL 資料庫，儲存分析結果與策略
# - catalog：負責映像倉庫的整合
# - simplequeue：內部訊息佇列
# - analyzer：映像分析服務
# - policy-engine：策略評估服務

# 啟動 Anchore Engine
# -d 參數表示在背景執行
docker-compose up -d

# 檢查所有服務的執行狀態
# 所有服務都應該顯示為 Up 且狀態為 healthy
docker-compose ps

# 預期輸出範例：
#         Name                       Command               State           Ports
# ---------------------------------------------------------------------------------
# anchore_engine_1       /docker-entrypoint.sh anch ...   Up      8228/tcp
# anchore_db_1          docker-entrypoint.sh postgres    Up      5432/tcp

# 查看服務日誌
# 確認啟動過程沒有錯誤
docker-compose logs -f anchore-engine

# 等待服務完全啟動（可能需要 2-3 分鐘）
# Anchore Engine 需要初始化資料庫並下載漏洞資料

# 安裝 Anchore CLI 工具
# CLI 工具提供了便捷的命令列介面來操作 Anchore Engine
pip install anchorecli

# 或使用 pip3 安裝（Python 3 環境）
pip3 install anchorecli

# 驗證安裝是否成功
anchore-cli --version

# 設定環境變數以連接 Anchore Engine
# 這些變數告訴 CLI 如何連接到 Engine 以及使用什麼憑證
export ANCHORE_CLI_URL=http://localhost:8228/v1
export ANCHORE_CLI_USER=admin
export ANCHORE_CLI_PASS=foobar

# 將這些設定加入 shell 組態檔以持久化
cat >> ~/.bashrc <<EOF
# Anchore Engine Configuration
export ANCHORE_CLI_URL=http://localhost:8228/v1
export ANCHORE_CLI_USER=admin
export ANCHORE_CLI_PASS=foobar
EOF

# 重新載入 shell 設定
source ~/.bashrc

# 確認 Anchore Engine 已就緒
# 這個命令會顯示各個服務的狀態
anchore-cli system status

# 預期輸出範例：
# Service         | Host         | State | Version
# ----------------+--------------+-------+--------
# catalog         | anchore      | up    | 1.0.0
# analyzer        | anchore      | up    | 1.0.0
# policy_engine   | anchore      | up    | 1.0.0

# 等待漏洞資料庫同步完成
# 初次啟動時，Anchore Engine 需要從上游同步 CVE 資料
# 這個過程可能需要 10-15 分鐘
anchore-cli system feeds list

# 當所有 feed 的狀態都顯示為 'synced' 時，表示同步完成
# 預期輸出範例：
# Feed              | Group         | LastSync                  | RecordCount
# ------------------+---------------+---------------------------+-------------
# vulnerabilities   | ubuntu:20.04  | 2025-11-28T03:00:00       | 15234
# vulnerabilities   | debian:11     | 2025-11-28T03:00:00       | 23456

# 新增映像到 Anchore Engine 進行分析
# Anchore Engine 會下載映像（如果本地不存在）並提取各層內容
anchore-cli image add docker.io/library/nginx:latest

# 輸出範例：
# Image Digest: sha256:abc123...
# Analysis Status: analyzing
# Image ID: def456...

# 列出所有已加入的映像
anchore-cli image list

# 等待分析完成
# --timeout 參數設定最長等待時間（秒）
# 大型映像的分析可能需要數分鐘
anchore-cli image wait docker.io/library/nginx:latest --timeout 600

# 分析完成後會顯示：
# Status: analyzed

# 查看映像的基本資訊
# 包括大小、建立時間、標籤等
anchore-cli image get docker.io/library/nginx:latest

# 掃描作業系統層的漏洞
# 這會比對 Debian/Ubuntu/Alpine/RHEL 等系統的漏洞資料庫
anchore-cli image vuln docker.io/library/nginx:latest os

# 輸出範例：
# Vulnerability ID      Package            Severity   Fix         
# CVE-2021-33574       glibc-2.31-13      High       2.31-14
# CVE-2021-35942       glibc-2.31-13      High       2.31-14
# CVE-2022-23218       glibc-2.31-13      Low        None

# 掃描非作業系統的套件漏洞
# 例如 Python pip、Node.js npm、Ruby gem、Java maven 等
anchore-cli image vuln docker.io/library/nginx:latest non-os

# 查看所有類型的漏洞
# 這會同時顯示 OS 與 non-OS 的漏洞
anchore-cli image vuln docker.io/library/nginx:latest all

# 以 JSON 格式輸出漏洞報告
# 方便程式化處理或整合到其他系統
anchore-cli --json image vuln docker.io/library/nginx:latest all > nginx-vulnerabilities.json

# 執行策略評估
# 這會根據預設或自訂的策略檢查映像是否符合規範
anchore-cli evaluate check docker.io/library/nginx:latest --detail

# 策略評估會檢查多個面向：
# - 是否存在高風險漏洞
# - 是否以 root 使用者執行
# - 是否包含敏感檔案
# - 套件版本是否符合要求
# - 等等

# 查看映像中安裝的所有作業系統套件
# 這可以幫助瞭解映像的組成
anchore-cli image content docker.io/library/nginx:latest os

# 查看映像的完整檔案清單
# 可以用來檢查是否包含不應該存在的檔案
anchore-cli image content docker.io/library/nginx:latest files

# 搜尋特定檔案或路徑
# 例如搜尋是否包含私鑰檔案
anchore-cli image content docker.io/library/nginx:latest files | grep -i "\.key$"

# 比較兩個映像的差異
# 這在更新基礎映像或升級版本時很有用
anchore-cli image diff docker.io/library/nginx:1.20 docker.io/library/nginx:latest

# 刪除不再需要的映像分析結果
# 釋放資料庫空間
anchore-cli image del docker.io/library/nginx:latest

# GitLab CI/CD 完整配置範例
# 此配置展示如何建立包含映像掃描的安全 CI/CD 流程

# 定義流程的各個階段
# 嚴格的階段順序確保安全檢查在部署前完成
stages:
  - build      # 建置階段：編譯程式碼、建置映像
  - scan       # 掃描階段：執行安全掃描與策略評估
  - deploy     # 部署階段：部署到目標環境

# 設定全域變數
variables:
  # 映像名稱，使用 CI 環境變數組成完整的映像標籤
  # CI_REGISTRY_IMAGE：專案的 Registry 路徑
  # CI_COMMIT_SHA：Git commit 的 SHA 值，確保映像版本可追溯
  IMAGE_NAME: ${CI_REGISTRY_IMAGE}:${CI_COMMIT_SHA}
  
  # Anchore Engine 的連線資訊
  ANCHORE_CLI_URL: "http://anchore-engine.internal:8228/v1"
  ANCHORE_CLI_USER: "admin"
  # 注意：密碼應該透過 GitLab CI/CD 保護變數設定
  # 而不是直接寫在配置檔中
  # ANCHORE_CLI_PASS 應在 Settings > CI/CD > Variables 中設定
  
  # Docker 建置參數
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: "/certs"

# 建置階段：建置並推送容器映像
build-image:
  stage: build
  # 使用 Docker-in-Docker 服務
  # 這允許在 CI 環境中執行 Docker 命令
  image: docker:latest
  services:
    - docker:dind
  # 只在特定分支或標籤時執行
  only:
    - main
    - develop
    - /^release-.*$/
    - tags
  script:
    # 登入容器 Registry
    # CI_REGISTRY_USER 和 CI_REGISTRY_PASSWORD 是 GitLab 自動提供的變數
    - docker login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY}
    
    # 建置映像並加上 commit SHA 作為標籤
    # --pull 確保使用最新的基礎映像
    # --build-arg 可以傳遞建置時需要的參數
    - docker build 
        --pull 
        --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
        --build-arg VCS_REF=${CI_COMMIT_SHA}
        --tag ${IMAGE_NAME} 
        .
    
    # 推送映像到 Registry
    - docker push ${IMAGE_NAME}
    
    # 如果是 main 分支，額外標記為 latest
    - |
      if [ "${CI_COMMIT_BRANCH}" == "main" ]; then
        docker tag ${IMAGE_NAME} ${CI_REGISTRY_IMAGE}:latest
        docker push ${CI_REGISTRY_IMAGE}:latest
      fi

# 掃描階段：使用 Anchore Engine 掃描映像
scan-image:
  stage: scan
  # 使用包含 Anchore CLI 的官方映像
  image: anchore/engine-cli:latest
  # 需要建置階段先完成
  needs:
    - build-image
  # 只在特定分支執行
  only:
    - main
    - develop
    - /^release-.*$/
    - tags
  before_script:
    # 確認環境變數已正確設定
    - echo "Anchore CLI URL:${ANCHORE_CLI_URL}"
    - echo "Scanning image:${IMAGE_NAME}"
    
    # 驗證 Anchore Engine 是否可連接
    - anchore-cli system status || exit 1
  script:
    # 新增映像到 Anchore Engine 進行分析
    - anchore-cli image add ${IMAGE_NAME}
    
    # 等待映像分析完成
    # --timeout 600 設定最長等待 10 分鐘
    - anchore-cli image wait ${IMAGE_NAME} --timeout 600
    
    # 執行漏洞掃描並輸出報告
    - echo "=== 漏洞掃描結果 ==="
    - anchore-cli image vuln ${IMAGE_NAME} all
    
    # 將漏洞報告儲存為 JSON 格式
    - anchore-cli --json image vuln ${IMAGE_NAME} all > vulnerabilities.json
    
    # 執行策略評估
    # 若評估失敗會回傳非零的結束碼，導致流程中斷
    - echo "=== 策略評估結果 ==="
    - anchore-cli evaluate check ${IMAGE_NAME} --detail
    
    # 產生詳細的評估報告
    - anchore-cli --json evaluate check ${IMAGE_NAME} --detail > policy-evaluation.json
    
    # 檢查是否存在高風險或嚴重漏洞
    # 這個檢查會在策略評估通過但仍有漏洞時額外執行
    - |
      CRITICAL_COUNT=$(jq '[.vulnerabilities[] | select(.severity=="Critical")] | length' vulnerabilities.json)
      HIGH_COUNT=$(jq '[.vulnerabilities[] | select(.severity=="High")] | length' vulnerabilities.json)
      
      echo "嚴重漏洞數量：${CRITICAL_COUNT}"
      echo "高風險漏洞數量：${HIGH_COUNT}"
      
      # 如果存在嚴重漏洞，中斷流程
      if [ ${CRITICAL_COUNT} -gt 0 ]; then
        echo "錯誤：發現 ${CRITICAL_COUNT} 個嚴重漏洞，中斷部署"
        exit 1
      fi
      
      # 如果高風險漏洞超過閾值，發出警告但不中斷（可視需求調整）
      if [ ${HIGH_COUNT} -gt 5 ]; then
        echo "警告：發現 ${HIGH_COUNT} 個高風險漏洞，超過建議閾值"
      fi
  # 失敗時不允許繼續
  allow_failure: false
  # 保留掃描報告作為成品
  artifacts:
    name: "security-scan-reports-${CI_COMMIT_SHA}"
    when: always
    paths:
      - vulnerabilities.json
      - policy-evaluation.json
    reports:
      # GitLab 可以解析這個報告並在 MR 中顯示
      container_scanning: vulnerabilities.json
    expire_in: 30 days

# 部署階段：部署到 Kubernetes
deploy-to-dev:
  stage: deploy
  image: bitnami/kubectl:latest
  # 只在掃描通過後執行
  needs:
    - scan-image
  # 只在 develop 分支自動部署到開發環境
  only:
    - develop
  environment:
    name: development
    url: https://dev.example.com
  before_script:
    # 設定 kubectl 連線資訊
    - kubectl config set-cluster ${KUBE_CLUSTER} --server=${KUBE_SERVER}
    - kubectl config set-credentials deployer --token=${KUBE_TOKEN}
    - kubectl config set-context default --cluster=${KUBE_CLUSTER} --user=deployer
    - kubectl config use-context default
  script:
    # 更新 Deployment 的映像版本
    - kubectl set image deployment/${APP_NAME} 
        ${APP_NAME}=${IMAGE_NAME} 
        -n development
    
    # 等待部署完成
    - kubectl rollout status deployment/${APP_NAME} -n development --timeout=5m
    
    # 驗證新 Pod 是否正常運作
    - kubectl get pods -n development -l app=${APP_NAME}

deploy-to-prod:
  stage: deploy
  image: bitnami/kubectl:latest
  needs:
    - scan-image
  # 只在 main 分支或 release 標籤時可用
  only:
    - main
    - /^v\d+\.\d+\.\d+$/
  environment:
    name: production
    url: https://www.example.com
  before_script:
    - kubectl config set-cluster ${KUBE_CLUSTER} --server=${KUBE_SERVER}
    - kubectl config set-credentials deployer --token=${KUBE_TOKEN}
    - kubectl config set-context default --cluster=${KUBE_CLUSTER} --user=deployer
    - kubectl config use-context default
  script:
    # 生產環境部署前的額外檢查
    - echo "準備部署到生產環境"
    - echo "映像：${IMAGE_NAME}"
    
    # 更新 Deployment
    - kubectl set image deployment/${APP_NAME} 
        ${APP_NAME}=${IMAGE_NAME} 
        -n production
    
    # 等待部署完成並驗證
    - kubectl rollout status deployment/${APP_NAME} -n production --timeout=10m
    
    # 執行部署後的健康檢查
    - curl -f https://www.example.com/health || exit 1
  # 生產環境部署需要手動觸發
  when: manual