# Hashicorp vault

SureCloud connects to HashiCorp Vault to retrieve audit device configuration, secrets engine inventory, lease and renewal status, and access policy definitions. This allows SureCloud to verify that secrets rotation is active, that audit logging is enabled, and that access to Vault secrets is controlled through defined policies — providing evidence for secrets management and cryptographic key management controls.

## Authentication and setup

HashiCorp Vault supports multiple authentication methods. SureCloud uses a dedicated AppRole with a read-only policy to authenticate without user interaction.

{% stepper %}
{% step %}
**Create a read-only policy in Vault**

On your Vault server, create a policy named `surecloud-read`:

```hcl
path "sys/audit" {
  capabilities = ["read", "list"]
}
path "sys/mounts" {
  capabilities = ["read", "list"]
}
path "sys/policies/acl/*" {
  capabilities = ["read", "list"]
}
path "sys/leases/*" {
  capabilities = ["read", "list"]
}
path "auth/*" {
  capabilities = ["read", "list"]
}
```

Apply it with:

```bash
vault policy write surecloud-read surecloud-read.hcl
```

{% endstep %}

{% step %}
**Enable AppRole and create a role**

```bash
vault auth enable approle
vault write auth/approle/role/surecloud-ccm \
  token_policies="surecloud-read" \
  token_ttl=1h \
  token_max_ttl=4h \
  secret_id_ttl=0
```

{% endstep %}

{% step %}
**Retrieve the Role ID and Secret ID**

```bash
vault read auth/approle/role/surecloud-ccm/role-id
vault write -f auth/approle/role/surecloud-ccm/secret-id
```

Copy both values.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → HashiCorp Vault → Connect**. Enter your Vault address (e.g. `https://vault.yourcompany.com`), the AppRole **Role ID**, and the **Secret ID**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
The AppRole Secret ID provides access to Vault. Store it securely. SureCloud encrypts it at rest. Rotate the Secret ID periodically by generating a new one via `vault write -f auth/approle/role/surecloud-ccm/secret-id` and updating it in **SureCloud → Integrations → HashiCorp Vault → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                            | Use Case                                                              |
| ----------------------------------- | --------------------------------------------------------------------- |
| `POST /v1/auth/approle/login`       | Authenticate with Role ID and Secret ID to obtain a Vault token       |
| `GET /v1/sys/audit`                 | Retrieve configured audit devices to confirm audit logging is enabled |
| `GET /v1/sys/mounts`                | List secrets engines and their configuration                          |
| `GET /v1/sys/policies/acl`          | List ACL policies to confirm access control is defined                |
| `GET /v1/sys/policies/acl/{policy}` | Retrieve individual policy content for access control evidence        |
| `GET /v1/auth`                      | List enabled authentication methods                                   |
| `GET /v1/sys/leases/lookup`         | Retrieve lease status for dynamic secrets rotation evidence           |

## Pagination

HashiCorp Vault list operations return all results in a single response for most configurations. `LIST /v1/sys/policies/acl` returns all policy names in one response. For very large Vault deployments with many policies or leases, SureCloud pages through results using Vault's `LIST` operation pattern.

## Required permissions

SureCloud requires an AppRole with the `surecloud-read` policy defined above, granting:

* `read` and `list` on `sys/audit` (audit device configuration)
* `read` and `list` on `sys/mounts` (secrets engine inventory)
* `read` and `list` on `sys/policies/acl/*` (access policy definitions)
* `read` and `list` on `auth/*` (authentication method configuration)

No secret read, write, or delete capabilities are required.

## Polling frequency

| Data Type                           | Interval       |
| ----------------------------------- | -------------- |
| Audit device configuration          | Every 24 hours |
| Secrets engine inventory            | Every 24 hours |
| ACL policy definitions              | Every 24 hours |
| Authentication method configuration | Every 24 hours |

## Troubleshooting

<details>

<summary>Authentication returns "invalid role ID" or "invalid secret ID"</summary>

The Role ID or Secret ID is incorrect, or the Secret ID has expired. Confirm the AppRole exists with `vault read auth/approle/role/surecloud-ccm`. Generate a new Secret ID and update it in **SureCloud → Integrations → HashiCorp Vault → Edit Connection**.

</details>

<details>

<summary>Audit devices endpoint returns empty</summary>

No audit devices have been enabled in Vault, or the `surecloud-read` policy does not include `sys/audit` read access. Enabling at least one audit device is a recommended Vault security practice. Verify audit device configuration with `vault audit list` and review the policy applied to the AppRole.

</details>

<details>

<summary>Vault is unreachable from SureCloud</summary>

Confirm the Vault address is accessible from the SureCloud collector network over HTTPS. Self-hosted Vault clusters on private networks require a firewall rule. If Vault is deployed in Kubernetes, confirm the service is externally accessible. Contact SureCloud Support for collector IP range details.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/hashicorp-vault.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.