Vaultx.Sys.Policy (Vaultx v0.7.0)

View Source

Enterprise policy management for HashiCorp Vault system backend.

This module provides comprehensive policy management capabilities for Vault ACL (Access Control List) policies, enabling fine-grained access control and security governance for enterprise Vault deployments. It supports complete policy lifecycle management with validation and compliance features.

Enterprise Policy Management

  • List and audit all configured security policies
  • Read and analyze specific policy content and rules
  • Create and update policies with validation
  • Safely delete policies with dependency checking
  • Policy syntax validation and compliance verification

API Endpoints

This module implements the following Vault API endpoints:

  • GET /sys/policy - List policies
  • GET /sys/policy/:name - Read policy
  • POST /sys/policy/:name - Create/Update policy
  • DELETE /sys/policy/:name - Delete policy

Usage Examples

# List all policies
{:ok, policies} = Vaultx.Sys.Policy.list()
policies #=> ["default", "root", "my-policy"]

# Read a specific policy
{:ok, policy} = Vaultx.Sys.Policy.read("my-policy")
policy.rules #=> "path "secret/*" { capabilities = ["read"] }"

# Create or update a policy
rules = ~s(path "secret/myapp/*" { capabilities = ["create", "read", "update", "delete"] })
:ok = Vaultx.Sys.Policy.write("myapp-policy", rules)

# Delete a policy
:ok = Vaultx.Sys.Policy.delete("old-policy")

Policy Language

Vault policies are written in HCL (HashiCorp Configuration Language) format:

# Allow full access to secret/myapp/*
path "secret/myapp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Allow read-only access to secret/shared/*
path "secret/shared/*" {
  capabilities = ["read", "list"]
}

# Deny access to secret/admin/*
path "secret/admin/*" {
  capabilities = ["deny"]
}

Security Considerations

  • Policy changes take effect immediately for all associated tokens
  • The "root" policy cannot be deleted or modified
  • The "default" policy is automatically attached to all tokens
  • Use principle of least privilege when designing policies

API Compliance

Fully implements HashiCorp Vault Policy API:

Summary

Types

policy_info()

Policy information structure.

policy_opts()

Policy management options.

Functions

delete(name, opts \\ [])

Delete a policy.

list(opts \\ [])

List all configured policies.

read(name, opts \\ [])

Read a specific policy.

write(name, rules, opts \\ [])

Create or update a policy.

Types

policy_info()

@type policy_info() :: %{name: String.t(), rules: String.t()}

Policy information structure.

policy_opts()

@type policy_opts() :: [
  timeout: pos_integer(),
  retry_attempts: non_neg_integer(),
  namespace: String.t()
]

Policy management options.

Functions

delete(name, opts \\ [])

@spec delete(String.t(), policy_opts()) :: Vaultx.Types.result(:ok)

Delete a policy.

Permanently removes the specified policy. This will immediately affect all tokens associated with this policy. Implements DELETE /sys/policy/:name.

Security Notes

  • The "root" policy cannot be deleted
  • The "default" policy cannot be deleted
  • Deletion takes effect immediately for all associated tokens

Examples

:ok = Vaultx.Sys.Policy.delete("old-policy")

list(opts \\ [])

@spec list(policy_opts()) :: Vaultx.Types.result([String.t()])

List all configured policies.

Returns a list of policy names available in the Vault instance. Implements GET /sys/policy.

Examples

{:ok, policies} = Vaultx.Sys.Policy.list()
policies #=> ["default", "root", "my-policy"]

read(name, opts \\ [])

@spec read(String.t(), policy_opts()) :: Vaultx.Types.result(policy_info())

Read a specific policy.

Retrieves the policy rules for the specified policy name. Implements GET /sys/policy/:name.

Examples

{:ok, policy} = Vaultx.Sys.Policy.read("my-policy")
policy.name #=> "my-policy"
policy.rules #=> "path "secret/*" { capabilities = ["read"] }"

write(name, rules, opts \\ [])

@spec write(String.t(), String.t(), policy_opts()) :: Vaultx.Types.result(:ok)

Create or update a policy.

Creates a new policy or updates an existing one with the specified rules. Policy changes take effect immediately for all associated tokens. Implements POST /sys/policy/:name.

Examples

rules = ~s(path "secret/myapp/*" { capabilities = ["create", "read", "update", "delete"] })
:ok = Vaultx.Sys.Policy.write("myapp-policy", rules)