보안 점수 및 프로필 API

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

Apigee UI에서 보안 점수와 보안 프로필을 보는 것 외에도 보안 점수와 프로필 API를 사용하여 액세스할 수 있습니다. 이 페이지에서는 보안 점수와 Profiles API를 사용하는 몇 가지 예시를 보여줍니다.

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

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

JSON에서 지원되는 입력 필드:
- timeRange: 기간 길이는 최대 14일이며 기간의 startTime 및 endTime은 지난 90일 이내여야 합니다. 기간을 참조하세요.
- filters: API에서 지원되는 필터를 참조하세요.
- pageSize: 단일 페이지에서 반환될 최대 하위 구성요소 수: 100개
다중 입력 필터는 지원되지 않습니다.
응답의 영향 필드는 지원되지 않습니다. (영향 필드는 이 권장사항이 전체 점수에 미칠 수 있는 잠재적 영향입니다. 이 권장사항이 점수 개선에 얼마나 중요한지를 나타냅니다.)

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

데이터 지연

지능화된 API 보안의 보안 점수를 기준으로 하는 데이터에는 데이터 처리 방식으로 인해 다음과 같은 지연이 발생합니다.

조직에서 지능화된 API 보안을 사용 설정하면 기존 프록시와 대상의 점수가 환경에 반영되는 데 최대 6시간이 걸릴 수 있습니다.
환경의 프록시(배포 및 배포 취소)와 대상(만들기, 업데이트, 삭제)과 관련된 새 이벤트에는 환경 점수에 반영되는 데 최대 6시간이 걸릴 수 있습니다.
Apigee Analytics 파이프라인으로 들어가는 데이터는 평균적으로 최대 15~20분 정도까지 지연됩니다. 따라서 소스 점수 악용 데이터는 약 15~20분 정도까지 처리가 지연됩니다.

API 호출 예시의 매개변수

다음 섹션에서는 보안 점수 및 프로필 API를 사용하는 API 호출 예시를 보여줍니다. API 호출에는 다음 매개변수가 포함됩니다.

ORG는 사용자의 조직입니다.
ENV는 점수를 계산할 환경입니다.
ENVGROUP은 환경을 포함하는 환경 그룹입니다.
PROFILE_ID는 프로필 이름입니다. PROFILE_ID는 default 또는 생성한 커스텀 프로필의 이름일 수 있습니다.
PROFILE_ID는 1~63자(영문 기준)의 소문자, 숫자(0~9) 또는 하이픈으로 구성되어야 합니다. 첫 번째 문자는 소문자여야 합니다. 마지막 문자는 소문자 또는 숫자여야 합니다.
$TOKEN은 OAuth 액세스 토큰의 환경 변수입니다.
timeRange는 점수의 기간입니다.

기간

보안 점수가 계산되는 데이터 기간입니다. 다음 형식으로 점수의 시작 및 종료 시간을 지정하여 시간 범위를 설정할 수 있습니다.

"timeRange":
  {
    "startTime": "YYYY-MM-DDT00:00:00Z",
    "endTime": "YYYY-MM-DDT00:00:00Z"
  }

startTime와 endTime 모두 이전 90일 이내여야 합니다.

기본 보안 프로필 사용

다음 예시에서는 기본 보안 프로필을 사용하는 방법을 보여줍니다. 예시에 사용된 매개변수는 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"

API에서 지원되는 필터

다음 표에서는 API에서 지원되는 필터 및 해당 구성요소 경로를 보여줍니다. 구성요소 경로에서 변수를 다음과 같이 바꿉니다.

ORG: 내 조직
ENV: 점수를 보고 있는 환경
PROXY_NAME: 프록시의 이름

필터	구성요소 경로
환경 점수	`/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`