安全性分數和設定檔 API

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

本頁面說明如何使用 API 管理風險評估安全分數和安全性設定檔 (簡稱「設定檔」)。本頁面會列出 API 要求範例。

如需風險評估功能的總覽 (包括限制) 以及使用 UI 的操作說明，請參閱「風險評估總覽和 UI」。

Risk Assessment v2 API 範例

v2 API 範例的參數

本節的範例可使用下列參數：

  • ORG 是貴機構。
  • ENV 是您要計算分數的環境。
  • PROFILE_ID 是設定檔的名稱。PROFILE_ID 可以是 google-default，或是您建立的自訂設定檔名稱。
  • PROFILE_DESC (選用) 是設定檔的說明。這應是可供人類閱讀的設定檔說明，提供足夠資訊，以便與其他設定檔區分開來。
  • PROXY_NAME：Proxy 的名稱。
  • RESOURCES 可以是：
    • "include_all_resources":{} 監控範圍內的所有資源。
    • "include": { "resources": [{"type": "API_PROXY", "name": "PROXY_NAME"}]} 可用於監控一或多個指定 Proxy。例如，"include": { "resources": [{"type": "API_PROXY", "name": "my-proxy-1"}]} 可用於監控名為 my-proxy-1 的 Proxy。
  • SECURITY_MONITORING_CONDITION_ID：安全監控條件的專屬 ID。如果未提供 ID，系統會自動產生 UUID。
  • $TOKEN 是 OAuth 存取權杖的環境變數。

擷取批次安全性評估結果

具有 Security Admin 或 Security Viewer 角色的使用者具備執行臨時風險評估運算的權限。您必須指定安全性設定檔、範圍 (Apigee 環境) 和要評估的資源。資源可以是 include_all_resources: true，用於計算範圍內的所有資源，或僅計算少數資源。如要進一步瞭解這項功能，請參閱 Apigee Management API 參考資料文件中的 securityAssessmentResults.batchCompute。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
           "profile": "PROFILE_ID",
           "scope": "ENV",
           RESOURCES
  }'

以下是要求的可能回應：

{
  "securityAssessmentResults": [
    {
      "resource": {
        "type": "API_PROXY",
        "name": "my-proxy-1",
        "resourceRevisionId": "1"
      },
      "createTime": "2023-11-22T04:49:29.418166Z",
      "scoringResult": {
        "severity": "HIGH",
        "failedAssessmentPerWeight": {
          "MINOR": 1
        },
        "assessmentRecommendations": {
          "cors-policies-check": {
            "displayName": "CORS policies check",
            "weight": "MAJOR",
            "recommendations": [
              {
                "description": "Check whether a CORS policy or CORS header in AssignMessage policy are present.",
                "link": {
                  "text": "Learn more",
                  "uri": "https://cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy"
                }
              }
            ],
            "verdict": "FAIL",
            "scoreImpact": 100
          }
        },
        "dataUpdateTime": "2023-11-22T04:49:29.418166Z"
      }
    }
  ],
  "assessmentTime": "2023-11-22T04:49:29.418166Z"
}

管理安全性設定檔

本節提供使用 API 管理安全性設定檔的示例，但不包含所有示例。詳情請參閱 securityProfilesV2 API 參考資料文件。

取得現有的自訂安全性設定檔

這個指令會擷取專案的所有安全性設定檔資訊：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

這個指令可擷取特定安全性設定檔的中繼資料，並可用於擷取 google-default 設定檔和自訂設定檔的資訊：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

建立新的自訂安全性設定檔

如要建立新的自訂安全性設定檔，請使用以下指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
           "description": "PROFILE_DESC",
           "profile_assessment_configs": {
               "auth-policies-check": {"weight": "MINOR"},
               "threat-policies-check": {"weight": "MODERATE"}
           }
        }'

更新現有的自訂安全性設定檔

如要更新現有設定檔，請使用以下指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

其中 UPDATE_MASK 可以是下列任一值 (如有)：description、profile_assessment_configs、description,profile_assessment_configs 或 * (所有)。如果指定 * 更新遮罩，要求會更新所有欄位，如果這些欄位未包含在要求中，則可能會移除值。

如果省略 update_mask，系統只會更新更新要求中提供的欄位。

刪除自訂安全性設定檔

刪除自訂安全性設定檔：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

管理監控條件

本節提供使用 API 管理監控條件的示例，但並未涵蓋所有情況。如要進一步瞭解如何透過 API 管理監控條件，請參閱 監控條件 API 參考資料文件。

建立新的監控條件

如要建立新的監控條件，請使用以下指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?security_monitoring_condition_id=MONITORING_CONDITION_ID" \
       -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
           "profile": "PROFILE_ID",
           "scope": "ENV",
           RESOURCES
       }'

回應可能如下所示：

{
  "name": "organizations/my-org/securityMonitoringConditions/my-condition",
  "createTime": "2025-11-22T05:02:16.089469Z",
  "updateTime": "2023-11-22T05:02:16.089469Z",
  "profile": "google-default",
  "scope": "test",
  "totalMonitoredResources": 4,
  "totalDeployedResources": 4,
  "includeAllResources": {}
}

列出監控條件

如要取得貴機構的監控條件清單，請使用以下指令：

curl -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions"

回應的格式如下：

{
  "securityMonitoringConditions": [
    {
      "name": "organizations/my-org/securityMonitoringConditions/my-condition",
      "createTime": "2023-11-22T05:02:16.089469Z",
      "updateTime": "2025-11-22T05:02:16.089469Z",
      "profile": "google-default",
      "scope": "test",
      "totalMonitoredResources": 4,
      "totalDeployedResources": 4,
      "includeAllResources": {}
    }
  ]
}

您也可以使用以下語法，依範圍或安全設定限制傳回的結果：

curl -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?filter=scope=ENV%20AND%20profile=PROFILE_ID"

取得現有的監控條件

如要取得現有監控條件的相關資訊，請使用以下指令：

curl -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID"

回應的格式如下：

{
  "name": "organizations/my-org/securityMonitoringConditions/my-condition",
  "createTime": "2023-11-22T05:02:16.089469Z",
  "updateTime": "2025-11-22T05:02:16.089469Z",
  "profile": "google-default",
  "scope": "test",
  "totalMonitoredResources": 4,
  "totalDeployedResources": 4,
  "includeAllResources": {}
}

更新現有的監控條件

此指令會更新現有監控條件的設定檔：

curl -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID?update_mask=CONDITION_UPDATE_MASK" -X PATCH -H "Content-Type: application/json" \
       -d  '{
       RESOURCES
  }'

其中 update_mask 為選用。如果包含，CONDITION_UPDATE_MASK 可以是 include 或 include_all_resources。省略 update_mask 只會更新更新要求中提供的欄位。

回應可能如下所示：

{
  "name": "test-condition",
  "createTime": "2023-11-22T03:04:05Z",
  "updateTime": "2023-11-22T03:04:05Z",
  "profile": "google-default",
  "scope": "test",
  "include": {
    "resources": [{
      "type": "API_PROXY", "name": "PROXY_NAME"
    }]
  }
}

刪除監控條件

這項指令會刪除現有的監控條件：

curl -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID" \
       -X DELETE

風險評估 v1

本節將說明 Risk Assessment v1 API 的相關資訊和範例。

使用 API 時的安全性分數限制

從安全分數和設定檔 API 使用安全分數時，安全分數有下列限制：

  • JSON 中支援的輸入欄位：
  • 不支援多個輸入篩選器。
  • 回應中不支援影響欄位。(影響欄位是指這項最佳化建議對整體分數的潛在影響。這表示這項最佳化建議對改善分數的重要性)。

如要瞭解一般安全分數限制 (不限於透過 API 使用)，請參閱「安全分數 v1 的限制」。

範例 API 呼叫中的參數

以下各節提供 API 呼叫範例，可使用下列參數：

  • ORG 是貴機構。
  • ENV 是您要計算分數的環境。
  • ENVGROUP 是包含環境的環境群組。
  • PROFILE_ID 是設定檔的名稱。PROFILE_ID 可以是 default 或您建立的自訂設定檔名稱。

    PROFILE_ID 必須包含 1 至 63 個半形字元，可以是小寫英文字母、數字 0 到 9 或連字號。開頭須為小寫英文字母，最後一個字元則須為小寫英文字母或數字。

  • PROXY_NAME：Proxy 的名稱。
  • $TOKEN 是 OAuth 存取權杖的環境變數。
  • timeRange 是分數的時間範圍。

Risk Assessment v1 API 範例

API 支援的篩選器

下表列出 API 支援的篩選器，以及相關元件路徑。

篩選器 元件路徑
環境分數 /org@ORG/envgroup@ENVGROUP/env@ENV
來源會為所有基礎元件評分 /org@ORG/envgroup@ENVGROUP/env@ENV/source
濫用行為分數 /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse
所有 Proxy 的分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies
特定 Proxy 的分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME
特定 Proxy 的政策分數
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual
特定代理程式適用的中介服務政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation
特定 Proxy 的安全性政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security
特定 Proxy 的驗證政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth
特定 Proxy 的 CORS 政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors
特定 Proxy 的威脅政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat
環境中所有 Proxy 的政策分數
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual
環境中所有 Proxy 的中介服務政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation
環境中所有 Proxy 的安全性政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security
環境中所有 Proxy 的驗證政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth
環境中所有 Proxy 的 CORS 政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors
環境中所有 Proxy 的威脅政策分數 /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat

使用預設安全性設定檔

以下範例說明如何使用預設安全性設定檔。如要瞭解範例中使用的參數，請參閱「範例 API 呼叫中的參數」。

將預設安全性設定檔附加至環境

如要查看安全分數，您必須將設定檔附加至要評估安全性的環境。如要將預設安全性設定檔附加至環境，請使用下列指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
取得預設安全性設定檔定義

如要取得預設安全性設定檔的定義，請輸入下列指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

從環境中卸離預設安全性設定檔

如果您需要將預設設定檔從環境中分離，可以按照以下步驟操作：

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

使用自訂安全性設定檔

您可以透過下列任一方式，使用 API 呼叫建立 自訂安全性設定檔：

  • 在呼叫主體中明確定義設定檔。
  • 將含有設定檔定義的 JSON 檔案附加至呼叫。

以下各節將提供這兩種方法的範例。如要瞭解範例中使用的參數，請參閱「範例 API 呼叫中的參數」。

範例 API 呼叫中的下列欄位會指定自訂設定檔：

  • description：自訂設定檔的說明。
  • profileConfig：要納入自訂設定檔的類別清單。這可以是下列安全性類別的任何子集：
    • abuse
    • authorization
    • cors
    • mtls
    • mediation
    • threat
在 API 呼叫的主體中定義設定檔

如要在 API 呼叫的主體中定義自訂設定檔，請輸入類似以下的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile",
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

這會建立包含 cors 和 threat 類別的自訂設定檔，並傳回類似以下的回應：

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }
將 JSON 檔案附加至 API 呼叫，藉此定義設定檔

您也可以附加 JSON 檔案，藉此定義 API 呼叫的設定檔，進而定義自訂安全性設定檔。舉例來說，請先建立下列 JSON 檔案：

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

這會定義包含類別 cors 和 threat 的設定檔。接著，您可以根據這些類別建立設定檔，如下所示：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

其中 create_profile.json 是上述 JSON 檔案的名稱。

取得自訂安全性設定檔定義

如要取得自訂安全性設定檔的定義，請輸入類似下列的指令：

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"
將自訂安全性設定檔從環境中分離

如要將自訂安全性設定檔從環境中分離，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"
刪除自訂安全性設定檔

如要刪除自訂安全性設定檔，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

取得環境的比數

以下各節提供取得環境分數的範例。如要瞭解範例中使用的參數，請參閱「範例 API 呼叫中的參數」。

取得環境的所有分數

如要取得環境的所有分數，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

如需要求和回應的說明，請參閱 computeEnvironmentScores 參考頁面。

取得環境的來源分數

如要取得環境來源分數，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
取得環境來源中的濫用分數

如要取得環境來源中的濫用分數，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
取得環境中所有 Proxy 的評分

如要取得環境中所有 Proxy 的評分，請輸入類似以下的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
取得環境中特定 Proxy 的評分

如要取得環境中特定 Proxy 的評分，請輸入類似以下的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

其中 PROXY 是您要取得分數的 proxy。

取得環境中特定目標的分數

如要取得環境中特定目標的分數，請輸入類似以下的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"