보안 점수 및 프로필 API

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

개요

이 페이지에서는 API를 사용하여 위험 평가 보안 점수 및 보안 프로필을 관리하는 방법을 설명합니다. API 요청 예시도 제공합니다.

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

위험 평가 v2 API 예시

일괄 보안 평가 결과 검색

Security Admin 또는 Security Viewer 역할이 있는 사용자는 임시 위험 평가 계산을 실행할 권한이 있습니다. 평가할 보안 프로필, 범위, 리소스를 지정해야 합니다. 범위 내의 모든 리소스를 계산하려는 경우 리소스는 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": {}
  }'

각 항목의 의미는 다음과 같습니다.

ORG는 사용자의 조직입니다.
ENV는 점수를 보고 있는 환경입니다.

위 요청에 대한 잠재적인 응답입니다.

  {
    "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": {}
      }
    ]
  }

위험 평가 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"
  }

API 호출에 JSON 파일을 연결하여 프로필 정의

프로필을 정의하는 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"