이벤트 API

이벤트 API

HCP Vault Radar 이벤트 API는 Vault Radar가 감지한 보안 이벤트를 쿼리하고 관리하는 엔드포인트를 제공해요. 이벤트는 다양한 데이터 소스에서 발견된 유출된 시크릿, 노출된 자격 증명, 기타 취약점 같은 보안 발견 결과를 나타내요.

출처: 문서

본문

버전 관리

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

사전 요구 사항

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

검색

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

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

Search

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

요청

경로 파라미터

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

예시 본문

{
  "search": {
    "filters": [
      {
        "id": "status",
        "op": "EQ",
        "value": [
          "NEW",
          "NOTIFIED",
          "TO_REMEDIATE",
          "SECRET_STORED",
          "SECRET_REPLACED",
          "SECRET_REVOKED"
        ]
      },
      {
        "id": "severity",
        "op": "EQ",
        "value": [
          "critical",
          "high"
        ]
      },
      {
        "id": "in_latest_version",
        "value": [
          true
        ],
        "op": "EQ"
      }
    ],
    "orderBy": "created",
    "orderDirection": "DESC",
    "limit": 100,
    "page": 1
  }
}

응답

200 - OK

{
  "events": [
    {
      "event_id": "7c7818b9-dce1-4abb-8f6e-2cd917c3531f",
      "type": "REPO_SCAN_MATCH",
      "sub_type": "secret_assignment",
      "severity": "critical",
      "status": "NEW",
      "created": "2025-12-20T22:15:06.667915Z",
      "in_latest_version": true,
      ...
    }
  ]
}

검색 (그룹 및 집계)

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

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

Search with aggregated results

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

경로 파라미터

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

예시 본문

이벤트를 심각도와 상태별로 그룹화하고 개수를 세어요.

{
  "search": {
    "filters": [
      {
        "id": "in_latest_version",
        "value": [
          true
        ],
        "op": "EQ"
      }
    ],
    "groupBy": "severity,status"
  }
}

응답

200 - OK

{
  "events": [
    {
      "count": 5,
      "severity": "medium",
      "status": "NEW"
    },
    {
      "count": 4,
      "severity": "low",
      "status": "NEW"
    },
    {
      "count": 1,
      "severity": "info",
      "status": "IGNORE_RULE"
    }
  ]
}

이벤트 업데이트

PUT /2023-05-01/vault-radar/projects/{project_id}/events

분류(triaging) 및 수정 워크플로를 위해 여러 이벤트의 상태를 일괄 업데이트해요.

Update events

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

경로 파라미터

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

예시 본문

{
  "events": [
    {
      "event_id": "0b366a31-7494-4264-bf26-12931d323b5c",
      "status": "NOT_IMPORTANT"
    },
    {
      "event_id": "544c8754-2f63-4907-8b1d-58eff1b7353a",
      "status": "TO_REMEDIATE"
    },
    {
      "event_id": "8b5edc4b-95ff-4a96-8064-ed56cb54908b",
      "status": "RESOLVED"
    }
  ]
}

응답

200 - OK

{
  "count": 3
}

검색 스키마

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

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

검색 파라미터

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

필터 구조

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

• id (string): 필터링할 Event 필드 이름 (아래 Event 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: 대소문자 구분 없는 패턴 일치

이벤트 필드 레퍼런스

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

필드

필드 이름	유형	설명
event_id	string	이 이벤트의 고유 식별자. 업데이트 작업에서 이벤트를 참조하는 데 사용.
type	string	보안 이벤트의 카테고리: REPO_SCAN_MATCH, PII_IN_REPO, NON_INCLUSIVE_LANGUAGE.
sub_type	string	카테고리 내의 특정 유형. 가능한 값은 이 목록 참고.
description	string	보안 발견 결과에 대한 상세 설명.
summary	string	빠른 분류를 위한 이벤트의 간결한 요약.
severity	string	이벤트의 위험 수준: critical, high, medium, low, info.
risk_category	string	위험 카테고리의 분류.
status	string	이벤트 수정의 현재 상태: NEW, FALSE_POSITIVE, NOT_IMPORTANT, IGNORE_RULE, NOTIFIED, TO_REMEDIATE, SECRET_STORED, SECRET_REPLACED, SECRET_REVOKED, RESOLVED, DELETED
created	timestamp	Vault Radar가 이벤트를 처음 감지한 시각.
last_updated	timestamp	이 이벤트에 대한 가장 최근 업데이트 시각.
author_time	timestamp	콘텐츠가 작성된 시각 (예: Git 커밋 타임스탬프).
data_source_type	string	스캔된 데이터 소스의 유형.
data_source_name	string	데이터 소스의 이름/식별자 (예: 조직 이름, 계정 이름).
connection_url	string	자체 관리 인스턴스에 있는 경우 데이터 소스 공급자의 URL.
resource_name	string	리소스의 이름.
resource_uri	string	이벤트가 발견된 리소스의 URL.
visibility	string	리소스의 접근 수준: self_managed_public, self_managed_private, cloud_public, cloud_private, unknown.
content_id	string	이벤트가 발견된 콘텐츠의 고유 식별자 (예: 커밋 해시).
content_reference	string	브랜치, 태그 또는 버전 참조 (예: refs/heads/main).
context	string	발견이 발생한 위치에 대한 추가 컨텍스트 정보 (예: 시크릿의 왼쪽과 오른쪽 문자).
context_url	string	위험을 볼 수 있는 직접 링크 (예: 줄 번호가 있는 GitHub 파일 링크).
in_latest_version	bool	이 이벤트가 현재/기본 버전에 존재하는지 여부. Git 저장소의 경우: 기본 브랜치의 최신 커밋에서 발견되면 true.
secret_id	string	감지된 시크릿의 고유 해시 식별자. 여러 위치에서 같은 시크릿을 추적하는 데 사용.
secret_activeness	string	유출된 시크릿이 여전히 외부 공급자에 접근할 수 있는지 여부: active, inactive, unknown.
author	string	발견 결과가 포함된 콘텐츠를 만들거나 커밋한 사람 (예: Git 커밋의 개발자 이름 또는 이메일).
updated_by	string	이 이벤트를 마지막으로 수정한 사용자 또는 시스템.
reviewed_by	string	분류 중 이 이벤트를 검토한 사용자.
is_monitored	bool	이벤트가 발견된 리소스가 변경 사항에 대해 적극적으로 모니터링되는지 여부.
details	json	이벤트에 대한 추가 기타 정보. 구조는 이벤트 유형과 데이터 소스에 따라 달라짐.
managed_locations	json	위험이 저장된 시크릿 매니저 위치에 대한 정보.

모범 사례

성능 팁

• 대용량 결과 집합에는 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/events/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "status", "op": "EQ", "value": ["NEW", "NOTIFIED", "TO_REMEDIATE", "SECRET_STORED", "SECRET_REPLACED", "SECRET_REVOKED"]},
        {"id": "severity", "op": "EQ", "value": ["critical", "high"]}
      ],
      "orderBy": "created",
      "orderDirection": "DESC",
      "limit": 10,
      "page": 1
    }
  }'

심각도와 상태별 이벤트 수에 대한 groupBy 검색.

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

이벤트 상태 업데이트.

$ curl -X PUT \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/events \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"event_id": "7c7818b9-dce1-4abb-8f6e-2cd917c3531f", "status": "RESOLVED"}
    ]
  }'

추가 리소스

• HashiCorp Cloud Platform 인증 문서

더 알아보기 (Learn more)

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