安全性分數和設定檔 API

本頁內容適用於 ApigeeApigee 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。
  • $TOKENOAuth 存取權杖的環境變數。

擷取批次安全評估結果

具有 Security AdminSecurity 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 管理安全性設定檔的範例,但並未詳盡列出所有情況。詳情請參閱安全設定檔 V2 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 可以是下列任一值 (如有):descriptionprofile_assessment_configsdescription,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,則 CONDITION_UPDATE_MASK 可以是 includeinclude_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

風險評估第 1 版

本節提供 Risk Assessment v1 API 的相關資訊和範例。

使用 API 時的安全分數限制

透過安全性分數和設定檔 API 使用安全性分數時,有下列限制:

  • JSON 支援的輸入欄位:
  • 系統不支援多個輸入篩選器。
  • 系統不支援回覆中的影響欄位。(「影響」欄位是指這項建議對整體分數的潛在影響。這表示這項建議對提高分數有多重要。)

如要瞭解與 API 使用無關的一般安全分數限制,請參閱「安全分數第 1 版的限制」。

範例 API 呼叫中的參數

以下各節提供 API 呼叫範例,並可使用下列參數:

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

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

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

風險評估 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
特定 Proxy 的中介服務政策分數 /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"