本指南說明如何使用 Security Command Center API 管理安全標記。安全標記 (或稱「標記」) 是 Security Command Center 中資產或發現結果的可自訂註解,可讓您為這些物件新增自己的業務背景資訊。
您只能在 Security Command Center 支援的資產上新增或更新安全標記。如需 Security Command Center 支援的資產清單,請參閱「Security Command Center 支援的資產類型」。
事前準備
您必須先設定服務帳戶和 SDK,才能使用安全標記。
如要新增或變更安全性標記,您必須具備包含權限的 Identity and Access Management 角色,才能使用所需類型的標記:
- 資產標記:資產安全標記寫入者、
securitycenter.assetSecurityMarksWriter
- 發現項目標記:發現項目安全標記寫入者、
securitycenter.findingSecurityMarksWriter
如要進一步瞭解 Security Command Center 中的 IAM 角色,請參閱存取權控管。如要瞭解如何有效使用安全標記,請參閱「使用 Security Command Center 安全標記」。
在資產上新增或更新安全標記
使用 Security Command Center API 時,新增和更新安全性標記是相同的作業。以下範例說明如何為鍵/值組合 (key_a, value_a)
和 (key_b, value_b)
新增安全標記。
下列程式碼會使用欄位遮罩,確保只更新這些值。如果未提供欄位遮罩,系統會先清除所有安全標記,再新增指定的鍵和值。
gcloud
gcloud scc assets update-marks ASSET_ID \ --PARENT=PARENT_ID \ --location=LOCATION \ --security-marks=SECURITY_MARKS \ --update-mask=UPDATE_MASK
更改下列內容:
ASSET_ID
:要更新的資產。PARENT
:資產所在的資源階層層級;請使用organization
、folder
或project
。PARENT_ID
:父項機構、資料夾或專案的數值 ID,或是父項專案的英數 ID。LOCATION
:要更新資產安全標記的 Security Command Center 位置;如果已啟用資料落地功能,請使用eu
、ksa
或us
,否則請使用值global
。SECURITY_MARKS
:以半形逗號分隔的鍵/值組合,代表安全標記及其值,例如key_a=value_a,key_b=value_b
。UPDATE_MASK
:以半形逗號分隔的安全性標記欄位清單,用於更新資產;例如marks.key_a,marks.key_b
。
Go
Python
如要瞭解安全狀態分析偵測器的專屬資產標記,請參閱「管理政策」。
刪除資產的安全標記
刪除特定安全標記的方式與新增或更新標記類似,具體來說,就是呼叫 update,並使用欄位遮罩,但不提供任何對應值。在這個範例中,系統會刪除含有 key_a
和 key_b
鍵的安全標記。
gcloud
gcloud scc assets update-marks ASSET_ID \ --PARENT=PARENT_ID \ --location=LOCATION \ --update-mask=UPDATE_MASK
ASSET_ID
:要更新的資產。PARENT
:資產所在的資源階層層級;請使用organization
、folder
或project
。PARENT_ID
:父項機構、資料夾或專案的數值 ID,或是父項專案的英數 ID。LOCATION
: 要從資產中刪除安全標記的 Security Command Center 位置;如果已啟用資料落地功能,請使用eu
、ksa
或us
;否則請使用global
值。UPDATE_MASK
:以半形逗號分隔的清單,列出要從資產中刪除的安全標記欄位,例如marks.key_a,marks.key_b
。
Node.js
Python
在同一個要求中新增及刪除安全標記
您可以在同一個要求中,同時新增、更新及刪除安全標記。在這個範例中,key_a
會更新,而 key_b
則會刪除。
gcloud
gcloud scc assets update-marks ASSET_ID \ --PARENT=PARENT_ID \ --location=LOCATION \ --update-mask=UPDATE_MASK
ASSET_ID
:要更新的資產。PARENT
:資產所在的資源階層層級;請使用organization
、folder
或project
。PARENT_ID
:父項機構、資料夾或專案的數值 ID,或是父項專案的英數 ID。LOCATION
: 要更新及刪除資產安全標記的Security Command Center 位置;如果已啟用資料落地功能,請使用eu
、ksa
或us
;否則請使用global
值。SECURITY_MARKS
:以半形逗號分隔的鍵/值配對,代表要更新的安全標記,例如key_a=value_a
;如要刪除安全標記,請省略該標記UPDATE_MASK
:以半形逗號分隔的清單,列出要更新或刪除的安全標記欄位,例如marks.key_a,marks.key_b
。
Node.js
Python
為發現項目新增安全標記
新增、更新及刪除發現項目的安全標記,與更新資產安全標記的程序相同。唯一的變更是 API 呼叫中使用的資源名稱。您提供的是發現項目資源名稱,而非資產資源。
舉例來說,如要更新發現項目的安全標記,請使用下列程式碼:
gcloud
gcloud scc findings update-marks FINDING_NAME \ --PARENT=PARENT_ID \ --location=LOCATION \ --source=SOURCE_ID \ --security-marks=SECURITY_MARKS \ --update-mask=UPDATE_MASK
更改下列內容:
FINDING_NAME
:要更新的發現項目。PARENT
:發現項目所在的資源階層層級;請使用organization
、folder
或project
。PARENT_ID
:父項機構、資料夾或專案的數值 ID,或是父項專案的英數 ID。LOCATION
: 要更新發現項目安全標記的 Security Command Center 位置;如果已啟用資料落地功能,請使用eu
、ksa
或us
;否則請使用global
值。SOURCE_ID
:來源 ID。SECURITY_MARKS
:以半形逗號分隔的鍵/值組合,代表安全標記及其值,例如key_a=value_a,key_b=value_b
。UPDATE_MASK
:以半形逗號分隔的安全性標記欄位清單,用於更新資產;例如marks.key_a,marks.key_b
。
Java
Node.js
Python
安全標記是在批次掃描期間處理,批次掃描每天執行兩次,而非即時處理。系統可能需要 12 到 24 小時,才會處理安全性標記,並套用解決或重新開啟調查結果的強制執行政策。
列出含有安全標記篩選器的資產
在資產上設定安全標記後,即可在 ListAssets
API 呼叫的篩選器引數中使用這些標記。舉例來說,如要查詢 key_a = value_a
的所有資產,請使用下列程式碼:
gcloud
# ORGANIZATION=12344321 FILTER="security_marks.marks.key_a = \"value_a\"" gcloud scc assets list $ORGANIZATION \ --filter="$FILTER"
Go
Java
Node.js
Python
列出含有安全標記篩選器的發現項目
在發現項目上設定安全性標記後,即可在 ListFindings
API 呼叫的篩選器引數中使用這些標記。舉例來說,如要查詢 key_a != value_a
的所有資產,請使用下列程式碼:
gcloud
gcloud scc findings list PARENT/PARENT_ID \ --location=LOCATION \ --source=SOURCE_ID \ --filter=FILTER
PARENT
:發現項目所在的資源階層層級;請使用organizations
、folders
或projects
。PARENT_ID
:父項機構、資料夾或專案的數值 ID,或是父項專案的英數 ID。LOCATION
:要列出調查結果的Security Command Center 位置;如果已啟用資料落地功能,請使用eu
、ksa
或us
;否則請使用global
值。SOURCE_ID
:來源 ID。FILTER
:要套用至發現項目的篩選器;舉例來說,如要排除含有安全標記key_a=value_a
的發現項目,請使用"NOT security_marks.marks.key_a=\"value_a\""