리소스 API

HCP Vault Radar 리소스 API는 Vault Radar가 모니터링하는 리소스를 쿼리하는 엔드포인트를 제공해요. 리소스는 저장소, 클라우드 스토리지처럼 보안 발견 결과를 스캔할 수 있는 스캔 가능한 자산을 나타내요.

출처: 문서

본문

버전 관리

Vault Radar API 버전은 2023-05-01이에요.

사전 요구 사항

인증을 위해 액세스 토큰을 검색하세요.

검색

POST /2023-05-01/vault-radar/projects/{project_id}/resources/search

필터링, 정렬, 페이지네이션을 포함한 유연한 기준으로 리소스를 검색해요.

https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/{project_id}/resources/search

요청

경로 파라미터

project_id (string, 필수): Vault Radar를 활성화한 HCP 프로젝트의 고유 식별자예요. 프로젝트 ID는 브라우저 URL이나 HCP 포털의 프로젝트 설정에서 찾을 수 있어요.

예시 본문

{
  "search": {
    "page": 1,
    "limit": 100,
    "filters": [
      {
        "id": "is_monitored",
        "value": [
          true
        ],
        "op": "EQ"
      },
      {
        "id": "state",
        "value": [
          "deleted"
        ],
        "op": "NEQ_NULL_AWARE"
      }
    ],
    "orderBy": "critical_count, high_count, medium_count, low_count",
    "orderDirection": "DESC, DESC, DESC, DESC"
  }
}

응답

200 - OK

{
  "resources": [
    {
      "id": "7c7818b9-dce1-4abb-8f6e-2cd917c3531f",
      "name": "my-repository",
      "uri": "https://github.com/my-org/my-repository",
      "data_source_name": "my-org",
      "data_source_type": "github_cloud",
      "state": "created",
      "is_monitored": true,
      "visibility": "cloud_private",
      "critical_count": 2,
      "high_count": 5,
      "medium_count": 10,
      "low_count": 3,
      ...
    }
  ]
}

검색 (그룹 및 집계)

POST /2023-05-01/vault-radar/projects/{project_id}/resources/search

리소스 검색 엔드포인트는 결과를 그룹화하고 집계하는 것도 허용해요.

Search with aggregated results

https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/{project_id}/resources/search

경로 파라미터

예시 본문

모니터링되는 리소스를 scan_state별로 그룹화하고 개수를 세어요.

{
  "search": {
    "filters": [
      {
        "id": "is_monitored",
        "value": [
          true
        ],
        "op": "EQ"
      }
    ],
    "groupBy": "scan_state"
  }
}

응답

200 - OK

{
  "resources": [
    {
      "count": 5,
      "scan_state": "done"
    },
    {
      "count": 2,
      "scan_state": "pending"
    }
  ]
}

검색 스키마

리소스 검색 엔드포인트는 SearchSchemaV2를 사용해 검색 기준을 정의해요. 이 스키마는 다음을 지원해요.

페이지네이션: limit과 page로 결과 집합 제어
필터링: Resource 필드 이름으로 조건 적용
정렬: Resource 필드 이름으로 결과 정렬
그룹화: 특정 Resource 필드 이름으로 리소스 집계

검색 파라미터

limit (int32): 반환할 최대 결과 수 (최대: 1000). 선택 사항이며 기본값은 1000이에요.
page (int32): 페이지네이션용 페이지 번호 (첫 페이지는 1). 선택 사항이며 기본값은 1이에요.
filters (FilterV2 배열): 필터링 기준. 선택 사항이에요.
orderBy (string): 정렬 기준이 되는 쉼표로 구분된 Resource 필드 이름 (예: "data_source_type", "uri", 또는 여러 정렬 기준 "data_source_type, uri"). 선택 사항이에요.
orderDirection (string): 쉼표로 구분된 정렬 방향 - "ASC"(오름차순) 또는 "DESC"(내림차순) (예: "ASC", "DESC", 또는 여러 방향 "ASC, DESC"). 선택 사항이에요.
groupBy (string): 집계하고 그룹화할 쉼표로 구분된 Resource 필드 이름 (예: "data_source_type", "data_source_name", 또는 여러 그룹 기준 "data_source_type, data_source_name"). 선택 사항이에요.

필터 구조

각 FilterV2는 세 가지 구성 요소를 가져요.

id (string): 필터링할 Resource 필드 이름 (아래 Resource Fields Reference 참고)
value (배열): 일치시킬 값의 배열
op (Operation enum): 사용할 비교 연산

여러 필터가 제공되면 논리 AND로 결합돼요.

사용 가능한 필터 연산

EQ: Equal - 필드가 배열의 어떤 값과 같으면 일치
NEQ: Not Equal - 필드가 어떤 값과 같지 않으면 일치
NEQ_NULL_AWARE: 값과 같지 않거나 null
GT: Greater Than
GE: Greater Than or Equal
LT: Less Than
LE: Less Than or Equal
LIKE: 패턴 일치 (%를 와일드카드로 사용)
ILIKE: 대소문자 구분 없는 패턴 일치

리소스 필드 레퍼런스

리소스 메시지에는 필터링, 정렬, 그룹화에 사용할 수 있는 다음 필드가 포함돼요.

필드

필드 이름	유형	설명
`id`	string	이 리소스의 고유 식별자.
`name`	string	리소스의 이름 (예: 저장소 이름).
`uri`	string	리소스의 URL 또는 경로.
`connection_url`	string	자체 관리 인스턴스에 있는 경우 데이터 소스 공급자의 URL.
`data_source_name`	string	데이터 소스의 이름/식별자 (예: 조직 이름, 계정 이름).
`data_source_type`	string	스캔된 데이터 소스의 유형.
`description`	string	리소스의 설명.
`detector_type`	string	스캔에 사용된 탐지기 유형: `hcp`, `agent`, `cli`
`visibility`	string	리소스의 접근 수준: `self_managed_public`, `self_managed_private`, `cloud_public`, `cloud_private`, `unknown`.
`state`	string	리소스의 현재 상태: `created`, `deleted`
`last_state_updated`	timestamp	이 리소스의 가장 최근 상태 업데이트 시각.
`hcp_resource_name`	string	HCP 리소스 이름 식별자.
`hcp_resource_status`	string	HCP 리소스의 상태.
`is_monitored`	bool	리소스가 변경 사항에 대해 적극적으로 모니터링되는지 여부.
`content_last_modified_time`	timestamp	리소스 콘텐츠가 마지막으로 수정된 시각.
`critical_count`	uint32	이 리소스에서 발견된 치명적 심각도 이벤트 수.
`high_count`	uint32	이 리소스에서 발견된 높은 심각도 이벤트 수.
`medium_count`	uint32	이 리소스에서 발견된 중간 심각도 이벤트 수.
`low_count`	uint32	이 리소스에서 발견된 낮은 심각도 이벤트 수.
`scan_state`	string	리소스의 현재 스캔 상태: `pending`, `in_progress`, `done`, `skipped`, `cancelling`, `cancelled`, `failed`, `expired`

모범 사례

성능 팁

대용량 결과 집합에는 limit과 page로 페이지네이션을 사용하세요.최대 한도는 1000이에요.첫 페이지는 page: 1, 두 번째는 page: 2 등으로 사용하세요.
결과 크기를 줄이려면 특정 필터를 적용하세요.
모든 리소스를 가져오는 대신 집계 뷰에는 groupBy를 사용하세요.
LIKE보다 성능이 좋은 EQ 연산으로 필터를 결합하세요.

예시

모니터링되는 리소스 검색.

$ curl -X POST \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/resources/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "is_monitored", "op": "EQ", "value": [true]}
      ],
      "orderBy": "name",
      "orderDirection": "ASC",
      "limit": 10,
      "page": 1
    }
  }'

데이터 소스 유형별 모니터링 리소스 수에 대한 groupBy 검색.

$ curl -X POST \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/resources/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "is_monitored", "value": [true], "op": "EQ"}
      ],
      "groupBy": "data_source_type"
    }
  }'

치명적 심각도 발견 결과가 있는 리소스 검색.

$ curl -X POST \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/resources/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "critical_count", "op": "GT", "value": [0]}
      ],
      "orderBy": "critical_count",
      "orderDirection": "DESC",
      "limit": 10,
      "page": 1
    }
  }'

추가 리소스

HashiCorp Cloud Platform 인증 문서

더 알아보기 (Learn more)

이벤트 API — 이벤트를 쿼리하는 API를 알아봐요.
API 인증 — API 액세스 토큰 생성 방법을 알아봐요.
HCP Vault Radar 개요 — Vault Radar의 전반적인 개념을 살펴봐요.