보안 점수 및 프로필 API

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

개요

이 페이지에서는 API를 사용하여 위험 평가 보안 점수와 보안 프로필(간단히 '프로필'이라고도 함)을 관리하는 방법을 설명합니다. 이 페이지에서는 API 요청 예시를 보여줍니다.

제한사항을 비롯한 위험 평가 기능 개요와 UI 사용 안내는 위험 평가 개요 및 UI를 참고하세요.

위험 평가 v2 API 예시

v2 API 예시의 매개변수

이 섹션의 예시에서는 다음 매개변수를 사용할 수 있습니다.

ORG는 사용자의 조직입니다.
ENV는 점수를 계산할 환경입니다.
PROFILE_ID는 프로필 이름입니다. PROFILE_ID는 google-default 또는 생성된 커스텀 프로필의 이름일 수 있습니다.
PROFILE_DESC(선택사항)는 프로필에 대한 설명입니다. 인간이 읽을 수 있는 프로필 설명으로, 다른 프로필과 구분할 수 있는 충분한 정보를 제공해야 합니다.
PROXY_NAME: 프록시의 이름
$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": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

다음은 이 요청에 대한 가능한 응답입니다.

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

보안 프로필 관리

이 섹션에서는 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"

위험 평가 v1

이 섹션에서는 위험 평가 v1 API에 관한 정보와 예시를 보여줍니다.

API를 사용할 때 보안 점수 제한사항

보안 점수를 보안 점수 및 Profiles API에서 사용할 때 보안 점수에는 다음과 같은 제한사항이 있습니다.

JSON에서 지원되는 입력 필드:
- timeRange: 값은 computEnvironmentScores API 참조에 설명된 기준에 따라 제한됩니다.
- filters: API에서 지원되는 필터를 참조하세요.
- pageSize: 단일 페이지에서 반환될 최대 하위 구성요소 수: 100개
다중 입력 필터는 지원되지 않습니다.
응답의 영향 필드는 지원되지 않습니다. (영향 필드는 이 권장사항이 전체 점수에 미칠 수 있는 잠재적 영향입니다. 이 권장사항이 점수 개선에 얼마나 중요한지를 나타냅니다.)

API에서 사용하는 데에만 적용되지 않는 일반적인 보안 점수 제한사항은 보안 점수 v1 제한사항을 참조하세요.

API 호출 예시의 매개변수

다음 섹션에서는 API 호출 예시를 제공하며 다음 파라미터를 사용할 수 있습니다.

ORG는 사용자의 조직입니다.
ENV는 점수를 계산할 환경입니다.
ENVGROUP은 환경이 포함된 환경 그룹입니다.
PROFILE_ID는 프로필 이름입니다. PROFILE_ID는 default 또는 생성한 커스텀 프로필의 이름일 수 있습니다.
PROFILE_ID는 1~63자(영문 기준)의 소문자, 숫자(0~9) 또는 하이픈으로 구성되어야 합니다. 첫 번째 문자는 소문자여야 합니다. 마지막 문자는 소문자 또는 숫자여야 합니다.
PROXY_NAME: 프록시의 이름
RESOURCES는 다음과 같을 수 있습니다.
- 범위 내의 모든 리소스의 경우 {"all_resources":true}
- 하나 이상의 지정된 프록시를 모니터링하려면 {"includes": { "resources": [{"name": "<proxy-name>"}]}. 예를 들어 my-proxy-1이라는 프록시를 모니터링하려면 {"includes": { "resources": [{"name": "my-proxy-1"}]}입니다.
- 하나 이상의 지정된 프록시를 제외한 모든 리소스를 모니터링하려면 {"excludes": { "resources": [{"name": "<proxy-name>"}]}. 예를 들어 {"excludes": { "resources": [{"name": "my-proxy-1"}]}은 my-proxy-1이라는 프록시를 제외한 모든 리소스를 모니터링합니다.
$TOKEN은 OAuth 액세스 토큰의 환경 변수입니다.
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`
모든 프록시의 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
특정 프록시의 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
특정 프록시의 정책 점수	`/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`
특정 프록시의 보안 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
특정 프록시의 인증 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
특정 프록시의 CORS 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
특정 프록시의 위협 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
환경의 모든 프록시에 대한 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
환경의 모든 프록시에 대한 미디에이션 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
환경의 모든 프록시에 대한 보안 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
환경의 모든 프록시에 대한 인증 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
환경의 모든 프록시에 대한 CORS 정책 점수	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
환경의 모든 프록시에 대한 위협 정책 점수	`/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"

참고: securityProfileRevisionId 파라미터는 지원 중단되었습니다. 이 파라미터를 API 호출에 포함하면 지능화된 API 보안에서 파라미터 값과 관계없이 프로필의 최신 버전을 사용합니다.

기본 보안 프로필 정의 가져오기

기본 보안 프로필의 정의를 가져오려면 다음 명령어를 입력합니다.

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 및 위협 카테고리가 포함된 커스텀 프로필이 생성되고 다음과 같은 응답이 반환됩니다.

{
  "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 및 위협 카테고리가 포함된 프로필이 정의됩니다. 그런 다음 다음과 같이 이러한 카테고리를 기반으로 프로필을 만들 수 있습니다.

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"

환경의 모든 프록시에 대한 점수 가져오기

환경의 모든 프록시에 대한 점수를 가져오려면 다음과 비슷한 명령어를 입력합니다.

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"

환경의 특정 프록시에 대한 점수 가져오기

환경의 특정 프록시에 대한 점수를 가져오려면 다음과 비슷한 명령어를 입력합니다.

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는 가져오려는 점수에 해당하는 프록시입니다.

환경의 특정 타겟에 대한 점수 가져오기

환경의 특정 타겟에 대한 점수를 가져오려면 다음과 비슷한 명령어를 입력합니다.

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"