Vault Radar resources (API)

Overview

The HCP Vault Radar resource API provides endpoints for querying resources monitored by Vault Radar. Resources represent scannable assets that can be scanned for security findings, such as repositories and cloud storage.

Versioning

The Vault Radar API version is 2023-05-01.

Prerequisites

• Retrieve an access token for authentication.

Search

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

Search for resources based on flexible criteria including filtering, sorting, and pagination.

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

Request

Path parameters

project_id (string, required): The unique identifier of the HCP project where you enabled Vault Radar. You can find the project ID in the URL of your browser or in the project settings in the HCP Portal.

Example body

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

Response

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,
      ...
    }
  ]
}

Search (group and aggregate)

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

The search endpoint for resources also allows you to group and aggregate results.

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

Path parameters

project_id (string, required): The unique identifier of the HCP project where you enabled Vault Radar. You can find the project ID in the URL of your browser or in the project settings in the HCP Portal.

Example body

Group and count monitored resources by scan_state.

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

Response

200 - OK

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

Search schema

The search resources endpoint uses SearchSchemaV2 to define search criteria. This schema supports:

• Pagination: Control result sets with limit and page
• Filtering: Apply conditions using Resource field names
• Sorting: Order results by Resource field names
• Grouping: Aggregate resources by specific Resource field names

Search parameters

• limit (int32): Maximum number of results to return (max: 1000). Optional, defaults to 1000.
• page (int32): Page number for pagination (first page is 1). Optional, defaults to 1.
• filters (array of FilterV2): Filtering criteria. Optional.
• orderBy (string): Comma-delimited Resource field name to sort by (e.g., "data_source_type", "uri", or multiple order by "data_source_type, uri"). Optional.
• orderDirection (string): Comma-delimited sort direction - "ASC" (ascending) or "DESC" (descending) e.g., "ASC", "DESC", or multiple directions "ASC, DESC". Optional.
• groupBy (string): Comma-delimited Resource field names to aggregate and group results e.g., "data_source_type", "data_source_name", or multiple group by "data_source_type, data_source_name". Optional.

Filter structure

Each FilterV2 has three components:

• id (string): The Resource field name to filter on (see Resource Fields Reference below)
• value (array): Array of values to match against
• op (Operation enum): The comparison operation to use

When multiple filters are provided, they are combined using logical AND.

Available filter operations

• EQ: Equal - matches if the field equals any value in the array
• NEQ: Not Equal - matches if the field does not equal any value
• NEQ_NULL_AWARE: Not Equal to or null
• GT: Greater Than
• GE: Greater Than or Equal
• LT: Less Than
• LE: Less Than or Equal
• LIKE: Pattern matching (use % as wildcard)
• ILIKE: Case-insensitive pattern matching

Resource fields reference

The resource message contains the following fields that can be used for filtering, sorting, and grouping:

Fields

Best practices

Performance tips

• Use pagination with limit and page for large result sets
  • Maximum limit is 1000
  • Use page: 1 for first page, page: 2 for second, etc.
• Apply specific filters to reduce result size
• Use groupBy for aggregated views instead of fetching all resources
• Combine filters with EQ operation for better performance than LIKE

Examples

Search for monitored resources.

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

Search with groupBy for monitored resource counts by data source type.

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

Search for resources with critical severity findings.

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

Additional resources

• HashiCorp Cloud Platform authentication documentation
• Vault Radar Swagger file