Skip to main content
Type '/' to Search

The Learn website is being redesigned to help you find what you are looking for more effectively.

Enterprise

Sentinel HTTP Import

This tutorial also appears in: Enterprise.

Enterprise Only: Sentinel requires Vault Enterprise Plus license. To explore Vault Enterprise features, you can sign up for a free 30-day trial from here.

Sentinel is a language framework for policy built to be embedded in Vault Enterprise to enable fine-grained, logic-based policy decisions which cannot be fully handled by the ACL policies.

If you are not yet familiar with using Sentinel policies in Vault, review Sentinel Policies.

»Challenge

Sentinel Endpoint Governing Policies (EGP) are flexible and provide rich capabilities and rules to enable uses like Multi Factor Authentication requirements or even per path policy delegation, but what if your use case requires policy rules that are informed by consulting the output of an HTTP API?

»Solution

The Sentinel http import enables the use of HTTP-accessible data from outside the runtime in Sentinel policy rules. At a basic level, the import uses an HTTP GET request and by default, any request response that is not a successful "200 OK" HTTP response causes a policy error. This behavior can be further customized to your particular use case.

In this tutorial, you will learn how to configure Vault server to allow additional enabled modules, start a dev mode Vault server with the Sentinel HTTP import enabled. Then, you will write a Sentinel EGP that uses the HTTP import to query the Vault server API to determine information about enabled secrets engines, permitting or denying certain operations based on the specific criteria described later in the example. Finally, you'll write working tests for the EGP and test the EGP.

»Prerequisites

To perform the tasks exactly as described here, you need to have a macOS or Linux computer with a Vault Enterprise binary at version 1.5.0 or higher.

NOTE: To explore Vault Enterprise features, you can sign up for a free 30-day trial.

You should have familiarity with Vault and Sentinel, and be comfortable authoring and deploying a Sentinel EGP for Vault to follow along with the example presented here.

»Token policy requirements

This tutorial requires two Vault tokens- one for the Vault admin who will be creating and testing the Sentinel EGP, and one to use within the EGP itself.

You will use the initial root token to create these tokens.

»Vault user token policies

You need to authenticate to Vault with a token that has sufficient capabilities to follow the example workflow.

CAUTION: Do not use the initial root token for any purpose other than creating the required tokens, as root tokens are not subject to Sentinel policy enforcement and will cause issues with policy development and testing.

The specific required policy capabilities for the token used by the admin user are as follows.

# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# To manage ACLs
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# To manage ACLs
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

»Sentinel EGP token policy

The Sentinel EGP example in this tutorial makes a call to the /sys/mounts API to determine which secrets engines are enabled.

This is an authenticated API endpoint, so the EGP itself needs its own Vault token with the minimum required ACL policy capability to read from /sys/mounts.

That policy is as follows.

path "/sys/mounts" {
  capabilities = ["read"]
}

path "/sys/mounts" {
  capabilities = ["read"]
}

This token will be referred to as the EGP token going forward in the tutorial.

»Step 1: Configure Vault

Before you can use the Sentinel HTTP import module, you need to configure Vault and define additional enabled modules. This is done with the additional_enabled_modules parameter.

For this tutorial, you will use a Vault server in dev mode and pass just the Sentinel specific configuration to it at runtime from the configuration file, vault-sentinel-configuration.hcl.

Write the file out to the present working directory with this command.

$ cat > vault-sentinel-configuration.hcl << EOF
sentinel {
  additional_enabled_modules = ["http"]
}
EOF

$ cat > vault-sentinel-configuration.hcl << EOF
sentinel {
  additional_enabled_modules = ["http"]
}
EOF

»Step 2: Start a dev mode server

In the same terminal session where you created the configuration file, start the Vault dev mode server and pass the configuration file to the -config flag like this.

$ vault server -dev \
    -dev-root-token-id root \
    -config vault-sentinel-configuration.hcl

$ vault server -dev \
    -dev-root-token-id root \
    -config vault-sentinel-configuration.hcl

Insecure operation: Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.

»Step 3: Write ACL policies, create tokens and login

Let's write the two ACL policies and generate the tokens you will need, and then login to Vault with the admin token at this time.

Open a new terminal session or window in which to follow these steps, and export VAULT_ADDR to properly address the dev mode server from this session.

$ export VAULT_ADDR=http://127.0.0.1:8200

$ export VAULT_ADDR=http://127.0.0.1:8200

Create the admin user policy.

$ vault policy write admin - << EOF
# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# To manage ACLs
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

$ vault policy write admin - << EOF
# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# To manage ACLs
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

Successful output example:

Success! Uploaded policy: admin

Success! Uploaded policy: admin

Create the EGP token policy.

$ vault policy write sentinel-egp-token - << EOF
path "/sys/mounts" {
  capabilities = ["read"]
}
EOF

$ vault policy write sentinel-egp-token - << EOF
path "/sys/mounts" {
  capabilities = ["read"]
}
EOF

Successful output example:

Success! Uploaded policy: sentinel-egp-token

Success! Uploaded policy: sentinel-egp-token

Next, create the tokens; typically tokens are issued from an enabled auth method, but to keep this tutorial brief, you can create them directly from the token store.

First, capture the admin user token value to the VAULT_ADMIN_TOKEN environment variable.

$ export VAULT_ADMIN_TOKEN="$(vault token create -policy=admin -field=token)"

$ export VAULT_ADMIN_TOKEN="$(vault token create -policy=admin -field=token)"

You can run echo $VAULT_ADMIN_TOKEN to see the environment variable value.

Then, capture the EGP token value to the VAULT_EGP_TOKEN environment variable.

$ export VAULT_EGP_TOKEN="$(vault token create -policy=sentinel-egp-token -field=token)"

$ export VAULT_EGP_TOKEN="$(vault token create -policy=sentinel-egp-token -field=token)"

You can run echo $VAULT_EGP_TOKEN to examine the environment variable value.

From here on out in this tutorial, you will use the admin token instead of the root token.

You can login with the admin token like this.

$ vault login -no-print $VAULT_ADMIN_TOKEN

$ vault login -no-print $VAULT_ADMIN_TOKEN

You are now ready to move on to writing, testing, and deploying the Sentinel EGP.

»Step 4: Write Sentinel EGP

After you configure Vault to allow additional Sentinel modules, create ACL policies and tokens, and login with the admin token, it is time to write the Sentinel EGP.

For this example, let's presume a simple scenario where the specific use case for Vault seeks to limit the number of Transit secrets engines that can be enabled at any one time to a single (1) instance.

Vault can limit the number of enabled secrets engines by leveraging Sentinel with the HTTP import to query its own API to determine the number of currently enabled secrets engines of a given type.

The Sentinel policy can then further choose to allow or deny enabling of new secrets engines based on the current count of enabled transit secrets engines.

»Example policy

Here is the example policy for review; details about the code follow.

# Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "$VAULT_EGP_TOKEN"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}

# Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "$VAULT_EGP_TOKEN"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}

Let's walk through the code to understand how this EGP works.

  • The first two non-comment lines declare the http and json imports needed for making HTTP requests and processing JSON.
  • Next, two param lines define parameter values for the Vault address and Vault token for the EGP itself. You should replace http://127.0.0.1:8200 with the address of your Vault server in the same URL format with port (ex. http://localhost:8200) and replace \$VAULT_EGP_TOKEN with the actual token value for your EGP token that you created in step 3.
  • Then there are some print statements, useful for debugging as the information is only printed when the policy is violated and fails.
  • The bulk of the EGP logic resides in a single function, validate_transit_not_present(). It makes the HTTP request to the Vault /sys/mounts API endpoint to query the state of enabled secrets engines by examining the type of each enabled engine. If one is discovered to have the type "transit", then the validated variable value will be returned as false, causing the main rule evaluation to fail, and permission to enable any additional transit secrets engines for a non-root token user will be denied.
  • Finally, the main rule sets some conditions for its evaluation based on request parameters; the request must be for the /sys/mounts path, it must be an update operation, and the data type for the operation needs to be transit. If the request matches these conditions, then validate_transit_not_present is called to determine if there is already an enabled transit secrets engine.

You can write transit-check.sentinel for use with CLI commands to the present working directory with this command.

$ cat > transit-check.sentinel << EOF
# Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "$VAULT_EGP_TOKEN"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}
EOF

$ cat > transit-check.sentinel << EOF
# Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "$VAULT_EGP_TOKEN"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}
EOF

WARNING: If you will deploy the Sentinel EGP with the HTTP API or Web UI, you need to replace the $VAULT_EGP_TOKEN value with that of your actual EGP token value prior to deploying the policy.

»Step 3: Test Sentinel EGP

You can test the Sentinel policy prior to deployment in order to validate syntax and to document expected behavior.

First, you need to download the Sentinel simulator.

$ wget https://releases.hashicorp.com/sentinel/0.15.6/sentinel_0.15.6_darwin_amd64.zip

$ wget https://releases.hashicorp.com/sentinel/0.15.6/sentinel_0.15.6_darwin_amd64.zip

Unzip the downloaded file.

$ unzip sentinel_0.15.6_darwin_amd64.zip -d /usr/local/bin

$ unzip sentinel_0.15.6_darwin_amd64.zip -d /usr/local/bin

Create a sub-folder named test where the transit-check.sentinel file is located.

Under the test folder, create a sub-folder for transit-check.

$ mkdir -p test/transit-check

$ mkdir -p test/transit-check

NOTE: The tests should be created under test/<policy_name> folder.

Write a passing test case for the transit-check policy, test/transit-check/success.json.

$ cat > test/transit-check/success.json << EOF
{
  "global": {
    "request": {
      "operation": "update",
      "path": "sys/mounts/transit",
      "data": {
        "type": "transit"
      }
    },
    "body": {
      "sys/": {
        "accessor": "system_ab0f1127",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0,
          "passthrough_request_headers": [
            "Accept"
          ]
        },
        "description": "system endpoints used for control, policy and debugging",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "system",
        "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
      },
      "identity/": {
        "accessor": "identity_9228cd88",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "identity store",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "identity",
        "uuid": "c584e265-8417-4671-7fec-225393fcf307"
      },
      "cubbyhole/": {
        "accessor": "cubbyhole_da4d2e11",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "per-token private secret storage",
        "external_entropy_access": false,
        "local": true,
        "options": null,
        "seal_wrap": false,
        "type": "cubbyhole",
        "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
      },
      "secret/": {
        "accessor": "kv_086ea056",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "key/value secret storage",
        "external_entropy_access": false,
        "local": false,
        "options": {
          "version": "2"
        },
        "seal_wrap": false,
        "type": "kv",
        "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
      },
      "request_id": "aac465cc-3101-cfa8-67d0-cc2bce8c38b1",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "cubbyhole/": {
          "accessor": "cubbyhole_da4d2e11",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "per-token private secret storage",
          "external_entropy_access": false,
          "local": true,
          "options": null,
          "seal_wrap": false,
          "type": "cubbyhole",
          "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
        },
        "identity/": {
          "accessor": "identity_9228cd88",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "identity store",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "identity",
          "uuid": "c584e265-8417-4671-7fec-225393fcf307"
        },
        "secret/": {
          "accessor": "kv_086ea056",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "key/value secret storage",
          "external_entropy_access": false,
          "local": false,
          "options": {
            "version": "2"
          },
          "seal_wrap": false,
          "type": "kv",
          "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
        },
        "sys/": {
          "accessor": "system_ab0f1127",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0,
            "passthrough_request_headers": [
              "Accept"
            ]
          },
          "description": "system endpoints used for control, policy and debugging",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "system",
          "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
        }
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    },
    "test": {
      "main": true,
      "validate_transit_not_present": true
    }
  }
}
EOF

$ cat > test/transit-check/success.json << EOF
{
  "global": {
    "request": {
      "operation": "update",
      "path": "sys/mounts/transit",
      "data": {
        "type": "transit"
      }
    },
    "body": {
      "sys/": {
        "accessor": "system_ab0f1127",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0,
          "passthrough_request_headers": [
            "Accept"
          ]
        },
        "description": "system endpoints used for control, policy and debugging",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "system",
        "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
      },
      "identity/": {
        "accessor": "identity_9228cd88",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "identity store",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "identity",
        "uuid": "c584e265-8417-4671-7fec-225393fcf307"
      },
      "cubbyhole/": {
        "accessor": "cubbyhole_da4d2e11",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "per-token private secret storage",
        "external_entropy_access": false,
        "local": true,
        "options": null,
        "seal_wrap": false,
        "type": "cubbyhole",
        "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
      },
      "secret/": {
        "accessor": "kv_086ea056",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "key/value secret storage",
        "external_entropy_access": false,
        "local": false,
        "options": {
          "version": "2"
        },
        "seal_wrap": false,
        "type": "kv",
        "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
      },
      "request_id": "aac465cc-3101-cfa8-67d0-cc2bce8c38b1",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "cubbyhole/": {
          "accessor": "cubbyhole_da4d2e11",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "per-token private secret storage",
          "external_entropy_access": false,
          "local": true,
          "options": null,
          "seal_wrap": false,
          "type": "cubbyhole",
          "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
        },
        "identity/": {
          "accessor": "identity_9228cd88",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "identity store",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "identity",
          "uuid": "c584e265-8417-4671-7fec-225393fcf307"
        },
        "secret/": {
          "accessor": "kv_086ea056",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "key/value secret storage",
          "external_entropy_access": false,
          "local": false,
          "options": {
            "version": "2"
          },
          "seal_wrap": false,
          "type": "kv",
          "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
        },
        "sys/": {
          "accessor": "system_ab0f1127",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0,
            "passthrough_request_headers": [
              "Accept"
            ]
          },
          "description": "system endpoints used for control, policy and debugging",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "system",
          "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
        }
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    },
    "test": {
      "main": true,
      "validate_transit_not_present": true
    }
  }
}
EOF

This test will pass because it does not include an enabled transit secrets engine.

The optional test definition adds more context to why the test should pass. The expected behavior is that the test passes because validate_transit_not_present returns true and main returns true.

Write a failing test for the transit-check policy, test/transit-check/fail.json.

$ cat > test/transit-check/fail.json << EOF
{
  "global": {
    "request": {
      "operation": "update",
      "path": "sys/mounts/transit",
      "data": {
        "type": "transit"
      }
    },
    "body": {
      "sys/": {
        "accessor": "system_ab0f1127",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0,
          "passthrough_request_headers": [
            "Accept"
          ]
        },
        "description": "system endpoints used for control, policy and debugging",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "system",
        "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
      },
      "identity/": {
        "accessor": "identity_9228cd88",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "identity store",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "identity",
        "uuid": "c584e265-8417-4671-7fec-225393fcf307"
      },
      "cubbyhole/": {
        "accessor": "cubbyhole_da4d2e11",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "per-token private secret storage",
        "external_entropy_access": false,
        "local": true,
        "options": null,
        "seal_wrap": false,
        "type": "cubbyhole",
        "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
      },
      "secret/": {
        "accessor": "kv_086ea056",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "key/value secret storage",
        "external_entropy_access": false,
        "local": false,
        "options": {
          "version": "2"
        },
        "seal_wrap": false,
        "type": "kv",
        "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
      },
      "transit/": {
        "accessor": "transit_1f715ad9",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "transit",
        "uuid": "dcb11046-caec-5b9b-e902-9f1281c520de"
      },
      "request_id": "d73a6a7a-a537-dd97-79a9-9e1b3654cc73",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "cubbyhole/": {
          "accessor": "cubbyhole_da4d2e11",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "per-token private secret storage",
          "external_entropy_access": false,
          "local": true,
          "options": null,
          "seal_wrap": false,
          "type": "cubbyhole",
          "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
        },
        "identity/": {
          "accessor": "identity_9228cd88",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "identity store",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "identity",
          "uuid": "c584e265-8417-4671-7fec-225393fcf307"
        },
        "secret/": {
          "accessor": "kv_086ea056",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "key/value secret storage",
          "external_entropy_access": false,
          "local": false,
          "options": {
            "version": "2"
          },
          "seal_wrap": false,
          "type": "kv",
          "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
        },
        "sys/": {
          "accessor": "system_ab0f1127",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0,
            "passthrough_request_headers": [
              "Accept"
            ]
          },
          "description": "system endpoints used for control, policy and debugging",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "system",
          "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
        },
        "transit/": {
          "accessor": "transit_1f715ad9",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "transit",
          "uuid": "dcb11046-caec-5b9b-e902-9f1281c520de"
        }
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    },
    "test": {
      "main": false,
      "validate_transit_not_present": false
    }
  }
}
EOF

$ cat > test/transit-check/fail.json << EOF
{
  "global": {
    "request": {
      "operation": "update",
      "path": "sys/mounts/transit",
      "data": {
        "type": "transit"
      }
    },
    "body": {
      "sys/": {
        "accessor": "system_ab0f1127",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0,
          "passthrough_request_headers": [
            "Accept"
          ]
        },
        "description": "system endpoints used for control, policy and debugging",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "system",
        "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
      },
      "identity/": {
        "accessor": "identity_9228cd88",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "identity store",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "identity",
        "uuid": "c584e265-8417-4671-7fec-225393fcf307"
      },
      "cubbyhole/": {
        "accessor": "cubbyhole_da4d2e11",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "per-token private secret storage",
        "external_entropy_access": false,
        "local": true,
        "options": null,
        "seal_wrap": false,
        "type": "cubbyhole",
        "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
      },
      "secret/": {
        "accessor": "kv_086ea056",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "key/value secret storage",
        "external_entropy_access": false,
        "local": false,
        "options": {
          "version": "2"
        },
        "seal_wrap": false,
        "type": "kv",
        "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
      },
      "transit/": {
        "accessor": "transit_1f715ad9",
        "config": {
          "default_lease_ttl": 0,
          "force_no_cache": false,
          "max_lease_ttl": 0
        },
        "description": "",
        "external_entropy_access": false,
        "local": false,
        "options": null,
        "seal_wrap": false,
        "type": "transit",
        "uuid": "dcb11046-caec-5b9b-e902-9f1281c520de"
      },
      "request_id": "d73a6a7a-a537-dd97-79a9-9e1b3654cc73",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "cubbyhole/": {
          "accessor": "cubbyhole_da4d2e11",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "per-token private secret storage",
          "external_entropy_access": false,
          "local": true,
          "options": null,
          "seal_wrap": false,
          "type": "cubbyhole",
          "uuid": "59b388df-c992-e9b9-43ec-7830d9eed35d"
        },
        "identity/": {
          "accessor": "identity_9228cd88",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "identity store",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "identity",
          "uuid": "c584e265-8417-4671-7fec-225393fcf307"
        },
        "secret/": {
          "accessor": "kv_086ea056",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "key/value secret storage",
          "external_entropy_access": false,
          "local": false,
          "options": {
            "version": "2"
          },
          "seal_wrap": false,
          "type": "kv",
          "uuid": "25bbe652-5f01-664d-a4ac-64a1bb45c478"
        },
        "sys/": {
          "accessor": "system_ab0f1127",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0,
            "passthrough_request_headers": [
              "Accept"
            ]
          },
          "description": "system endpoints used for control, policy and debugging",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "system",
          "uuid": "5e4101dd-ea91-5d26-9f09-85b675a72a95"
        },
        "transit/": {
          "accessor": "transit_1f715ad9",
          "config": {
            "default_lease_ttl": 0,
            "force_no_cache": false,
            "max_lease_ttl": 0
          },
          "description": "",
          "external_entropy_access": false,
          "local": false,
          "options": null,
          "seal_wrap": false,
          "type": "transit",
          "uuid": "dcb11046-caec-5b9b-e902-9f1281c520de"
        }
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    },
    "test": {
      "main": false,
      "validate_transit_not_present": false
    }
  }
}
EOF

This test will fail because it includes an enabled transit secrets engine.

The optional test definition adds more context to why the test should fail. The expected behavior is that the test fails because validate_transit_not_present returns false and main returns false.

Now, you have written both success and failure tests.

├── transit-check.sentinel
└── test
   │
   └── transit-check
       ├── fail.json
       └── success.json

├── transit-check.sentinel
└── test
   │
   └── transit-check
       ├── fail.json
       └── success.json

Execute the test.

$ sentinel test

$ sentinel test

Successful output:

PASS - transit-check.sentinel
  PASS - test/transit-check/fail.json
  PASS - test/transit-check/success.json

PASS - transit-check.sentinel
  PASS - test/transit-check/fail.json
  PASS - test/transit-check/success.json

NOTE: If you want to see the tracing and log output for tests, run the command with a -verbose flag.

»Step 6: Deploy Sentinel EGP

Sentinel policies have three enforcement levels:

LevelDescription
advisoryThe policy is allowed to fail. Can be used as a tool to educate new users.
soft-mandatoryThe policy must pass unless an override is specified.
hard-mandatoryThe policy must pass no matter what!

Since this policy is tied to a specific path, the policy type that you are going to create is an Endpoint Governing Policy (EGP).

Ensure that you login with the admin token before completing these steps.

$ vault login -no-print $VAULT_ADMIN_TOKEN

$ vault login -no-print $VAULT_ADMIN_TOKEN

Store the Base64 encoded transit-check.sentinel policy in an environment variable named POLICY.

$ POLICY=$(base64 transit-check.sentinel)

$ POLICY=$(base64 transit-check.sentinel)

Create a policy transit-check with enforcement level of hard-mandatory to reject all requests to secrets under the path kv/solar-sensitive when UV index is 9 or higher.

$ vault write sys/policies/egp/transit-check \
    policy="${POLICY}" \
    paths="sys/mounts/*" \
    enforcement_level="hard-mandatory"

$ vault write sys/policies/egp/transit-check \
    policy="${POLICY}" \
    paths="sys/mounts/*" \
    enforcement_level="hard-mandatory"

Success! Data written to: sys/policies/egp/transit-check

Success! Data written to: sys/policies/egp/transit-check

You can read the policy by executing the following command:

$ vault read sys/policies/egp/transit-check

$ vault read sys/policies/egp/transit-check

Successful output:

Key                  Value
---                  -----
enforcement_level    hard-mandatory
name                 transit-check
paths                [sys/mounts/*]
policy               # Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "s.7j0ybDH9pklYXctdPbhAYoNI"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}

Key                  Value
---                  -----
enforcement_level    hard-mandatory
name                 transit-check
paths                [sys/mounts/*]
policy               # Validate that a transit secrets engine is not already enabled before
# allowing the enabling of a transit secrets engine.
import "http"
import "json"

# Set parameters for Vault address and EGP token values
param vault_addr default "http://127.0.0.1:8200"
param vault_token default "s.7j0ybDH9pklYXctdPbhAYoNI"

# Print some information about the request.
# Note that these messages are printed only when the policy is violated.
print("Request path:", request.path)
print("Request data:", request.data)
print("Request operation:", request.operation)

validate_transit_not_present = func() {
  # Start with validated set to false
  validated = false
  # Make request to the Vault API
  req = http.request(vault_addr + "/v1/sys/mounts").
                      with_header("X-Vault-Token", vault_token)
  resp = http.accept_status_codes([200, 404]).get(req)
  body = json.unmarshal(resp.body)
  print("Body Keys:", keys(body))
  # if transit type secrets engine is found, return validated with false value
  if "data" in keys(body) {
    for values(body.data) as secrets_engine {
      if secrets_engine.type is "transit" {
        validated = false
        break
      } else {
        validated = true
      }
    }
  }
  return validated
}

# Main rule
main = rule when request.path matches "sys/mounts/*" and
                                 request.data.type in ["transit"] and
                                 request.operation in ["update"] {
  validate_transit_not_present()
}

»Verification

Once the policy is deployed, all operations which fail the policy rule assertions will be denied when the server determines that there is already a transit secrets engine enabled.

To confirm, first login with the admin token.

$ vault login -no-print $VAULT_ADMIN_TOKEN

$ vault login -no-print $VAULT_ADMIN_TOKEN

Now, enable one instance of the transit secrets engine.

$ vault secrets enable transit

$ vault secrets enable transit

Successful output example:

Success! Enabled the transit secrets engine at: transit/

Success! Enabled the transit secrets engine at: transit/

Then, attempt to enable another instance of the transit secrets engine at the path another-transit-secrets-engine.

$ vault secrets enable -path=another-transit-secrets-engine transit

$ vault secrets enable -path=another-transit-secrets-engine transit

Expected failure output:

Error enabling: Error making API request.

URL: POST http://127.0.0.1:8200/v1/sys/mounts/another-transit-secrets-engine
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/transit-check" evaluation resulted in denial.

The specific error was:
<nil>

A trace of the execution for policy "root/transit-check" is available:

Result: false

Description: Main rule

print() output:

Request path: sys/mounts/another-transit-secrets-engine
Request data: {"config": {"default_lease_ttl": "0s", "force_no_cache": false, "max_lease_ttl": "0s", "options": null}, "description": "", "external_entropy_access": false, "local": false, "options": null, "seal_wrap": false, "type": "transit"}
Request operation: update
Body Keys: ["sys/" "request_id" "renewable" "lease_duration" "secret/" "warnings" "identity/" "transit/" "auth" "lease_id" "cubbyhole/" "wrap_info" "data"]

Rule "main" (byte offset 1256) = false

  * permission denied

Error enabling: Error making API request.

URL: POST http://127.0.0.1:8200/v1/sys/mounts/another-transit-secrets-engine
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/transit-check" evaluation resulted in denial.

The specific error was:
<nil>

A trace of the execution for policy "root/transit-check" is available:

Result: false

Description: Main rule

print() output:

Request path: sys/mounts/another-transit-secrets-engine
Request data: {"config": {"default_lease_ttl": "0s", "force_no_cache": false, "max_lease_ttl": "0s", "options": null}, "description": "", "external_entropy_access": false, "local": false, "options": null, "seal_wrap": false, "type": "transit"}
Request operation: update
Body Keys: ["sys/" "request_id" "renewable" "lease_duration" "secret/" "warnings" "identity/" "transit/" "auth" "lease_id" "cubbyhole/" "wrap_info" "data"]

Rule "main" (byte offset 1256) = false

  * permission denied

You will note as previously mentioned, the debug print() statement outputs are shown since the policy was violated.

Warning: As with ACL policies, root tokens are NOT subject to Sentinel policy checks. Therefore, use a non-root token for verification test.

»Step 7: Delete Sentinel Policy

To delete the transit-check EGP, execute the following command.

$ vault delete sys/policies/egp/transit-check

$ vault delete sys/policies/egp/transit-check

Successful output example:

Success! Data deleted (if it existed) at: sys/policies/egp/transit-check

Success! Data deleted (if it existed) at: sys/policies/egp/transit-check

»Going even further with Vault Enterprise Namespaces

If you want to try a more advanced example involving the Vault Enterprise Namespaces feature, you can follow the guidance in Restrict Members of a Group with Sentinel to restrict the subgroups and entities of a group by requiring all subgroups and entities of a group to belong to the same namespace.

»Step 8: Cleanup

To clean up the example files and stop your Vault dev server follow these steps.

Remove the files.

$ rm -f transit-check-payload.json \
    transit-check.sentinel\
    vault-sentinel-configuration.hcl

$ rm -f transit-check-payload.json \
    transit-check.sentinel\
    vault-sentinel-configuration.hcl

Remove the Sentinel tests.

$ rm -rf test

$ rm -rf test

In the other terminal session where you started the Vault dev server, press CTRL+C to stop Vault.

»Troubleshooting

If you encounter an error such as this example while testing the EGP.

Error enabling: Error making API request.

URL: POST http://127.0.0.1:8200/v1/sys/mounts/example
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/transit-example" evaluation resulted in denial.

The specific error was:
root/transit-example:4:1: Import "http" is not available

A trace of the execution for policy "root/transit-example" is available:

Result: false
Error: false

Description: Validate that a Transit secrets engine is not already enabled
when an operation to enable a Transit secrets engine is attempted

  * permission denied

Error enabling: Error making API request.

URL: POST http://127.0.0.1:8200/v1/sys/mounts/example
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/transit-example" evaluation resulted in denial.

The specific error was:
root/transit-example:4:1: Import "http" is not available

A trace of the execution for policy "root/transit-example" is available:

Result: false
Error: false

Description: Validate that a Transit secrets engine is not already enabled
when an operation to enable a Transit secrets engine is attempted

  * permission denied

Note the Import "http" is not available portion of the error. This indicates that Vault is not configured to allow the HTTP import. Check the instructions in Step 1: Configure Vault and make sure you have configured and restarted your Vault.

»Help and Reference

stdin: is not a tty