From 3615154f2e30cb9e0b91540f0fb7b6db74672680 Mon Sep 17 00:00:00 2001 From: James Anderton Date: Tue, 3 Feb 2026 00:49:15 -0600 Subject: [PATCH 1/5] feat(vault): add Vault product with 6 plugins and 16 skills Add comprehensive Vault skills for secrets management, authentication, operations, enterprise features, MCP integration, and HashiCorp product integrations. - **vault-authentication** (5 skills) - auth-methods: AppRole, Kubernetes, OIDC, AWS/Azure/GCP auth - policies: HCL policy syntax, capabilities, templating - token-management: Service/batch/periodic tokens, accessors - identity-system: Entities, aliases, groups, OIDC provider - response-wrapping: Cubbyhole, wrap/unwrap, malfeasance detection - **vault-secrets-management** (2 skills) - secrets-engines: KV, database, PKI, transit, SSH, cloud engines - vault-agent: Auto-auth, templating, caching, process supervisor - **vault-operations** (3 skills) - kubernetes-integration: Injector, CSI provider, Helm deployment - production-operations: HA, performance tuning, backup/restore - troubleshooting: Diagnostics, audit analysis, common errors - **vault-enterprise** (1 skill) - enterprise-features: Namespaces, replication, Sentinel, MFA, HSM - **vault-mcp-integration** (2 skills) - vault-mcp-server: MCP server setup, tool configuration - mcp-secrets-workflows: AI-assisted secret management patterns - **vault-hashicorp-integrations** (3 skills) - consul-secrets: Dynamic Consul ACL tokens - nomad-secrets: Dynamic Nomad ACL tokens - terraform-cloud-secrets: Dynamic TFC API tokens All skills follow Anthropic Agent Skills best practices: - Descriptions include 'Use when' trigger phrases - Reference files use 'For X, see' linking for in-time revelation - Skills under 8KB for efficient context loading - Consistent frontmatter with name and description fields Content sourced from official HashiCorp Vault documentation. HVD-unique content excluded per content attribution analysis. Repository totals: 11 plugins, 29 skills (terraform: 3/9, packer: 2/4, vault: 6/16) --- .claude-plugin/marketplace.json | 78 ++ CHANGELOG.md | 21 + README.md | 16 +- vault/README.md | 125 +++ .../authentication/.claude-plugin/plugin.json | 40 + vault/authentication/SPEC.md | 156 ++++ .../skills/auth-methods/SKILL.md | 168 ++++ .../auth-methods/references/auth-methods.md | 574 ++++++++++++ .../skills/identity-system/SKILL.md | 239 +++++ .../references/identity-system.md | 120 +++ vault/authentication/skills/policies/SKILL.md | 221 +++++ .../skills/policies/references/policies.md | 609 +++++++++++++ .../skills/response-wrapping/SKILL.md | 189 ++++ .../references/response-wrapping.md | 73 ++ .../skills/token-management/SKILL.md | 236 +++++ .../references/token-management.md | 116 +++ vault/enterprise/.claude-plugin/plugin.json | 40 + vault/enterprise/SPEC.md | 107 +++ .../skills/enterprise-features/SKILL.md | 237 +++++ .../references/enterprise.md | 389 +++++++++ .../.claude-plugin/plugin.json | 40 + vault/hashicorp-integrations/SPEC.md | 99 +++ .../skills/consul-secrets/SKILL.md | 241 ++++++ .../references/consul-secrets.md | 103 +++ .../skills/nomad-secrets/SKILL.md | 281 ++++++ .../nomad-secrets/references/nomad-secrets.md | 103 +++ .../skills/terraform-cloud-secrets/SKILL.md | 269 ++++++ .../references/terraform-cloud-secrets.md | 106 +++ .../.claude-plugin/plugin.json | 40 + vault/mcp-integration/SPEC.md | 117 +++ .../skills/mcp-secrets-workflows/SKILL.md | 295 +++++++ .../references/mcp-secrets-workflows.md | 498 +++++++++++ .../skills/vault-mcp-server/SKILL.md | 266 ++++++ .../references/vault-mcp-server.md | 441 ++++++++++ vault/operations/.claude-plugin/plugin.json | 40 + vault/operations/SPEC.md | 108 +++ .../skills/kubernetes-integration/SKILL.md | 208 +++++ .../references/kubernetes.md | 638 ++++++++++++++ .../skills/production-operations/SKILL.md | 219 +++++ .../references/enterprise.md | 545 ++++++++++++ .../references/production-operations.md | 593 +++++++++++++ .../skills/troubleshooting/SKILL.md | 232 +++++ .../references/troubleshooting.md | 787 +++++++++++++++++ .../.claude-plugin/plugin.json | 39 + vault/secrets-management/SPEC.md | 107 +++ .../skills/secrets-engines/SKILL.md | 149 ++++ .../references/secrets-engines.md | 762 ++++++++++++++++ .../skills/vault-agent/SKILL.md | 170 ++++ .../vault-agent/references/vault-agent.md | 814 ++++++++++++++++++ 49 files changed, 12063 insertions(+), 1 deletion(-) create mode 100644 vault/README.md create mode 100644 vault/authentication/.claude-plugin/plugin.json create mode 100644 vault/authentication/SPEC.md create mode 100644 vault/authentication/skills/auth-methods/SKILL.md create mode 100644 vault/authentication/skills/auth-methods/references/auth-methods.md create mode 100644 vault/authentication/skills/identity-system/SKILL.md create mode 100644 vault/authentication/skills/identity-system/references/identity-system.md create mode 100644 vault/authentication/skills/policies/SKILL.md create mode 100644 vault/authentication/skills/policies/references/policies.md create mode 100644 vault/authentication/skills/response-wrapping/SKILL.md create mode 100644 vault/authentication/skills/response-wrapping/references/response-wrapping.md create mode 100644 vault/authentication/skills/token-management/SKILL.md create mode 100644 vault/authentication/skills/token-management/references/token-management.md create mode 100644 vault/enterprise/.claude-plugin/plugin.json create mode 100644 vault/enterprise/SPEC.md create mode 100644 vault/enterprise/skills/enterprise-features/SKILL.md create mode 100644 vault/enterprise/skills/enterprise-features/references/enterprise.md create mode 100644 vault/hashicorp-integrations/.claude-plugin/plugin.json create mode 100644 vault/hashicorp-integrations/SPEC.md create mode 100644 vault/hashicorp-integrations/skills/consul-secrets/SKILL.md create mode 100644 vault/hashicorp-integrations/skills/consul-secrets/references/consul-secrets.md create mode 100644 vault/hashicorp-integrations/skills/nomad-secrets/SKILL.md create mode 100644 vault/hashicorp-integrations/skills/nomad-secrets/references/nomad-secrets.md create mode 100644 vault/hashicorp-integrations/skills/terraform-cloud-secrets/SKILL.md create mode 100644 vault/hashicorp-integrations/skills/terraform-cloud-secrets/references/terraform-cloud-secrets.md create mode 100644 vault/mcp-integration/.claude-plugin/plugin.json create mode 100644 vault/mcp-integration/SPEC.md create mode 100644 vault/mcp-integration/skills/mcp-secrets-workflows/SKILL.md create mode 100644 vault/mcp-integration/skills/mcp-secrets-workflows/references/mcp-secrets-workflows.md create mode 100644 vault/mcp-integration/skills/vault-mcp-server/SKILL.md create mode 100644 vault/mcp-integration/skills/vault-mcp-server/references/vault-mcp-server.md create mode 100644 vault/operations/.claude-plugin/plugin.json create mode 100644 vault/operations/SPEC.md create mode 100644 vault/operations/skills/kubernetes-integration/SKILL.md create mode 100644 vault/operations/skills/kubernetes-integration/references/kubernetes.md create mode 100644 vault/operations/skills/production-operations/SKILL.md create mode 100644 vault/operations/skills/production-operations/references/enterprise.md create mode 100644 vault/operations/skills/production-operations/references/production-operations.md create mode 100644 vault/operations/skills/troubleshooting/SKILL.md create mode 100644 vault/operations/skills/troubleshooting/references/troubleshooting.md create mode 100644 vault/secrets-management/.claude-plugin/plugin.json create mode 100644 vault/secrets-management/SPEC.md create mode 100644 vault/secrets-management/skills/secrets-engines/SKILL.md create mode 100644 vault/secrets-management/skills/secrets-engines/references/secrets-engines.md create mode 100644 vault/secrets-management/skills/vault-agent/SKILL.md create mode 100644 vault/secrets-management/skills/vault-agent/references/vault-agent.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6aca4cb..080a843 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -72,6 +72,84 @@ "category": "integration", "license": "MPL-2.0", "strict": false + }, + { + "name": "vault-secrets-management", + "source": "./vault/secrets-management", + "description": "Vault secrets engine skills including KV, database, AWS, Transit, PKI, and Vault Agent.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "secrets", "kv", "database", "transit", "pki", "vault-agent", "dynamic-credentials"], + "category": "integration", + "license": "MPL-2.0", + "strict": false + }, + { + "name": "vault-authentication", + "source": "./vault/authentication", + "description": "Vault authentication, identity, and token management including AppRole, Kubernetes, OIDC, policies, tokens, and response wrapping.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "auth", "authentication", "approle", "kubernetes", "oidc", "policies", "tokens", "identity", "wrapping"], + "category": "integration", + "license": "MPL-2.0", + "strict": false + }, + { + "name": "vault-operations", + "source": "./vault/operations", + "description": "Vault operational skills including Kubernetes integration, HA/DR, monitoring, and troubleshooting.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "operations", "kubernetes", "vso", "ha", "dr", "monitoring", "troubleshooting"], + "category": "integration", + "license": "MPL-2.0", + "strict": false + }, + { + "name": "vault-enterprise", + "source": "./vault/enterprise", + "description": "Vault Enterprise skills including namespaces, replication, Sentinel policies, MFA, and HSM integration.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "enterprise", "namespaces", "replication", "sentinel", "mfa", "hsm", "control-groups"], + "category": "integration", + "license": "MPL-2.0", + "strict": false + }, + { + "name": "vault-mcp-integration", + "source": "./vault/mcp-integration", + "description": "Vault MCP Server integration skills for AI-assisted secrets management workflows.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "mcp", "model-context-protocol", "claude", "ai", "secrets", "automation"], + "category": "integration", + "license": "MPL-2.0", + "strict": false + }, + { + "name": "vault-hashicorp-integrations", + "source": "./vault/hashicorp-integrations", + "description": "Vault secrets engines for HashiCorp products - dynamic tokens for Consul, Nomad, and Terraform Cloud.", + "version": "0.1.0", + "author": { + "name": "HashiCorp" + }, + "keywords": ["vault", "consul", "nomad", "terraform", "dynamic-credentials", "acl-tokens", "hashicorp"], + "category": "integration", + "license": "MPL-2.0", + "strict": false } ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index ece1f01..7f7c5a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,27 @@ All notable changes to the HashiCorp Agent Skills. ### Added - `terraform-search-import` skill for discovering existing resources with Terraform Search and bulk import +- Vault product with 6 plugins and 16 skills + - `vault-secrets-management`: secrets-engines, vault-agent + - `vault-authentication`: auth-methods, policies, token-management, identity-system, response-wrapping + - `vault-operations`: kubernetes-integration, production-operations, troubleshooting + - `vault-enterprise`: enterprise-features (namespaces, replication, Sentinel, MFA, HSM) + - `vault-mcp-integration`: vault-mcp-server, mcp-secrets-workflows + - `vault-hashicorp-integrations`: consul-secrets, nomad-secrets, terraform-cloud-secrets +- Token management, identity system, and response wrapping skills for authentication workflows +- HashiCorp product integration skills for Consul, Nomad, and Terraform Cloud/Enterprise +- Vault Enterprise skills for multi-tenancy, replication, and policy-as-code +- Vault MCP Server integration skills for AI-assisted secrets management +- Enhanced SPEC.md files with comprehensive user stories and functional requirements +- Vault MCP Server integration for all Vault plugins +- Product template system in `examples/` directory + - `examples/README.md` - Comprehensive guide for adding products, plugins, and skills + - `examples/spec.md` - Spec-Kit format specification with user stories + - `examples/questionnaire.md` - Questions reference for automation + - `examples/new-product-template/` - Template files with placeholders + - `examples/commands/new-product/` - `/new-product` slash command for interactive scaffolding +- `CONTRIBUTING.md` - Contribution guidelines +- 11 Claude Code plugins with 29 total skills ## 0.1.0 diff --git a/README.md b/README.md index a5ae88e..f4fd08e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A collection of Agent skills and Claude Code plugins for HashiCorp products. |:--------|:----------| | [Terraform](./terraform/) | Write HCL code, build modules, develop providers, and run tests | | [Packer](./packer/) | Build machine images on AWS, Azure, and Windows; integrate with HCP Packer registry | +| [Vault](./vault/) | Manage secrets, configure authentication, operate clusters, and integrate with AI assistants | > **Legal Note:** Your use of a third party MCP Client/LLM is subject solely to the terms of use for such MCP/LLM, and IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP Clients/LLMs, and may not be able to provide support to resolve issues which are caused by the third party tools. @@ -37,6 +38,12 @@ claude plugin install terraform-module-generation@hashicorp claude plugin install terraform-provider-development@hashicorp claude plugin install packer-builders@hashicorp claude plugin install packer-hcp@hashicorp +claude plugin install vault-secrets-management@hashicorp +claude plugin install vault-authentication@hashicorp +claude plugin install vault-operations@hashicorp +claude plugin install vault-enterprise@hashicorp +claude plugin install vault-mcp-integration@hashicorp +claude plugin install vault-hashicorp-integrations@hashicorp ``` Or use the interactive interface: @@ -52,7 +59,8 @@ agent-skills/ │ └── marketplace.json ├── terraform/ # Terraform skills ├── packer/ # Packer skills -├── / # Future products (Vault, Consul, etc.) +├── vault/ # Vault skills +├── examples/ # Templates for adding new products └── README.md ``` @@ -67,6 +75,12 @@ Each product folder contains plugins, and each plugin contains skills: └── SKILL.md ``` +## Contributing + +Want to add skills for a new HashiCorp product? See [CONTRIBUTING.md](CONTRIBUTING.md) and [examples/README.md](examples/README.md) for detailed instructions. + +Use the `/new-product` command for interactive scaffolding, or follow the templates in `examples/new-product-template/`. + ## License MPL-2.0 diff --git a/vault/README.md b/vault/README.md new file mode 100644 index 0000000..00bb943 --- /dev/null +++ b/vault/README.md @@ -0,0 +1,125 @@ +# HashiCorp Vault Agent Skills + +Agent skills for HashiCorp Vault identity-based secrets and encryption management. + +## Overview + +Vault secures, stores, and tightly controls access to tokens, passwords, certificates, encryption keys, and other sensitive data. These skills provide AI-assisted guidance for secrets management, authentication, operational tasks, enterprise features, and HashiCorp product integrations. + +## Available Plugins + +| Plugin | Description | Skills | +|--------|-------------|--------| +| [vault-secrets-management](secrets-management/) | Generate and manage static and dynamic secrets | `secrets-engines`, `vault-agent` | +| [vault-authentication](authentication/) | Configure auth methods, policies, tokens, and identity | `auth-methods`, `policies`, `token-management`, `identity-system`, `response-wrapping` | +| [vault-operations](operations/) | Deploy, monitor, and troubleshoot Vault | `kubernetes-integration`, `production-operations`, `troubleshooting` | +| [vault-enterprise](enterprise/) | Vault Enterprise features | `enterprise-features` | +| [vault-mcp-integration](mcp-integration/) | Use Vault with MCP-enabled AI assistants | `vault-mcp-server`, `mcp-secrets-workflows` | +| [vault-hashicorp-integrations](hashicorp-integrations/) | Dynamic credentials for HashiCorp products | `consul-secrets`, `nomad-secrets`, `terraform-cloud-secrets` | + +## Installation + +### Install All Vault Plugins + +```bash +claude plugin install vault-secrets-management@hashicorp +claude plugin install vault-authentication@hashicorp +claude plugin install vault-operations@hashicorp +claude plugin install vault-enterprise@hashicorp +claude plugin install vault-mcp-integration@hashicorp +claude plugin install vault-hashicorp-integrations@hashicorp +``` + +### Install Individual Skills + +```bash +# Secrets management +npx skills add hashicorp/agent-skills/vault/secrets-management/skills/secrets-engines +npx skills add hashicorp/agent-skills/vault/secrets-management/skills/vault-agent + +# Authentication, identity, and tokens +npx skills add hashicorp/agent-skills/vault/authentication/skills/auth-methods +npx skills add hashicorp/agent-skills/vault/authentication/skills/policies +npx skills add hashicorp/agent-skills/vault/authentication/skills/token-management +npx skills add hashicorp/agent-skills/vault/authentication/skills/identity-system +npx skills add hashicorp/agent-skills/vault/authentication/skills/response-wrapping + +# Operations +npx skills add hashicorp/agent-skills/vault/operations/skills/kubernetes-integration +npx skills add hashicorp/agent-skills/vault/operations/skills/production-operations +npx skills add hashicorp/agent-skills/vault/operations/skills/troubleshooting + +# Enterprise +npx skills add hashicorp/agent-skills/vault/enterprise/skills/enterprise-features + +# MCP Integration +npx skills add hashicorp/agent-skills/vault/mcp-integration/skills/vault-mcp-server +npx skills add hashicorp/agent-skills/vault/mcp-integration/skills/mcp-secrets-workflows + +# HashiCorp Integrations +npx skills add hashicorp/agent-skills/vault/hashicorp-integrations/skills/consul-secrets +npx skills add hashicorp/agent-skills/vault/hashicorp-integrations/skills/nomad-secrets +npx skills add hashicorp/agent-skills/vault/hashicorp-integrations/skills/terraform-cloud-secrets +``` + +## MCP Server Integration + +All Vault plugins include configuration for the [Vault MCP Server](https://github.com/hashicorp/vault-mcp-server): + +```bash +export VAULT_ADDR="https://vault.example.com:8200" +export VAULT_TOKEN="hvs.xxxxx" +export VAULT_NAMESPACE="admin" # Optional, for Enterprise +``` + +The MCP server enables Claude and other AI assistants to interact directly with Vault: +- Create and manage secrets engine mounts +- Read, write, and list secrets +- Manage KV v1 and v2 secrets + +See [vault-mcp-integration](mcp-integration/) for setup and usage patterns. + +## Plugin Overview + +### Core Vault Skills + +- **secrets-engines**: KV, Database, AWS, Transit, PKI, SSH engines +- **vault-agent**: Auto-auth, caching, templating, sidecar patterns + +### Authentication and Identity Skills + +- **auth-methods**: AppRole, Kubernetes, OIDC, AWS, Azure, GCP, LDAP +- **policies**: HCL syntax, templated policies, CI/CD patterns +- **token-management**: Service, batch, periodic, orphan tokens, accessors +- **identity-system**: Entities, aliases, groups, OIDC provider +- **response-wrapping**: Cubbyhole, wrapped tokens, secure secret distribution + +### Operations Skills + +- **kubernetes-integration**: VSO, Agent Injector, CSI Provider +- **production-operations**: HA, DR, monitoring, backup, upgrades +- **troubleshooting**: Diagnostics, debugging, anti-patterns + +### Enterprise Skills (requires Vault Enterprise license) + +- **enterprise-features**: Namespaces, replication, Sentinel, MFA, HSM + +### MCP Integration Skills + +- **vault-mcp-server**: Installation, configuration, IDE integration +- **mcp-secrets-workflows**: Tool usage patterns for AI workflows + +### HashiCorp Integration Skills + +- **consul-secrets**: Dynamic Consul ACL tokens +- **nomad-secrets**: Dynamic Nomad ACL tokens +- **terraform-cloud-secrets**: Dynamic Terraform Cloud/Enterprise API tokens + +## Documentation + +- [Vault Documentation](https://developer.hashicorp.com/vault) +- [Vault Enterprise](https://developer.hashicorp.com/vault/docs/enterprise) +- [Vault API Reference](https://developer.hashicorp.com/vault/api-docs) +- [Vault Tutorials](https://developer.hashicorp.com/vault/tutorials) +- [Vault MCP Server](https://github.com/hashicorp/vault-mcp-server) +- [HCP Vault](https://developer.hashicorp.com/hcp/docs/vault) diff --git a/vault/authentication/.claude-plugin/plugin.json b/vault/authentication/.claude-plugin/plugin.json new file mode 100644 index 0000000..4a7f32a --- /dev/null +++ b/vault/authentication/.claude-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "vault-authentication", + "version": "0.1.0", + "description": "Skills for configuring Vault authentication methods and access policies. Covers AppRole, Kubernetes, OIDC, AWS, LDAP auth, and HCL policy authoring.", + "author": "HashiCorp", + "homepage": "https://developer.hashicorp.com/vault/docs/auth", + "repository": "https://github.com/hashicorp/agent-skills", + "license": "MPL-2.0", + "keywords": [ + "vault", + "auth", + "authentication", + "approle", + "kubernetes", + "oidc", + "ldap", + "policies", + "acl", + "hashicorp" + ], + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "VAULT_ADDR", + "-e", + "VAULT_TOKEN", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${VAULT_ADDR}", + "VAULT_TOKEN": "${VAULT_TOKEN}" + } + } + } +} diff --git a/vault/authentication/SPEC.md b/vault/authentication/SPEC.md new file mode 100644 index 0000000..25cac34 --- /dev/null +++ b/vault/authentication/SPEC.md @@ -0,0 +1,156 @@ +# Specification: vault-authentication + +**Status**: Published +**Version**: 0.3.0 + +--- + +## Overview + +This plugin provides skills for configuring Vault authentication methods, writing access control policies, managing tokens, configuring the identity system, and implementing secure secret distribution patterns. Covers machine authentication (AppRole, Kubernetes, AWS, Azure, GCP), human authentication (OIDC, LDAP), token lifecycle, identity entities and groups, and response wrapping. + +--- + +## User Stories + +### US-1: Platform Engineer Configuring Kubernetes Authentication (P1) + +A platform engineer needs to configure Kubernetes workloads to authenticate with Vault and retrieve secrets without manual token management. + +**Why this priority**: Kubernetes is the dominant container orchestration platform. K8s-native auth is essential for cloud-native deployments. + +**Acceptance Criteria**: +1. Given a user asks about Kubernetes auth, when the skill is invoked, then it provides Kubernetes auth method configuration including role binding and ClusterRoleBinding setup. +2. Given a user mentions service accounts, when queried, then the skill explains service account binding patterns and annotations_as_alias_metadata. +3. Given a Kubernetes 1.21+ question, when asked about token handling, then the skill explains short-lived bound service account token options. + +### US-2: DevOps Engineer Setting Up CI/CD Authentication (P1) + +A DevOps engineer needs to configure GitHub Actions/GitLab CI to authenticate with Vault for deployment secrets. + +**Why this priority**: Secure CI/CD integration is critical for DevOps pipelines. + +**Acceptance Criteria**: +1. Given a CI/CD authentication question, when the skill is invoked, then it provides AppRole or JWT auth configuration. +2. Given a trusted broker pattern question, when queried, then the skill explains response wrapping and secure credential distribution. +3. Given a response wrapping question, when asked about SecretID, then the skill explains wrapped SecretID workflow with TTL enforcement. + +### US-3: Security Engineer Writing Access Policies (P1) + +A security engineer needs to create fine-grained access control policies for multiple teams accessing different secrets paths. + +**Why this priority**: Policies are the foundation of Vault's security model. Incorrect policies create security risks. + +**Acceptance Criteria**: +1. Given a user requests policy creation, when the skill is invoked, then it generates valid HCL policy syntax with proper path patterns. +2. Given a user asks about templated policies, when queried, then the skill explains identity templating with {{identity.entity}} patterns. +3. Given a KV v2 question, when asked about paths, then the skill emphasizes /data/ path segment requirement. +4. Given a response wrapping policy question, when asked, then the skill shows min/max_wrapping_ttl enforcement. + +### US-4: Identity Admin Configuring SSO (P2) + +An identity administrator needs to configure OIDC authentication for human users via Okta/Azure AD. + +**Acceptance Criteria**: +1. Given an OIDC configuration request, when the skill is invoked, then it provides complete OIDC auth setup including claims mapping. +2. Given a group-based access question, when queried, then the skill explains external groups and policy assignment. +3. Given an OIDC group mapping question, when asked about workflow, then the skill explains the full OIDC group mapping workflow. + +### US-5: Security Engineer Implementing Trusted Broker (P2) + +A security engineer needs to implement the AppRole trusted broker pattern for secure CI/CD secret distribution. + +**Acceptance Criteria**: +1. Given a trusted broker question, when the skill is invoked, then it provides complete trusted broker architecture with workflow diagram. +2. Given a policy question, when asked about broker permissions, then the skill shows broker policy with wrapping TTL constraints. +3. Given a security configuration question, when asked, then the skill explains secret_id_num_uses, secret_id_ttl, and CIDR binding. + +### US-6: Platform Engineer Managing Token Lifecycle (P1) + +A platform engineer needs to understand and manage different token types for various workload patterns. + +**Why this priority**: Token management is fundamental to Vault operations. Incorrect token usage causes outages. + +**Acceptance Criteria**: +1. Given a token type question, when the skill is invoked, then it explains service vs batch tokens and when to use each. +2. Given a long-running service question, when queried, then the skill provides periodic token configuration. +3. Given a token renewal question, when asked, then the skill explains TTL, max TTL, and renewal strategies. + +### US-7: Administrator Configuring Unified Identity (P2) + +An administrator needs to map users from multiple auth methods to a single identity for consistent policy application. + +**Acceptance Criteria**: +1. Given an identity configuration question, when the skill is invoked, then it explains entities, aliases, and group membership. +2. Given an OIDC provider question, when queried, then the skill provides Vault-as-OIDC-provider configuration. +3. Given a policy inheritance question, when asked, then the skill explains entity and group policy assignment. + +### US-8: Developer Implementing Secure Secret Handoff (P2) + +A developer needs to securely pass secrets to another service using response wrapping. + +**Acceptance Criteria**: +1. Given a response wrapping question, when the skill is invoked, then it explains cubbyhole and wrapped token patterns. +2. Given a malfeasance detection question, when queried, then the skill explains single-use tokens and detection. +3. Given a bootstrap question, when asked, then the skill provides wrapped token bootstrap workflow. + +--- + +## Functional Requirements + +| ID | Requirement | +|----|-------------| +| FR-001 | Skill MUST cover AppRole authentication with trusted broker pattern | +| FR-002 | Skill MUST cover Kubernetes auth with 1.21+ token handling | +| FR-003 | Skill MUST cover OIDC auth with group mapping workflow | +| FR-004 | Skill MUST cover AWS IAM auth with server ID header | +| FR-005 | Skill MUST cover Azure AD, GCP IAM, LDAP auth methods | +| FR-006 | Skill MUST explain Identity system and entities | +| FR-007 | Skill MUST cover HCL policy syntax with all capabilities | +| FR-008 | Skill MUST explain KV v2 /data/ path requirement | +| FR-009 | Skill MUST cover templated policies with identity tokens | +| FR-010 | Skill MUST cover response wrapping TTL enforcement | +| FR-011 | Skill MUST explain CI/CD pipeline policy patterns | +| FR-012 | Skill MUST cover Sentinel policies (Enterprise) | +| FR-013 | Skill MUST explain service vs batch token differences | +| FR-014 | Skill MUST cover periodic token configuration | +| FR-015 | Skill MUST explain token accessor usage patterns | +| FR-016 | Skill MUST cover orphan token creation and implications | +| FR-017 | Skill MUST explain entity and alias creation | +| FR-018 | Skill MUST cover internal and external group types | +| FR-019 | Skill MUST explain identity token (OIDC) generation | +| FR-020 | Skill MUST cover cubbyhole secrets engine | +| FR-021 | Skill MUST explain wrap/unwrap operations | +| FR-022 | Skill MUST cover wrapped token bootstrap patterns | + +--- + +## Skills Included + +| Skill | Description | +|-------|-------------| +| `auth-methods` | Configure AppRole, Kubernetes, OIDC, AWS, Azure, GCP, LDAP auth | +| `policies` | Write HCL policies, templated policies, and debug permissions | +| `token-management` | Manage service, batch, periodic, orphan tokens and accessors | +| `identity-system` | Configure entities, aliases, groups, and OIDC provider | +| `response-wrapping` | Implement cubbyhole wrapping and secure secret distribution | + +--- + +## Content Sources + +- HashiCorp Vault Documentation +- Vault Tutorials +- CSA Enterprise Patterns (genericized) + +--- + +## References + +- [Vault Auth Methods](https://developer.hashicorp.com/vault/docs/auth) +- [AppRole Auth](https://developer.hashicorp.com/vault/docs/auth/approle) +- [Kubernetes Auth](https://developer.hashicorp.com/vault/docs/auth/kubernetes) +- [Vault Policies](https://developer.hashicorp.com/vault/docs/concepts/policies) +- [Token Concepts](https://developer.hashicorp.com/vault/docs/concepts/tokens) +- [Identity Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/identity) +- [Response Wrapping](https://developer.hashicorp.com/vault/docs/concepts/response-wrapping) diff --git a/vault/authentication/skills/auth-methods/SKILL.md b/vault/authentication/skills/auth-methods/SKILL.md new file mode 100644 index 0000000..c22d700 --- /dev/null +++ b/vault/authentication/skills/auth-methods/SKILL.md @@ -0,0 +1,168 @@ +--- +name: auth-methods +description: Configure Vault authentication methods. Use when asked about AppRole, Kubernetes auth, OIDC/JWT, AWS IAM auth, Azure auth, GCP auth, LDAP, GitHub auth, or the trusted broker pattern. Covers identity verification and token generation. +--- + +# Vault Authentication Methods + +Auth methods verify client identity and return a Vault token with attached policies. Each method is designed for specific use cases: machine-to-machine (AppRole, Kubernetes), human users (OIDC, LDAP), or cloud workloads (AWS, Azure, GCP). + +## Reference + +- [Vault Auth Methods Documentation](https://developer.hashicorp.com/vault/docs/auth) +- [Detailed Auth Methods Reference](references/auth-methods.md) + +--- + +## When to Use This Skill + +- **AppRole**: CI/CD pipelines, automated services, non-Kubernetes workloads +- **Kubernetes**: Pods running in Kubernetes clusters +- **OIDC/JWT**: Human users via SSO (Okta, Azure AD, Google Workspace) +- **AWS IAM**: EC2 instances, Lambda functions, ECS tasks +- **Azure**: Azure VMs, AKS, Azure Functions +- **GCP**: GCE instances, GKE, Cloud Functions +- **LDAP**: Enterprise directory integration +- **Trusted broker**: Wrapping tokens for secure credential distribution + +--- + +## Auth Method Selection + +| Use Case | Auth Method | +|----------|-------------| +| CI/CD pipelines | AppRole | +| Kubernetes pods | Kubernetes | +| Human users (SSO) | OIDC | +| AWS workloads | AWS IAM | +| Azure workloads | Azure | +| GCP workloads | GCP | +| Enterprise directory | LDAP | +| GitHub Actions | GitHub or JWT | + +--- + +## Quick Reference + +### AppRole (Recommended for Automation) + +```bash +# Enable AppRole +vault auth enable approle + +# Create role +vault write auth/approle/role/my-app \ + token_policies="app-policy" \ + token_ttl=1h \ + secret_id_ttl=10m + +# Get credentials +vault read auth/approle/role/my-app/role-id +vault write -f auth/approle/role/my-app/secret-id + +# Login +vault write auth/approle/login \ + role_id="" \ + secret_id="" +``` + +### Kubernetes + +```bash +# Enable Kubernetes auth +vault auth enable kubernetes + +# Configure with cluster info +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.default.svc:443" + +# Create role bound to service account +vault write auth/kubernetes/role/my-app \ + bound_service_account_names=my-app-sa \ + bound_service_account_namespaces=default \ + policies=app-policy \ + ttl=1h +``` + +### OIDC (Human Users) + +```bash +# Enable OIDC +vault auth enable oidc + +# Configure provider (e.g., Okta) +vault write auth/oidc/config \ + oidc_discovery_url="https://your-org.okta.com" \ + oidc_client_id="vault-client-id" \ + oidc_client_secret="client-secret" \ + default_role="default" + +# Create role +vault write auth/oidc/role/default \ + bound_audiences="vault-client-id" \ + allowed_redirect_uris="http://localhost:8250/oidc/callback" \ + user_claim="email" \ + policies="user-policy" + +# Login +vault login -method=oidc +``` + +### AWS IAM + +```bash +# Enable AWS auth +vault auth enable aws + +# Configure +vault write auth/aws/config/client \ + access_key="ACCESS_KEY" \ + secret_key="SECRET_KEY" + +# Create IAM role +vault write auth/aws/role/my-role \ + auth_type=iam \ + bound_iam_principal_arn="arn:aws:iam::123456789:role/my-role" \ + policies=aws-policy +``` + +--- + +## Common Patterns + +### Trusted Broker Pattern + +Securely distribute initial credentials using response wrapping: + +```bash +# Wrap a secret ID for 60 seconds +vault write -wrap-ttl=60s -f auth/approle/role/my-app/secret-id + +# Unwrap on the target machine (single use) +vault unwrap +``` + +### Multi-Method Authentication + +```bash +# Enable multiple methods with mount paths +vault auth enable -path=okta oidc +vault auth enable -path=github-actions jwt + +# Users can authenticate via either +vault login -method=oidc -path=okta +``` + +--- + +## Best Practices + +- **Use AppRole** for machine-to-machine with short-lived secret IDs +- **Use Kubernetes auth** for K8s workloads (avoid mounting service account tokens) +- **Use OIDC** for human users (integrates with existing SSO) +- **Bind to specific identities** - never use wildcards in IAM principal ARNs +- **Set short TTLs** - 1h or less for tokens + +--- + +For detailed configurations including Azure, GCP, LDAP, GitHub, and advanced patterns, see [references/auth-methods.md](references/auth-methods.md). diff --git a/vault/authentication/skills/auth-methods/references/auth-methods.md b/vault/authentication/skills/auth-methods/references/auth-methods.md new file mode 100644 index 0000000..1944734 --- /dev/null +++ b/vault/authentication/skills/auth-methods/references/auth-methods.md @@ -0,0 +1,574 @@ +--- +name: vault-auth-methods +description: Detailed configuration for Vault authentication methods including AppRole, Kubernetes, OIDC, AWS, Azure, GCP, and LDAP +--- + +# Vault Authentication Methods + +This reference provides detailed configuration for Vault's authentication methods. + +--- + +## Overview + +Authentication methods verify user or machine identity before granting access. After successful authentication, Vault issues a **token** tied to policies that define permissions. + +### Authentication Flow + +1. Client presents credentials to an auth method endpoint +2. Vault validates credentials with the identity provider +3. Vault issues a token with attached policies +4. Client uses token for subsequent API calls + +--- + +## AppRole (Recommended for Applications) + +AppRole is designed for machine-to-machine authentication with two-factor security (RoleID + SecretID). + +### Enable and Configure AppRole + +```bash +# Enable AppRole auth +vault auth enable approle + +# Create a role with policies and TTL +vault write auth/approle/role/my-app \ + token_policies="app-policy" \ + token_ttl=1h \ + token_max_ttl=4h \ + secret_id_ttl=10m \ + secret_id_num_uses=1 +``` + +### Get Credentials + +```bash +# Get RoleID (can be embedded in configuration) +vault read auth/approle/role/my-app/role-id + +# Generate SecretID (deliver securely, often via response wrapping) +vault write -f auth/approle/role/my-app/secret-id + +# Response wrapping for secure SecretID delivery +vault write -wrap-ttl=60s -f auth/approle/role/my-app/secret-id +``` + +### AppRole Application Login + +```bash +# CLI login +vault write auth/approle/login \ + role_id="" \ + secret_id="" + +# API login +curl --request POST \ + --data '{"role_id": "", "secret_id": ""}' \ + $VAULT_ADDR/v1/auth/approle/login +``` + +### Best Practices + +- Use `secret_id_num_uses=1` for single-use SecretIDs +- Deliver SecretID via response wrapping +- Use short TTLs and implement token renewal +- Separate RoleID (less sensitive) from SecretID (highly sensitive) + +--- + +## AppRole Trusted Broker Pattern (CI/CD) + +> **Core Principle**: RoleID and SecretID should ONLY ever be together on the end-user system that consumes the secret. + +### Architecture + +```text +┌─────────┐ ┌─────────┐ ┌─────────┐ +│ CI │ 1.Auth ──────────► │ Vault │ ◄──── 8.Auth ─────│ Runner │ +│ Worker │ ◄──── 2.Token ──── │ │ ──── 9.Token ───► │Container│ +│(Broker) │ 3.Wrapped SecretID │ │ ◄── 10.Get Secret │ │ +│ │ ◄──── 4.Return ─── │ │ ──── 11.Secret ──►│ │ +│ │ 5.Spawn+Pass ─────────────────────────────────────► │ +└─────────┘ └─────────┘ 6.Unwrap └─────────┘ + 7.SecretID +``` + +### Workflow Steps + +1. CI Worker authenticates to Vault (using its own identity) +2. Vault returns token with limited policy +3. Worker requests **wrapped** SecretID for the runner role +4. Vault returns wrapped SecretID (single-use wrapping token) +5. Worker spawns runner container, passes wrapped SecretID as env var +6. Runner unwraps the SecretID +7. Runner uses RoleID + SecretID to authenticate +8. Vault returns token with runner-specific policies +9. Runner retrieves secrets + +### Worker Policy (Trusted Broker) + +```hcl +# Worker can only create wrapped SecretIDs, not access secrets directly +path "auth/approle/role/+/secret*" { + capabilities = ["create", "read", "update"] + min_wrapping_ttl = "100s" + max_wrapping_ttl = "300s" +} +``` + +### Runner Policy (Scoped to Specific Secrets) + +```hcl +path "secret/data/{{identity.entity.metadata.app}}/*" { + capabilities = ["read"] +} +``` + +### Jenkins Pipeline Example + +```groovy +pipeline { + environment { + WRAPPED_SID = sh( + returnStdout: true, + script: ''' + curl --silent \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "X-Vault-Wrap-TTL: 300s" \ + --request POST \ + ${VAULT_ADDR}/v1/auth/approle/role/${JOB_NAME}/secret-id \ + | jq -r '.wrap_info.token' + ''' + ).trim() + } + stages { + stage('Run') { + steps { + // Pass wrapped SecretID to container + sh 'docker run -e WRAPPED_SID=${WRAPPED_SID} myapp:latest' + } + } + } +} +``` + +### Security Configurations + +| Setting | Recommended Value | Purpose | +| --------- | ------------------- | --------- | +| `secret_id_num_uses` | 1 | Single-use SecretIDs | +| `secret_id_ttl` | 120s | Short-lived SecretIDs | +| `secret_id_bound_cidrs` | Network range | Restrict login location | +| `wrap_ttl` | 100-300s | Response wrapping for delivery | + +### Anti-Patterns to Avoid + +| Anti-Pattern | Risk | Correct Approach | +| -------------- | ------ | ------------------ | +| CI Worker retrieves secrets directly | Worker has access to many secrets | Use trusted broker pattern | +| Passing RoleID AND SecretID together | Full auth credentials exposed | Separate delivery mechanisms | +| Passing Vault tokens to runners | Token can access all permitted secrets | Use AppRole per-runner | +| Storing SecretID in CI/CD config | Credential exposure | Generate per-run with wrapping | + +### Security Monitoring + +Alert on these conditions in audit logs: + +- Wrapped SecretID requested when no job is running +- Unwrap attempt fails (token already used = potential compromise) +- SecretID generated without corresponding job execution + +--- + +## Kubernetes Authentication + +Authenticates Kubernetes pods using their ServiceAccount tokens. + +### Enable and Configure Kubernetes Auth + +```bash +# Enable Kubernetes auth +vault auth enable kubernetes + +# Configure Vault to communicate with Kubernetes API +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.default.svc:443" \ + kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt + +# For external Vault accessing K8s cluster +vault write auth/kubernetes/config \ + kubernetes_host="https://cluster-api.example.com:6443" \ + kubernetes_ca_cert=@ca.crt \ + token_reviewer_jwt=@reviewer-jwt.txt +``` + +### Handling Kubernetes 1.21+ Short-Lived Tokens + +Kubernetes 1.21+ uses short-lived bound service account tokens. Configure one of these options: + +```bash +# Option 1: Use local token reviewer JWT (recommended when Vault runs in K8s) +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.default.svc:443" \ + kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt + +# Option 2: Disable issuer validation (for cross-cluster auth) +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.example.com:6443" \ + kubernetes_ca_cert=@ca.crt \ + disable_iss_validation=true + +# Option 3: Use explicit issuer (for specific OIDC issuers) +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.example.com:6443" \ + issuer="https://kubernetes.default.svc.cluster.local" +``` + +### Use Annotations as Alias Metadata + +Enable templated policies using ServiceAccount metadata: + +```bash +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.default.svc:443" \ + use_annotations_as_alias_metadata=true +``` + +This allows policies like: + +```hcl +path "secret/data/{{identity.entity.aliases.auth_kubernetes.metadata.service_account_namespace}}/*" { + capabilities = ["read"] +} +``` + +### Create Roles + +```bash +# Bind role to specific ServiceAccount and namespace +vault write auth/kubernetes/role/my-app \ + bound_service_account_names=my-app-sa \ + bound_service_account_namespaces=default,staging \ + policies=app-policy \ + ttl=1h \ + audience=vault + +# Wildcard bindings +vault write auth/kubernetes/role/any-app \ + bound_service_account_names="*" \ + bound_service_account_namespaces=apps \ + policies=read-only +``` + +### Pod Authentication + +Pods authenticate using their mounted ServiceAccount token: + +```bash +# From within pod +JWT=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) +curl --request POST \ + --data "{\"jwt\": \"$JWT\", \"role\": \"my-app\"}" \ + $VAULT_ADDR/v1/auth/kubernetes/login +``` + +### Kubernetes RBAC Requirements + +```yaml +# ClusterRoleBinding for token review +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: vault-tokenreview +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: system:auth-delegator +subjects: +- kind: ServiceAccount + name: vault + namespace: vault +``` + +--- + +## JWT/OIDC Authentication + +Authenticate using JSON Web Tokens from OIDC providers (Okta, Auth0, Azure AD, Google). + +### OIDC Configuration (Interactive) + +```bash +# Enable OIDC +vault auth enable oidc + +# Configure with OIDC provider +vault write auth/oidc/config \ + oidc_discovery_url="https://accounts.google.com" \ + oidc_client_id="" \ + oidc_client_secret="" \ + default_role="default" + +# Create role with claims mapping +vault write auth/oidc/role/default \ + allowed_redirect_uris="http://localhost:8250/oidc/callback" \ + allowed_redirect_uris="https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback" \ + user_claim="email" \ + policies="default" \ + oidc_scopes="openid,email,profile" \ + bound_claims='{"groups": ["engineering"]}' +``` + +### JWT Configuration (Non-Interactive) + +```bash +# For JWT tokens (CI/CD, service accounts) +vault auth enable jwt + +vault write auth/jwt/config \ + oidc_discovery_url="https://token.actions.githubusercontent.com" \ + bound_issuer="https://token.actions.githubusercontent.com" + +# GitHub Actions role +vault write auth/jwt/role/github-actions \ + role_type="jwt" \ + user_claim="actor" \ + bound_claims_type="glob" \ + bound_claims='{"repository": "myorg/*"}' \ + policies="ci-policy" \ + ttl=15m +``` + +### OIDC Login + +```bash +# Interactive browser login +vault login -method=oidc + +# With specific role +vault login -method=oidc role=admin +``` + +--- + +## AWS IAM Authentication + +Authenticate EC2 instances or IAM principals using AWS credentials. + +### Enable and Configure AWS Auth + +```bash +vault auth enable aws + +# Configure AWS credentials for Vault +vault write auth/aws/config/client \ + access_key= \ + secret_key= \ + region=us-east-1 + +# For STS with assumed role +vault write auth/aws/config/sts/account-id \ + sts_role=arn:aws:iam::ACCOUNT:role/VaultVerifyRole +``` + +### IAM Role (Recommended) + +```bash +# Create IAM auth role +vault write auth/aws/role/web-app \ + auth_type=iam \ + bound_iam_principal_arn="arn:aws:iam::ACCOUNT:role/WebAppRole" \ + policies=app-policy \ + ttl=1h +``` + +### EC2 Role + +```bash +vault write auth/aws/role/ec2-app \ + auth_type=ec2 \ + bound_ami_id="ami-12345678" \ + bound_vpc_id="vpc-abcdef12" \ + policies=app-policy +``` + +### AWS Application Login + +```bash +# IAM auth from AWS environment +vault login -method=aws role=web-app + +# Using explicit credentials +vault write auth/aws/login \ + role=web-app \ + iam_http_request_method=POST \ + iam_request_url= \ + iam_request_body= \ + iam_request_headers= +``` + +--- + +## Azure Authentication + +Authenticate Azure VMs and managed identities. + +### Enable and Configure Azure Auth + +```bash +vault auth enable azure + +vault write auth/azure/config \ + tenant_id="" \ + resource="https://management.azure.com/" \ + client_id="" \ + client_secret="" +``` + +### Create Role + +```bash +vault write auth/azure/role/web-app \ + policies="app-policy" \ + bound_subscription_ids="" \ + bound_resource_groups="my-rg" \ + bound_service_principal_ids="" +``` + +--- + +## GCP Authentication + +Authenticate GCP service accounts and compute instances. + +### Enable and Configure GCP Auth + +```bash +vault auth enable gcp + +vault write auth/gcp/config \ + credentials=@gcp-credentials.json +``` + +### IAM Role + +```bash +vault write auth/gcp/role/web-app \ + type="iam" \ + policies="app-policy" \ + bound_service_accounts="sa@project.iam.gserviceaccount.com" +``` + +### GCE Role + +```bash +vault write auth/gcp/role/gce-app \ + type="gce" \ + policies="app-policy" \ + bound_projects="my-project" \ + bound_zones="us-central1-a" \ + bound_labels="env:prod" +``` + +--- + +## LDAP Authentication + +Authenticate against LDAP/Active Directory. + +### Enable and Configure LDAP Auth + +```bash +vault auth enable ldap + +vault write auth/ldap/config \ + url="ldaps://ldap.example.com:636" \ + binddn="cn=vault,ou=services,dc=example,dc=com" \ + bindpass="" \ + userdn="ou=users,dc=example,dc=com" \ + userattr="sAMAccountName" \ + groupdn="ou=groups,dc=example,dc=com" \ + groupattr="cn" \ + insecure_tls=false \ + starttls=false +``` + +### Map Groups to Policies + +```bash +# Map LDAP group to Vault policies +vault write auth/ldap/groups/engineering \ + policies="engineering-policy,read-only" + +vault write auth/ldap/groups/admins \ + policies="admin-policy" +``` + +### Login + +```bash +vault login -method=ldap username=jdoe +# Prompts for password +``` + +--- + +## Token Authentication + +Direct token authentication (often used after other methods issue tokens). + +### Create Tokens + +```bash +# Create token with policies +vault token create -policy=app-policy -ttl=1h + +# Create orphan token (no parent) +vault token create -orphan -policy=app-policy + +# Create periodic token (renewable indefinitely) +vault token create -policy=app-policy -period=24h + +# Create batch token (lightweight, no storage) +vault token create -type=batch -policy=app-policy +``` + +### Token Types + +| Type | Storage | Renewal | Use Case | +| ------ | --------- | --------- | ---------- | +| **Service** | Yes | Yes | Long-running apps | +| **Batch** | No | No | Short-lived, high-volume | +| **Periodic** | Yes | Indefinite | Services needing long uptime | + +--- + +## Comparison Table + +| Method | Use Case | Security Level | Complexity | +| -------- | ---------- | ---------------- | ------------ | +| **AppRole** | Applications, CI/CD | High | Medium | +| **Kubernetes** | K8s pods | High | Medium | +| **JWT/OIDC** | SSO, CI/CD tokens | High | Medium | +| **AWS** | AWS workloads | High | Low | +| **Azure** | Azure workloads | High | Low | +| **GCP** | GCP workloads | High | Low | +| **LDAP** | Enterprise users | Medium | Medium | +| **Token** | Direct auth | Varies | Low | + +--- + +## Additional Resources + +- [Auth Methods Documentation](https://developer.hashicorp.com/vault/docs/auth) +- [AppRole Tutorial](https://developer.hashicorp.com/vault/tutorials/auth-methods/approle) +- [Kubernetes Auth Tutorial](https://developer.hashicorp.com/vault/tutorials/kubernetes/kubernetes-sidecar) + +--- + +## Related + +- [Policies](policies.md) - Define permissions for authenticated identities +- [Kubernetes Integration](kubernetes.md) - K8s-specific auth and secret delivery +- [Vault Agent](vault-agent.md) - Auto-auth configuration for applications diff --git a/vault/authentication/skills/identity-system/SKILL.md b/vault/authentication/skills/identity-system/SKILL.md new file mode 100644 index 0000000..a823640 --- /dev/null +++ b/vault/authentication/skills/identity-system/SKILL.md @@ -0,0 +1,239 @@ +--- +name: identity-system +description: Use when working with Vault identity, entities, aliases, groups, identity tokens, or OIDC provider configuration. Covers unified identity management and SSO patterns. +--- + +# Identity System + +Manage Vault's identity secrets engine for unified identity, groups, and OIDC provider capabilities. + +## Reference + +- [Identity Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/identity) +- [Identity Concepts](https://developer.hashicorp.com/vault/docs/concepts/identity) +- [OIDC Provider](https://developer.hashicorp.com/vault/docs/secrets/identity/oidc-provider) +- For complete API examples and advanced patterns, see [references/identity-system.md](references/identity-system.md) + +## Overview + +The Identity secrets engine provides: +- **Entities**: Represent users/machines across multiple auth methods +- **Aliases**: Map auth method logins to entities +- **Groups**: Organize entities for policy assignment +- **Identity Tokens**: Issue OIDC-compliant tokens +- **OIDC Provider**: Act as an identity provider for SSO + +## Entities + +An entity represents a single person or machine: + +```bash +# Create entity +vault write identity/entity \ + name="alice" \ + policies="developer" \ + metadata=team="platform" + +# Read entity +vault read identity/entity/name/alice + +# List entities +vault list identity/entity/name +``` + +### Entity Aliases + +Map authentication sources to entities: + +```bash +# Create alias linking LDAP login to entity +vault write identity/entity-alias \ + name="alice@corp.com" \ + canonical_id="entity-uuid-here" \ + mount_accessor="auth_ldap_abc123" + +# When alice logs in via LDAP, her token inherits entity policies +``` + +## Groups + +### Internal Groups (Manual Membership) + +```bash +# Create internal group +vault write identity/group \ + name="platform-team" \ + policies="platform-policy" \ + member_entity_ids="entity-uuid-1,entity-uuid-2" + +# Add entity to group +vault write identity/group/name/platform-team \ + member_entity_ids="entity-uuid-1,entity-uuid-2,entity-uuid-3" +``` + +### External Groups (Auth Method Controlled) + +```bash +# Create external group +vault write identity/group \ + name="ldap-admins" \ + type="external" \ + policies="admin-policy" + +# Create group alias mapping LDAP group +vault write identity/group-alias \ + name="cn=admins,ou=groups,dc=corp,dc=com" \ + mount_accessor="auth_ldap_abc123" \ + canonical_id="group-uuid-here" + +# When LDAP user in "admins" group authenticates, they inherit policies +``` + +## Identity Hierarchy + +``` +┌─────────────────────────────────────────────────────────┐ +│ Entity: alice │ +│ policies: [developer] │ +├─────────────────────┬───────────────────────────────────┤ +│ Alias: alice@ldap │ Alias: alice-github │ +│ mount: auth/ldap │ mount: auth/github │ +└─────────────────────┴───────────────────────────────────┘ + │ + ▼ + ┌────────────────────────┐ + │ Group: platform-team │ + │ policies: [platform] │ + └────────────────────────┘ +``` + +## Identity Tokens (OIDC) + +Issue OIDC-compliant identity tokens: + +```bash +# Create OIDC key +vault write identity/oidc/key/my-key \ + algorithm="RS256" \ + rotation_period="24h" + +# Create role +vault write identity/oidc/role/my-role \ + key="my-key" \ + template='{"groups":{{identity.entity.groups.names}}}' + +# Generate token +vault read identity/oidc/token/my-role +``` + +### Token Template + +Customize claims in identity tokens: + +```json +{ + "sub": "{{identity.entity.id}}", + "name": "{{identity.entity.name}}", + "groups": {{identity.entity.groups.names}}, + "email": "{{identity.entity.metadata.email}}" +} +``` + +## OIDC Provider + +Configure Vault as an OIDC identity provider: + +```bash +# Create provider +vault write identity/oidc/provider/my-provider \ + issuer="https://vault.example.com" \ + allowed_client_ids="client-id-1,client-id-2" + +# Create client +vault write identity/oidc/client/my-app \ + redirect_uris="https://app.example.com/callback" \ + assignments="allow_all" + +# Create scope +vault write identity/oidc/scope/profile \ + template='{"name":"{{identity.entity.name}}"}' +``` + +### Discovery Endpoint + +```bash +# OIDC discovery +curl $VAULT_ADDR/v1/identity/oidc/provider/my-provider/.well-known/openid-configuration +``` + +## Lookup Operations + +```bash +# Lookup entity by ID +vault read identity/entity/id/entity-uuid + +# Lookup entity by name +vault read identity/entity/name/alice + +# Lookup entity by alias +vault write identity/lookup/entity \ + alias_name="alice@corp.com" \ + alias_mount_accessor="auth_ldap_abc123" + +# Lookup group by name +vault read identity/group/name/platform-team +``` + +## Merge Entities + +Combine duplicate entities: + +```bash +vault write identity/entity/merge \ + from_entity_ids="entity-uuid-1,entity-uuid-2" \ + to_entity_id="entity-uuid-primary" +``` + +## API Examples + +### Create Entity + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"name":"alice","policies":["developer"]}' \ + $VAULT_ADDR/v1/identity/entity +``` + +### List Groups + +```bash +curl -X LIST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + $VAULT_ADDR/v1/identity/group/name +``` + +## Common Patterns + +### SSO Integration + +1. Configure Vault OIDC provider +2. Register applications as OIDC clients +3. Applications redirect to Vault for authentication +4. Vault issues identity tokens with entity claims + +### Cross-Auth Method Identity + +1. Create entity for each user +2. Create aliases for each auth method (LDAP, GitHub, OIDC, etc.) +3. Assign policies to entities or groups +4. Users get consistent access regardless of login method + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Entity policies not applied | Alias not linked | Verify entity-alias exists | +| Group policies missing | Entity not in group | Check member_entity_ids | +| OIDC token empty claims | Template syntax error | Validate template JSON | +| External group not working | Mount accessor wrong | Get accessor from auth/method/tune | diff --git a/vault/authentication/skills/identity-system/references/identity-system.md b/vault/authentication/skills/identity-system/references/identity-system.md new file mode 100644 index 0000000..cc082e1 --- /dev/null +++ b/vault/authentication/skills/identity-system/references/identity-system.md @@ -0,0 +1,120 @@ +--- +name: identity-system +description: Reference documentation for Vault identity secrets engine, entities, groups, and OIDC provider. +--- + +# Identity System Reference + +## Core Components + +| Component | Description | +|-----------|-------------| +| Entity | Represents a user or machine across auth methods | +| Alias | Maps auth method login to an entity | +| Group (Internal) | Manual entity membership | +| Group (External) | Auth method controlled membership | +| Identity Token | OIDC-compliant JWT | +| OIDC Provider | Full OIDC IdP functionality | + +## Entity API + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/identity/entity` | Create entity | +| GET | `/identity/entity/id/:id` | Read by ID | +| GET | `/identity/entity/name/:name` | Read by name | +| LIST | `/identity/entity/name` | List entities | +| DELETE | `/identity/entity/id/:id` | Delete entity | +| POST | `/identity/entity/merge` | Merge entities | + +## Alias API + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/identity/entity-alias` | Create alias | +| GET | `/identity/entity-alias/id/:id` | Read alias | +| LIST | `/identity/entity-alias/id` | List aliases | +| DELETE | `/identity/entity-alias/id/:id` | Delete alias | + +## Group API + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/identity/group` | Create group | +| GET | `/identity/group/id/:id` | Read by ID | +| GET | `/identity/group/name/:name` | Read by name | +| LIST | `/identity/group/name` | List groups | + +## Group Types + +### Internal Groups + +- Membership controlled by Vault operators +- Entities added via `member_entity_ids` +- Use for cross-auth-method grouping + +### External Groups + +- Membership controlled by auth method +- Linked via group alias to external group +- Automatically synced on authentication + +## Identity Token (OIDC) Flow + +1. Create OIDC key with signing algorithm +2. Create role with template and key reference +3. Entity authenticates and reads token +4. Token contains claims from template + +## OIDC Key Configuration + +| Option | Description | +|--------|-------------| +| `algorithm` | RS256, RS384, RS512, ES256, ES384, ES512, EdDSA | +| `rotation_period` | How often to rotate signing key | +| `verification_ttl` | How long old keys remain valid | + +## Template Variables + +```json +{ + "sub": "{{identity.entity.id}}", + "name": "{{identity.entity.name}}", + "groups": {{identity.entity.groups.names}}, + "metadata": "{{identity.entity.metadata}}" +} +``` + +Available variables: +- `identity.entity.id` +- `identity.entity.name` +- `identity.entity.metadata.` +- `identity.entity.aliases` +- `identity.entity.groups.ids` +- `identity.entity.groups.names` + +## Lookup API + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/identity/lookup/entity` | Lookup entity by criteria | +| POST | `/identity/lookup/group` | Lookup group by criteria | + +## Mount Accessor + +Required for alias creation: + +```bash +# Get accessor for auth method +vault auth list -detailed +# or +vault read sys/auth/ldap | grep accessor +``` + +## Policy Inheritance + +Entities and groups can have policies attached: +1. Token inherits entity policies +2. Token inherits group policies (all groups entity belongs to) +3. Policies are additive to token's existing policies +4. Computed dynamically at request time diff --git a/vault/authentication/skills/policies/SKILL.md b/vault/authentication/skills/policies/SKILL.md new file mode 100644 index 0000000..97bfc77 --- /dev/null +++ b/vault/authentication/skills/policies/SKILL.md @@ -0,0 +1,221 @@ +--- +name: policies +description: Write Vault HCL policies for access control. Use when asked about ACL policies, policy syntax, capabilities (read, write, list, delete, sudo), templated policies, path patterns, Sentinel policies (Enterprise), or troubleshooting permission denied errors. +--- + +# Vault Policies + +Policies define the permissions granted to tokens and entities. Written in HCL, they specify which paths can be accessed and what operations (capabilities) are allowed. Policies are the foundation of Vault's security model. + +## Reference + +- [Vault Policies Documentation](https://developer.hashicorp.com/vault/docs/concepts/policies) +- For complete policy syntax and advanced templating patterns, see [references/policies.md](references/policies.md) + +--- + +## When to Use This Skill + +- **Access control**: Define what secrets users/apps can access +- **Least privilege**: Create minimal policies for specific use cases +- **Templated policies**: Dynamic paths based on identity +- **Policy debugging**: Troubleshoot "permission denied" errors +- **Sentinel policies**: Advanced policy-as-code (Enterprise) + +--- + +## Policy Capabilities + +| Capability | Description | +|------------|-------------| +| `create` | Create new data at a path | +| `read` | Read data from a path | +| `update` | Modify existing data | +| `delete` | Delete data | +| `list` | List paths (directory-like listing) | +| `sudo` | Override deny or access root-protected paths | +| `deny` | Explicitly deny access (overrides everything) | + +--- + +## Quick Reference + +### Basic Policy Structure + +```hcl +# Allow read access to application secrets +path "secret/data/myapp/*" { + capabilities = ["read", "list"] +} + +# Allow dynamic database credentials +path "database/creds/readonly" { + capabilities = ["read"] +} + +# Deny access to admin secrets +path "secret/data/admin/*" { + capabilities = ["deny"] +} +``` + +### KV v2 Policy Paths + +KV v2 requires `/data/` in the path: + +```hcl +# Read secrets (note: /data/ prefix for actual secrets) +path "secret/data/myapp/*" { + capabilities = ["read"] +} + +# List secrets (uses /metadata/ prefix) +path "secret/metadata/myapp/*" { + capabilities = ["list"] +} + +# Full access to KV v2 +path "secret/data/myapp/*" { + capabilities = ["create", "read", "update", "delete"] +} +path "secret/metadata/myapp/*" { + capabilities = ["list", "read", "delete"] +} +``` + +### Templated Policies + +Use identity information for dynamic paths: + +```hcl +# Each user gets their own secret namespace +path "secret/data/users/{{identity.entity.name}}/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Team-based access using groups +path "secret/data/teams/{{identity.groups.names}}/*" { + capabilities = ["read", "list"] +} +``` + +--- + +## Common Patterns + +### Application Policy + +```hcl +# Typical application policy +path "secret/data/myapp/config" { + capabilities = ["read"] +} + +path "database/creds/myapp-readonly" { + capabilities = ["read"] +} + +path "auth/token/renew-self" { + capabilities = ["update"] +} + +path "auth/token/lookup-self" { + capabilities = ["read"] +} +``` + +### Operator Policy + +```hcl +# Operations team policy +path "sys/health" { + capabilities = ["read"] +} + +path "sys/policies/*" { + capabilities = ["read", "list"] +} + +path "auth/*" { + capabilities = ["read", "list"] +} + +# Seal/unseal requires sudo +path "sys/seal" { + capabilities = ["sudo", "update"] +} +``` + +### CI/CD Pipeline Policy + +```hcl +# Read secrets for deployment +path "secret/data/deployment/*" { + capabilities = ["read"] +} + +# Generate cloud credentials +path "aws/creds/deploy" { + capabilities = ["read"] +} + +# No write access to production secrets +path "secret/data/production/*" { + capabilities = ["deny"] +} +``` + +--- + +## Policy Management + +```bash +# Create/update policy from file +vault policy write app-policy policy.hcl + +# List policies +vault policy list + +# Read policy +vault policy read app-policy + +# Delete policy +vault policy delete app-policy + +# Check token capabilities +vault token capabilities secret/data/myapp +``` + +--- + +## Debugging Policies + +```bash +# Check current token's policies +vault token lookup + +# Test capabilities for a specific path +vault token capabilities secret/data/myapp/config + +# Enable audit logging to see denied requests +vault audit enable file file_path=/var/log/vault-audit.log +``` + +Common issues: +- **KV v2**: Policy path needs `/data/` but CLI doesn't (`vault kv get secret/myapp`) +- **Missing `list`**: Need `list` capability to see path contents +- **Glob patterns**: `*` matches within a path segment, use explicit paths when possible + +--- + +## Best Practices + +- **Least privilege**: Start with minimal permissions, add as needed +- **Use templated policies** for user/team-specific paths +- **Separate policies by use case** (app, operator, admin) +- **Test policies** before applying to production +- **Enable audit logging** to track access patterns + +--- + +For advanced patterns including Sentinel policies (Enterprise), response wrapping policies, and CI/CD integration, see [references/policies.md](references/policies.md). diff --git a/vault/authentication/skills/policies/references/policies.md b/vault/authentication/skills/policies/references/policies.md new file mode 100644 index 0000000..f73314a --- /dev/null +++ b/vault/authentication/skills/policies/references/policies.md @@ -0,0 +1,609 @@ +--- +name: vault-policies +description: Detailed guidance on writing and managing Vault ACL policies and Sentinel policies +--- + +# Vault Policies + +This reference provides detailed guidance on writing and managing Vault policies. + +--- + +## Overview + +Policies define **what actions** are allowed on **which paths**. They are written in HCL (HashiCorp Configuration Language) and attached to tokens via authentication. + +### Policy Evaluation + +- **Default deny**: If no policy grants access, the operation is denied +- **Additive**: Multiple policies combine permissions (most permissive wins) +- **Root token**: Bypasses all policy checks (avoid in production) + +--- + +## Policy Syntax + +### Basic Structure + +```hcl +# Comment describing the policy +path "" { + capabilities = ["", ...] +} +``` + +### Capabilities + +| Capability | HTTP Verb | Description | +| ------------ | ----------- | ------------- | +| `create` | POST | Create new data | +| `read` | GET | Read data | +| `update` | POST/PUT | Modify existing data | +| `delete` | DELETE | Delete data | +| `list` | LIST | List keys at path | +| `sudo` | - | Access protected endpoints | +| `deny` | - | Explicitly deny (overrides all) | + +--- + +## Path Patterns + +> **Important for KV v2**: Policy paths must include `/data/` for secrets access. +> For example, if your secret is at `secret/myapp/config`, the policy path is `secret/data/myapp/config`. +> The CLI hides this, but policies require the full path. + +### Exact Match + +```hcl +# Only matches exactly secret/data/myapp/config +path "secret/data/myapp/config" { + capabilities = ["read"] +} +``` + +### Glob Patterns + +```hcl +# Matches any immediate child +path "secret/data/myapp/*" { + capabilities = ["read", "list"] +} + +# Matches all descendants (recursive) +path "secret/data/myapp/+" { + capabilities = ["read"] +} +``` + +### Segment Wildcards + +```hcl +# + matches exactly one path segment +path "secret/data/+/config" { + capabilities = ["read"] +} +# Matches: secret/data/app1/config, secret/data/app2/config +# Not: secret/data/app1/nested/config +``` + +--- + +## Common Policy Examples + +### Application Read-Only + +```hcl +# Read application secrets +path "secret/data/myapp/*" { + capabilities = ["read", "list"] +} + +# Allow token self-management +path "auth/token/renew-self" { + capabilities = ["update"] +} + +path "auth/token/lookup-self" { + capabilities = ["read"] +} +``` + +### Application Read-Write + +```hcl +path "secret/data/myapp/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "secret/metadata/myapp/*" { + capabilities = ["read", "list", "delete"] +} +``` + +### Database Credentials + +```hcl +# Generate dynamic database credentials +path "database/creds/readonly" { + capabilities = ["read"] +} + +# Manage leases +path "sys/leases/renew" { + capabilities = ["update"] +} + +path "sys/leases/revoke" { + capabilities = ["update"] +} +``` + +### AWS Credentials + +```hcl +path "aws/creds/deploy" { + capabilities = ["read"] +} + +path "aws/sts/deploy" { + capabilities = ["read"] +} +``` + +### PKI Certificate Issuance + +```hcl +# Issue certificates +path "pki_int/issue/web-servers" { + capabilities = ["create", "update"] +} + +# Read CA certificate +path "pki_int/ca/pem" { + capabilities = ["read"] +} + +path "pki_int/cert/ca" { + capabilities = ["read"] +} +``` + +### Transit Encryption + +```hcl +# Encrypt data +path "transit/encrypt/my-key" { + capabilities = ["update"] +} + +# Decrypt data +path "transit/decrypt/my-key" { + capabilities = ["update"] +} +``` + +### Admin Policy + +```hcl +# Full access to secrets +path "secret/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Manage policies +path "sys/policies/acl/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Manage auth methods +path "sys/auth/*" { + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# Manage secrets engines +path "sys/mounts/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Access audit logs +path "sys/audit/*" { + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} +``` + +--- + +## Templated Policies + +Use identity information to create dynamic policies. + +### Entity Templates + +```hcl +# Each entity gets their own path +path "secret/data/users/{{identity.entity.id}}/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# Use entity name +path "secret/data/teams/{{identity.entity.name}}/*" { + capabilities = ["read", "list"] +} +``` + +### Entity Metadata + +```hcl +# Use custom metadata +path "secret/data/projects/{{identity.entity.metadata.project}}/*" { + capabilities = ["read"] +} +``` + +### Group Templates + +```hcl +# Group-based access +path "secret/data/groups/{{identity.groups.names}}/*" { + capabilities = ["read", "list"] +} +``` + +### Auth Method Templates + +```hcl +# Access based on auth method alias +path "secret/data/{{identity.entity.aliases.auth_kubernetes.metadata.service_account_namespace}}/*" { + capabilities = ["read"] +} +``` + +--- + +## Required Parameters + +Restrict which keys can be set. + +```hcl +path "secret/data/restricted/*" { + capabilities = ["create", "update"] + required_parameters = ["reason", "requester"] +} +``` + +--- + +## Allowed Parameters + +Limit which keys can be written. + +```hcl +path "secret/data/config/*" { + capabilities = ["create", "update"] + allowed_parameters = { + "data" = ["username", "password", "api_key"] + } +} +``` + +--- + +## Denied Parameters + +Prevent specific keys from being set. + +```hcl +path "secret/data/*" { + capabilities = ["create", "update"] + denied_parameters = { + "data" = ["admin_password", "root_key"] + } +} +``` + +> **Note**: Parameter constraints (`required_parameters`, `allowed_parameters`, `denied_parameters`) +> only apply to `create` and `update` operations. They cannot restrict `read` access to specific fields. + +--- + +## Min/Max Wrapping TTL + +Control response wrapping to ensure secrets are consumed securely. + +```hcl +path "secret/data/sensitive/*" { + capabilities = ["read"] + min_wrapping_ttl = "1m" + max_wrapping_ttl = "10m" +} +``` + +### Response Wrapping Best Practices + +| Setting | Purpose | Recommended Value | +| -------------------- | --------------------------- | ----------------- | +| `min_wrapping_ttl` | Prevent unwrapped responses | 60s or higher | +| `max_wrapping_ttl` | Limit exposure window | 10-15 minutes max | + +```hcl +# Force wrapping for AppRole secret_id retrieval (Trusted Broker pattern) +path "auth/approle/role/+/secret-id" { + capabilities = ["update"] + min_wrapping_ttl = "60s" + max_wrapping_ttl = "300s" +} +``` + +--- + +## CI/CD Pipeline Policies + +### Trusted Broker Pattern Policies + +Based on the AppRole Trusted Broker architecture pattern: + +#### Controller/Orchestrator Policy + +The CI/CD controller (Jenkins master, GitLab coordinator) needs: + +```hcl +# Policy: cicd-controller +# Purpose: Allow CI controller to fetch wrapped secret_ids for jobs + +# Read role-id (public, can be in config) +path "auth/approle/role/+/role-id" { + capabilities = ["read"] +} + +# Generate wrapped secret-id (MUST be wrapped) +path "auth/approle/role/+/secret-id" { + capabilities = ["update"] + min_wrapping_ttl = "60s" + max_wrapping_ttl = "300s" +} + +# Lookup wrapping token info (for validation) +path "sys/wrapping/lookup" { + capabilities = ["update"] +} +``` + +#### Worker/Runner Policy + +Individual build agents get limited, wrapped credentials: + +```hcl +# Policy: cicd-worker +# Purpose: Application-specific access for build jobs + +# Read application secrets +path "secret/data/apps/{{identity.entity.metadata.app_name}}/*" { + capabilities = ["read"] +} + +# Get dynamic database credentials for testing +path "database/creds/ci-readonly" { + capabilities = ["read"] +} + +# Manage own leases +path "sys/leases/renew-self" { + capabilities = ["update"] +} + +path "auth/token/renew-self" { + capabilities = ["update"] +} +``` + +#### Jenkins Integration Example + +```hcl +# Policy: jenkins-master +# Jenkins master distributes credentials to agents + +path "auth/approle/role/jenkins-agent-*/secret-id" { + capabilities = ["update"] + min_wrapping_ttl = "120s" + max_wrapping_ttl = "300s" +} + +path "auth/approle/role/jenkins-agent-*/role-id" { + capabilities = ["read"] +} + +# Token introspection for cleanup +path "auth/token/lookup-accessor" { + capabilities = ["update"] +} + +path "auth/token/revoke-accessor" { + capabilities = ["update"] +} +``` + +### GitHub Actions Integration + +```hcl +# Policy: github-actions +# For GitHub Actions OIDC integration + +# Read secrets for the repository +path "secret/data/github/{{identity.entity.aliases.auth_jwt.metadata.repository}}/*" { + capabilities = ["read"] +} + +# Environment-specific paths +path "secret/data/github/{{identity.entity.aliases.auth_jwt.metadata.repository}}/{{identity.entity.aliases.auth_jwt.metadata.environment}}/*" { + capabilities = ["read"] +} +``` + +### GitLab CI Integration + +```hcl +# Policy: gitlab-ci +# For GitLab CI JWT integration + +path "secret/data/gitlab/{{identity.entity.aliases.auth_jwt.metadata.project_path}}/*" { + capabilities = ["read"] +} + +# Restrict to protected branches only +# (Combine with Sentinel for branch checks) +``` + +--- + +## Policy Anti-Patterns to Avoid + +| Anti-Pattern | Problem | Correct Approach | +| -------------- | --------- | ------------------ | +| `path "*"` | Too broad, security risk | Use specific paths | +| `capabilities = ["sudo"]` everywhere | Bypasses controls | Only for sys/ paths that require it | +| Sharing policies across apps | Violates least privilege | One policy per app/role | +| Hardcoded paths | Doesn't scale | Use templated policies | +| No `min_wrapping_ttl` on secret-id | Secrets in plain text | Always wrap secret-id | + +--- + +## Policy Management Commands + +```bash +# Write policy from file +vault policy write app-policy app-policy.hcl + +# Write policy inline +vault policy write test-policy - < secret/data/myapp/config +``` + +### Lookup Token Policies + +```bash +vault token lookup +# Shows attached policies + +vault token lookup -accessor +``` + +### Common Issues + +**Permission denied on valid path**: + +- Check KV v2 paths include `/data/` segment +- Verify policy uses correct path pattern +- Check for `deny` capability in other policies + +**Can list but not read**: + +- `list` and `read` are separate capabilities +- Add `read` capability to policy + +**Wildcard not matching**: + +- `*` matches immediate children only +- Use `+` for recursive matching + +--- + +## Sentinel Policies (Enterprise) + +Fine-grained policy-as-code using Sentinel language. + +### Endpoint Governing Policies (EGP) + +Applied to specific paths. + +```sentinel +# Require MFA for sensitive paths +import "mfa" + +main = rule { + mfa.methods.totp.valid +} +``` + +### Role Governing Policies (RGP) + +Applied to specific identities. + +```sentinel +# Restrict access by time +import "time" + +main = rule { + time.now.hour >= 9 and time.now.hour < 17 +} +``` + +### Sentinel Policy Management + +```bash +# Write Sentinel policy +vault write sys/policies/egp/business-hours \ + policy=@policy.sentinel \ + paths="secret/data/prod/*" \ + enforcement_level="hard-mandatory" + +# Enforcement levels: advisory, soft-mandatory, hard-mandatory +``` + +--- + +## Best Practices + +1. **Principle of least privilege**: Grant minimum necessary access +2. **Use path patterns**: Avoid overly broad wildcards +3. **Separate policies by function**: Don't combine unrelated permissions +4. **Use templates**: Leverage identity templating for scalability +5. **Test policies**: Verify with `vault token capabilities` +6. **Version control**: Store policies in git +7. **Document policies**: Include comments explaining intent +8. **Regular audits**: Review policies periodically +9. **Use Sentinel**: Add business logic for complex requirements (Enterprise) + +--- + +## Additional Resources + +- [Policies Documentation](https://developer.hashicorp.com/vault/docs/concepts/policies) +- [Policy Tutorial](https://developer.hashicorp.com/vault/tutorials/policies) +- [Sentinel Documentation](https://developer.hashicorp.com/vault/docs/enterprise/sentinel) + +--- + +## Related + +- [Auth Methods](auth-methods.md) - Authentication methods that policies attach to +- [Secrets Engines](secrets-engines.md) - Paths that policies protect +- [Enterprise](enterprise.md) - Sentinel policies and namespaces diff --git a/vault/authentication/skills/response-wrapping/SKILL.md b/vault/authentication/skills/response-wrapping/SKILL.md new file mode 100644 index 0000000..3b793d4 --- /dev/null +++ b/vault/authentication/skills/response-wrapping/SKILL.md @@ -0,0 +1,189 @@ +--- +name: response-wrapping +description: Use when working with Vault response wrapping, cubbyhole secrets, secure secret distribution, wrapped tokens, or bootstrap workflows. Covers wrap/unwrap operations and malfeasance detection. +--- + +# Response Wrapping and Cubbyhole + +Securely distribute secrets using Vault's response wrapping and cubbyhole mechanisms. + +## Reference + +- [Response Wrapping](https://developer.hashicorp.com/vault/docs/concepts/response-wrapping) +- [Cubbyhole Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/cubbyhole) +- For complete wrapping workflows and security patterns, see [references/response-wrapping.md](references/response-wrapping.md) + +## Overview + +Response wrapping provides a secure mechanism to distribute secrets by: +1. Wrapping any Vault response in a single-use token +2. Storing the wrapped response in the token's cubbyhole +3. Allowing the recipient to unwrap exactly once +4. Detecting interception through "malfeasance detection" + +## Cubbyhole Secrets Engine + +Every token has its own private cubbyhole storage: + +```bash +# Write to current token's cubbyhole +vault write cubbyhole/my-secret value="sensitive-data" + +# Read from cubbyhole +vault read cubbyhole/my-secret + +# Cubbyhole is destroyed when token expires or is revoked +``` + +**Key Properties:** +- Scoped to the token - no other token can access it +- Not shared across token hierarchies +- Automatically destroyed with the token +- Cannot be listed by other tokens + +## Response Wrapping + +### Wrap Any Response + +```bash +# Wrap a secret read with 5-minute TTL +vault read -wrap-ttl=5m secret/data/myapp + +# Returns wrapped token instead of secret +Key Value +--- ----- +wrapping_token: hvs.CAES... +wrapping_accessor: 8WxD3y... +wrapping_token_ttl: 5m +wrapping_token_creation_time: 2024-01-15T10:30:00Z +wrapping_token_creation_path: secret/data/myapp +``` + +### Unwrap a Wrapped Token + +```bash +# Recipient unwraps to get the original response +vault unwrap hvs.CAES... + +# Or using the environment +VAULT_TOKEN=hvs.CAES... vault unwrap +``` + +### Wrap Arbitrary Data + +```bash +# Wrap arbitrary JSON data +vault write -wrap-ttl=1h sys/wrapping/wrap data='{"api_key":"secret123"}' +``` + +## API Examples + +### Create Wrapped Response + +```bash +curl -X GET \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -H "X-Vault-Wrap-TTL: 300" \ + $VAULT_ADDR/v1/secret/data/myapp +``` + +### Unwrap Token + +```bash +curl -X POST \ + -H "X-Vault-Token: hvs.wrapped_token" \ + $VAULT_ADDR/v1/sys/wrapping/unwrap +``` + +### Look Up Wrapped Token Properties + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"token": "hvs.wrapped_token"}' \ + $VAULT_ADDR/v1/sys/wrapping/lookup +``` + +## Malfeasance Detection + +If someone intercepts and unwraps a token before the intended recipient: + +```bash +# Second unwrap attempt fails with clear indication +vault unwrap hvs.previously_unwrapped + +Error: wrapping token is not valid or does not exist +``` + +The original sender can verify delivery by: +1. Storing the wrapping accessor +2. Checking if the token was unwrapped by the expected entity +3. Detecting if unwrap happened from unexpected source + +## Bootstrap Workflow + +### Service Bootstrap with Wrapped Token + +```bash +# 1. Operator creates wrapped approle credentials +vault write -wrap-ttl=24h -f auth/approle/role/myapp/secret-id + +# 2. Deliver wrapped token to new service (secure channel) +# 3. Service unwraps on first boot +vault unwrap hvs.wrapped_secretid + +# 4. Service authenticates with unwrapped secret-id +vault write auth/approle/login \ + role_id="role-id" \ + secret_id="unwrapped-secret-id" +``` + +### Secure Handoff Pattern + +``` +┌──────────┐ wrapped token ┌──────────┐ +│ Operator │ ─────────────────────► │ Service │ +└──────────┘ └────┬─────┘ + │ + │ unwrap (once) + ▼ + ┌──────────┐ + │ Vault │ + └──────────┘ +``` + +## Wrapping TTL Best Practices + +| Use Case | Recommended TTL | +|----------|-----------------| +| Interactive handoff | 5-15 minutes | +| Automated bootstrap | 1-24 hours | +| Scheduled deployment | Match deployment window | +| Emergency access | 30 seconds - 5 minutes | + +## Common Patterns + +### Wrap Token Creation + +```bash +# Create wrapped token for another service +vault token create \ + -wrap-ttl=1h \ + -policy=app-policy \ + -ttl=4h +``` + +### Rewrap for Extended Delivery + +```bash +# Rewrap an existing wrapped token with new TTL +vault write sys/wrapping/rewrap token="hvs.old_wrapped" +``` + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| "wrapping token is not valid" | Already unwrapped or expired | Generate new wrapped response | +| "permission denied" | Token lacks unwrap permission | Use token with appropriate policy | +| Empty response on unwrap | Original secret was empty | Verify source secret exists | diff --git a/vault/authentication/skills/response-wrapping/references/response-wrapping.md b/vault/authentication/skills/response-wrapping/references/response-wrapping.md new file mode 100644 index 0000000..8a1ae82 --- /dev/null +++ b/vault/authentication/skills/response-wrapping/references/response-wrapping.md @@ -0,0 +1,73 @@ +--- +name: response-wrapping +description: Reference documentation for Vault response wrapping, cubbyhole secrets, and secure secret distribution patterns. +--- + +# Response Wrapping Reference + +## Core Concepts + +### Cubbyhole Secrets Engine + +The cubbyhole secrets engine provides private, token-scoped secret storage: + +- **Token Isolation**: Each token has its own cubbyhole that no other token can access +- **Automatic Cleanup**: Cubbyhole is destroyed when the token expires or is revoked +- **No Hierarchy**: Child tokens cannot access parent's cubbyhole +- **Default Enabled**: Mounted at `cubbyhole/` by default, cannot be disabled + +### Response Wrapping Mechanism + +1. Client requests wrapped response with `X-Vault-Wrap-TTL` header +2. Vault generates a single-use wrapping token +3. Original response is stored in the wrapping token's cubbyhole +4. Client receives wrapping token instead of original response +5. Recipient unwraps token to retrieve original response +6. Wrapping token is immediately invalidated after unwrap + +## CLI Reference + +| Command | Description | +|---------|-------------| +| `vault read -wrap-ttl= ` | Read and wrap response | +| `vault write -wrap-ttl= ` | Write and wrap response | +| `vault unwrap [token]` | Unwrap wrapped token | +| `vault token create -wrap-ttl=` | Create and wrap new token | + +## API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/sys/wrapping/wrap` | Wrap arbitrary data | +| POST | `/sys/wrapping/unwrap` | Unwrap wrapped token | +| POST | `/sys/wrapping/lookup` | Look up wrapping token properties | +| POST | `/sys/wrapping/rewrap` | Rewrap with new wrapping token | + +## Wrapping Token Properties + +```json +{ + "wrapping_token": "hvs.CAESIFhP...", + "wrapping_accessor": "abc123...", + "wrapping_token_ttl": 300, + "wrapping_token_creation_time": "2024-01-15T10:00:00Z", + "wrapping_token_creation_path": "secret/data/myapp" +} +``` + +## Security Considerations + +1. **Single Use**: Wrapped tokens can only be unwrapped once +2. **TTL Limits**: Set appropriate TTL based on delivery time +3. **Malfeasance Detection**: Failed unwrap indicates interception +4. **Creation Path**: Stored for audit purposes, reveals original request path +5. **No Renewal**: Wrapping tokens cannot be renewed + +## Use Cases + +| Scenario | Recommended TTL | +|----------|-----------------| +| Interactive handoff | 5-15 minutes | +| Service bootstrap | 30 minutes - 24 hours | +| Automated deployment | Match deployment window | +| Emergency credential | 1-5 minutes | diff --git a/vault/authentication/skills/token-management/SKILL.md b/vault/authentication/skills/token-management/SKILL.md new file mode 100644 index 0000000..8b71795 --- /dev/null +++ b/vault/authentication/skills/token-management/SKILL.md @@ -0,0 +1,236 @@ +--- +name: token-management +description: Use when working with Vault token types, creating periodic or batch tokens, managing token accessors, orphan tokens, or token lifecycle. Covers service vs batch tokens and renewal strategies. +--- + +# Token Management + +Manage Vault token types, lifecycle, and access patterns for different workloads. + +## Reference + +- [Token Concepts](https://developer.hashicorp.com/vault/docs/concepts/tokens) +- [Token Auth Method](https://developer.hashicorp.com/vault/docs/auth/token) +- For complete token lifecycle patterns and accessor management, see [references/token-management.md](references/token-management.md) + +## Token Types Overview + +| Type | Storage | Renewable | Use Case | +|------|---------|-----------|----------| +| Service | Yes | Yes | Standard operations, child tokens | +| Batch | No | No | High-scale ephemeral workloads | +| Periodic | Yes | Yes (indefinitely) | Long-running services | +| Orphan | Yes | Yes | Independent token lifecycle | + +## Token Prefixes + +``` +hvs. - Service token +hvb. - Batch token +hvr. - Recovery token +``` + +## Service Tokens + +Standard tokens with full features: + +```bash +# Create service token (default) +vault token create -policy=myapp -ttl=4h + +# Create with explicit type +vault token create -type=service -policy=myapp + +# Renew before expiration +vault token renew hvs.token_value + +# Or self-renew +vault token renew +``` + +## Batch Tokens + +Lightweight, no storage overhead: + +```bash +# Create batch token +vault token create -type=batch -policy=myapp -ttl=1h + +# Batch tokens cannot be renewed +# They expire at TTL, period + +# Best for: +# - Serverless functions +# - Kubernetes pods with short lifespans +# - High-throughput automation +``` + +## Periodic Tokens + +Never expire if renewed within period: + +```bash +# Create periodic token (requires sudo/root) +vault token create -period=24h -policy=myapp + +# Token TTL resets to period on each renewal +vault token renew hvs.periodic_token + +# Use for: +# - Long-running services +# - Database connection pools +# - Background workers +``` + +## Orphan Tokens + +Independent of parent token lifecycle: + +```bash +# Create orphan token +vault token create -orphan -policy=myapp + +# Or via token store role +vault write auth/token/roles/orphan-role orphan=true +vault token create -role=orphan-role + +# Orphan tokens are NOT revoked when parent is revoked +``` + +## Token Accessors + +Reference tokens without exposing values: + +```bash +# Get accessor when creating token +vault token create -policy=myapp +# Key Value +# token_accessor abc123xyz + +# Lookup token by accessor +vault token lookup -accessor abc123xyz + +# Revoke by accessor (safer for automation) +vault token revoke -accessor abc123xyz + +# List all accessors (requires root/sudo) +vault list auth/token/accessors +``` + +## Token Capabilities + +Check what a token can do: + +```bash +# Check current token's capabilities on a path +vault token capabilities secret/data/myapp + +# Check specific token's capabilities +vault token capabilities -accessor abc123 secret/data/myapp + +# Self-check +vault token lookup +``` + +## Token Renewal Strategies + +### Manual Renewal + +```bash +# Renew with default increment +vault token renew + +# Renew with specific increment +vault token renew -increment=1h + +# Renew another token +vault token renew hvs.other_token +``` + +### Programmatic Renewal + +```go +// Go example with vault client +client.Auth().Token().RenewSelf(3600) +``` + +### Renewal Considerations + +``` +┌─────────────────────────────────────────────────────────┐ +│ Token Lifetime │ +├──────────────┬──────────────────────────────────────────┤ +│ Created │ Max TTL │ +│ │ │ │ │ +│ ▼ │ ▼ │ +│ [────TTL────]───renew──[────TTL────]───renew──[──] │ +│ │ │ +│ Token │ │ +│ Expires │ +└─────────────────────────────────────────────────────────┘ +``` + +## Token Store Roles + +Pre-define token configurations: + +```bash +# Create role for CI/CD tokens +vault write auth/token/roles/cicd \ + allowed_policies="deploy-policy" \ + orphan=true \ + renewable=true \ + token_period=1h \ + token_explicit_max_ttl=24h + +# Create token from role +vault token create -role=cicd +``` + +## Decision Matrix + +| Requirement | Token Type | +|-------------|------------| +| Standard app with renewal | Service | +| High-scale, short-lived | Batch | +| Long-running, must not expire | Periodic | +| Independent lifecycle | Orphan | +| Pre-approved parameters | Role-based | + +## API Examples + +### Create Token + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"policies":["myapp"],"ttl":"1h"}' \ + $VAULT_ADDR/v1/auth/token/create +``` + +### Lookup Token + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"token":"hvs.target_token"}' \ + $VAULT_ADDR/v1/auth/token/lookup +``` + +### Revoke Token + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"token":"hvs.target_token"}' \ + $VAULT_ADDR/v1/auth/token/revoke +``` + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Token expired unexpectedly | Didn't renew before TTL | Implement renewal loop | +| Cannot renew batch token | Batch tokens are non-renewable | Use service token instead | +| Max TTL prevents renewal | System or mount max_ttl hit | Re-authenticate for new token | +| Orphan token still revoked | Explicit revocation, not parent | Check audit logs | diff --git a/vault/authentication/skills/token-management/references/token-management.md b/vault/authentication/skills/token-management/references/token-management.md new file mode 100644 index 0000000..88a9083 --- /dev/null +++ b/vault/authentication/skills/token-management/references/token-management.md @@ -0,0 +1,116 @@ +--- +name: token-management +description: Reference documentation for Vault token types, lifecycle, and management patterns. +--- + +# Token Management Reference + +## Token Types + +| Type | Prefix | Storage | Renewable | Parent Revocation | +|------|--------|---------|-----------|-------------------| +| Service | `hvs.` | Yes | Yes | Revokes children | +| Batch | `hvb.` | No | No | Stops working | +| Periodic | `hvs.` | Yes | Yes (indefinite) | Revokes children | +| Orphan | `hvs.` | Yes | Yes | Not affected | +| Root | `hvs.` | Yes | Optional | N/A | + +## Token Capabilities + +Service tokens support all capabilities: +- Create child tokens +- Have cubbyholes +- Be renewed +- Be explicitly revoked +- Have explicit max TTL +- Be periodic + +Batch tokens are lightweight but limited: +- No storage overhead +- Cannot create children +- Cannot be renewed +- No cubbyhole +- Scale with standbys + +## CLI Reference + +| Command | Description | +|---------|-------------| +| `vault token create` | Create new token | +| `vault token lookup [token]` | View token details | +| `vault token renew [token]` | Renew token lease | +| `vault token revoke [token]` | Revoke token and children | +| `vault token capabilities ` | Check token permissions | +| `vault list auth/token/accessors` | List all token accessors | + +## Token Creation Flags + +| Flag | Description | +|------|-------------| +| `-type=` | service or batch | +| `-policy=` | Attach policy (repeatable) | +| `-ttl=` | Initial TTL | +| `-explicit-max-ttl=` | Hard limit on lifetime | +| `-period=` | Create periodic token | +| `-orphan` | Create without parent | +| `-renewable=` | Allow renewal (default: true) | +| `-no-parent` | Create orphan (requires sudo) | + +## API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/auth/token/create` | Create token | +| POST | `/auth/token/create-orphan` | Create orphan token | +| POST | `/auth/token/lookup` | Lookup token | +| POST | `/auth/token/lookup-accessor` | Lookup by accessor | +| POST | `/auth/token/renew` | Renew token | +| POST | `/auth/token/revoke` | Revoke token | +| POST | `/auth/token/revoke-orphan` | Revoke, orphan children | +| POST | `/auth/token/revoke-accessor` | Revoke by accessor | +| LIST | `/auth/token/accessors` | List all accessors | + +## Token Store Roles + +Pre-define token parameters: + +```bash +vault write auth/token/roles/cicd \ + allowed_policies="deploy,read" \ + disallowed_policies="admin" \ + orphan=true \ + renewable=true \ + token_period=1h \ + token_explicit_max_ttl=24h \ + token_type=service \ + token_num_uses=0 \ + token_bound_cidrs="10.0.0.0/8" +``` + +## TTL Hierarchy + +1. **System max TTL**: 32 days (default), configurable +2. **Mount max TTL**: Per auth method tuning +3. **Role/Auth max TTL**: Configured on role or auth method +4. **Request TTL**: Requested at token creation +5. **Explicit max TTL**: Hard cap if set + +## Accessor Usage + +Accessors provide safe token references: + +- Lookup token metadata +- Check token capabilities +- Renew token +- Revoke token +- Audit logging + +**Cannot**: Read token value, use token for authentication + +## Root Token Best Practices + +1. Generate only for initial setup or emergencies +2. Use `vault operator generate-root` with quorum +3. Revoke immediately after use +4. Prefer limited tokens for daily operations +5. Multiple witnesses when using root tokens diff --git a/vault/enterprise/.claude-plugin/plugin.json b/vault/enterprise/.claude-plugin/plugin.json new file mode 100644 index 0000000..6e9223c --- /dev/null +++ b/vault/enterprise/.claude-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "vault-enterprise", + "version": "0.1.0", + "description": "Skills for HashiCorp Vault Enterprise features including namespaces, replication, Sentinel policies, MFA, and HSM integration", + "author": "HashiCorp", + "homepage": "https://developer.hashicorp.com/vault/docs/enterprise", + "repository": "https://github.com/hashicorp/agent-skills", + "license": "MPL-2.0", + "keywords": [ + "vault", + "enterprise", + "namespaces", + "replication", + "sentinel", + "mfa", + "hsm" + ], + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "VAULT_ADDR", + "-e", + "VAULT_TOKEN", + "-e", + "VAULT_NAMESPACE", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${VAULT_ADDR}", + "VAULT_TOKEN": "${VAULT_TOKEN}", + "VAULT_NAMESPACE": "${VAULT_NAMESPACE}" + } + } + } +} diff --git a/vault/enterprise/SPEC.md b/vault/enterprise/SPEC.md new file mode 100644 index 0000000..83ee1b3 --- /dev/null +++ b/vault/enterprise/SPEC.md @@ -0,0 +1,107 @@ +# Specification: vault-enterprise + +**Status**: Published +**Version**: 0.1.0 + +--- + +## Overview + +This plugin provides skills for HashiCorp Vault Enterprise features including multi-tenancy with namespaces, cross-datacenter replication, policy-as-code with Sentinel, multi-factor authentication (MFA), and Hardware Security Module (HSM) integration. + +--- + +## User Stories + +### US-1: Architect Designing Multi-Tenant Vault (P1) + +An enterprise architect needs to design a multi-tenant Vault deployment where different business units have isolated secrets and independent administration. + +**Acceptance Criteria**: +1. Given a user asks about tenant isolation, when the skill is invoked, then it provides namespace design patterns with recommended hierarchy. +2. Given a question about namespace limits, when queried, then the skill explains the ~4,600 namespace limit and strategies for large deployments. +3. Given an anti-pattern query, when asked about deep nesting, then the skill explains why to avoid >3 levels. + +### US-2: Security Engineer Implementing Policy-as-Code (P1) + +A security engineer needs to implement Sentinel policies for compliance requirements that go beyond standard ACL policies. + +**Acceptance Criteria**: +1. Given a request for compliance controls, when the skill is invoked, then it provides Sentinel policy examples for common requirements. +2. Given a question about policy types, when queried, then the skill differentiates EGP (Endpoint Governing Policies) vs RGP (Role Governing Policies). +3. Given a debugging scenario, when a policy fails, then the skill provides simulation and testing approaches. + +### US-3: Operations Engineer Configuring Replication (P2) + +An operations engineer needs to configure Performance Replication for read scaling and Disaster Recovery replication for business continuity. + +**Acceptance Criteria**: +1. Given a replication architecture question, when the skill is invoked, then it explains DR vs PR differences with use cases. +2. Given a failover question, when asked about DR promotion, then the skill provides step-by-step DR failover procedure. +3. Given a token question, when asked about cross-cluster tokens, then the skill explains batch token portability. + +### US-4: Identity Admin Configuring MFA (P2) + +An identity administrator needs to configure multi-factor authentication for sensitive operations in Vault. + +**Acceptance Criteria**: +1. Given an MFA configuration request, when the skill is invoked, then it differentiates Login MFA vs Step-up MFA. +2. Given a TOTP question, when asked about authenticator apps, then the skill provides TOTP configuration with code examples. +3. Given a policy question, when asked about requiring MFA, then the skill shows policy syntax for MFA enforcement. + +### US-5: Security Engineer Integrating HSM (P3) + +A security engineer in a regulated environment needs to integrate Vault with an HSM for seal/unseal and cryptographic operations. + +**Acceptance Criteria**: +1. Given an HSM question, when the skill is invoked, then it explains HSM integration options (PKCS#11). +2. Given an auto-unseal question, when queried about HSM vs cloud KMS, then the skill provides trade-offs. +3. Given a compliance question, when asked about FIPS 140-2, then the skill explains HSM requirements. + +--- + +## Functional Requirements + +| ID | Requirement | +|----|-------------| +| FR-001 | Skill MUST cover namespace design patterns and anti-patterns | +| FR-002 | Skill MUST include namespace hierarchy recommendations | +| FR-003 | Skill MUST explain namespace limits (~4,600 with default mount table) | +| FR-004 | Skill MUST cover Performance Replication configuration | +| FR-005 | Skill MUST cover Disaster Recovery Replication setup | +| FR-006 | Skill MUST include DR failover procedures | +| FR-007 | Skill MUST differentiate batch tokens for replication | +| FR-008 | Skill MUST cover Sentinel EGP and RGP policies | +| FR-009 | Skill MUST include Login MFA vs Step-up MFA | +| FR-010 | Skill MUST cover HSM/PKCS#11 integration | +| FR-011 | Skill MUST include Control Groups for approval workflows | + +--- + +## Skills Included + +| Skill | Description | +|-------|-------------| +| `enterprise-features` | Configure namespaces, replication, Sentinel, MFA, HSM, and Control Groups | + +--- + +## Non-Functional Requirements + +### NFR-1: Enterprise License Clarity + +All features MUST be clearly marked as requiring Vault Enterprise license. + +### NFR-2: Version Compatibility + +Features MUST note minimum Vault version requirements (e.g., Seal HA requires 1.16+). + +--- + +## References + +- [Vault Enterprise Documentation](https://developer.hashicorp.com/vault/docs/enterprise) +- [Namespaces](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) +- [Replication](https://developer.hashicorp.com/vault/docs/enterprise/replication) +- [Sentinel Policies](https://developer.hashicorp.com/vault/docs/enterprise/sentinel) +- [MFA](https://developer.hashicorp.com/vault/docs/enterprise/mfa) diff --git a/vault/enterprise/skills/enterprise-features/SKILL.md b/vault/enterprise/skills/enterprise-features/SKILL.md new file mode 100644 index 0000000..41ccf4c --- /dev/null +++ b/vault/enterprise/skills/enterprise-features/SKILL.md @@ -0,0 +1,237 @@ +--- +name: enterprise-features +description: Configure Vault Enterprise features. Use when asked about namespaces, multi-tenancy, Performance Replication, Disaster Recovery replication, Sentinel policies, MFA (Login or Step-up), Control Groups, or HSM integration. Covers enterprise-only capabilities requiring Vault Enterprise license. +--- + +# Vault Enterprise Features + +Vault Enterprise extends HashiCorp Vault with features for large-scale, regulated, and multi-tenant deployments. All features on this page require a Vault Enterprise license. + +## Reference + +- [Vault Enterprise Documentation](https://developer.hashicorp.com/vault/docs/enterprise) +- [Detailed Enterprise Reference](references/enterprise.md) + +--- + +## When to Use This Skill + +- **Namespaces**: Multi-tenant isolation for business units or teams +- **Replication**: Cross-datacenter sync (Performance or Disaster Recovery) +- **Sentinel**: Policy-as-code for compliance requirements +- **MFA**: Multi-factor authentication for sensitive operations +- **Control Groups**: Approval workflows for privileged actions +- **HSM**: Hardware Security Module integration for key protection + +--- + +## Namespaces + +Namespaces provide isolated Vault environments within a single cluster. + +### When to Use Namespaces + +| Criterion | Use Namespace? | +|-----------|---------------| +| Separate policy administration needed | Yes | +| Different compliance requirements | Yes | +| Distinct business units | Yes | +| Team-level isolation | Maybe (consider policies first) | +| Per-application isolation | No (use policies) | +| Per-environment (dev/prod) | No (use separate clusters) | + +### Recommended Architecture + +```text +root/ +├── shared-services/ # Shared auth, PKI roots +├── business-unit-a/ # LOB-level namespace +│ ├── team-1/ # Max 2-3 levels deep +│ └── team-2/ +└── business-unit-b/ +``` + +### Common Operations + +```bash +# Create namespace +vault namespace create business-unit-a +vault namespace create -namespace=business-unit-a team-1 + +# List namespaces +vault namespace list + +# Target namespace +export VAULT_NAMESPACE=business-unit-a/team-1 +vault secrets list + +# Lock namespace (incident response) +vault namespace lock business-unit-a + +# Unlock namespace +vault namespace unlock business-unit-a -unlock-key= +``` + +### Anti-Patterns + +- Deep nesting (> 3 levels) +- Namespace per person +- Environment names in paths (dev/staging/prod) +- Namespace per application + +### Namespace Limits + +| Configuration | Approximate Limit | +|---------------|-------------------| +| Default mount table | ~4,600 namespaces | +| Recommended max depth | 2-3 levels | +| Naming restrictions | No `/`, `\`, `..`, `%`, or `+` | + +--- + +## Replication + +### Performance Replication (PR) + +Read scaling and geographic distribution. Tokens and leases are NOT replicated. + +```bash +# Primary cluster +vault write -f sys/replication/performance/primary/enable + +# Get secondary activation token +vault write sys/replication/performance/primary/secondary-token id=region-2 + +# Secondary cluster +vault write sys/replication/performance/secondary/enable token= +``` + +### Disaster Recovery (DR) + +Business continuity with hot standby. DR cluster is read-only until promoted. + +```bash +# Primary cluster +vault write -f sys/replication/dr/primary/enable + +# Get secondary activation token +vault write sys/replication/dr/primary/secondary-token id=dr-site + +# Secondary cluster (standby) +vault write sys/replication/dr/secondary/enable token= + +# DR Failover (on secondary) +vault write -f sys/replication/dr/secondary/promote +``` + +### Key Considerations + +- Local mounts are NOT replicated +- Batch tokens ARE portable across PR clusters +- Never enable two primaries simultaneously +- Upgrade secondaries BEFORE primary + +--- + +## Sentinel Policies + +Policy-as-code for advanced access control beyond ACLs. + +### Policy Types + +| Type | Scope | Use Case | +|------|-------|----------| +| EGP (Endpoint Governing) | Specific paths | Enforce rules on API endpoints | +| RGP (Role Governing) | Tokens/identities | Apply rules based on who is making request | + +### Example: Require MFA for Admin Operations + +```python +import "mfa" +import "strings" + +# Require MFA for /sys/ operations +precond = rule { + strings.has_prefix(request.path, "sys/") +} + +main = rule when precond { + mfa.methods.totp.valid +} +``` + +### Example: Time-Based Restrictions + +```python +import "time" + +# Only allow writes during business hours +main = rule when request.operation in ["create", "update"] { + time.now.hour >= 9 and time.now.hour < 17 and + time.now.weekday_name not in ["Saturday", "Sunday"] +} +``` + +--- + +## Multi-Factor Authentication (MFA) + +### Login MFA vs Step-up MFA + +| Type | When Applied | Use Case | +|------|--------------|----------| +| Login MFA | During authentication | Require MFA for all logins | +| Step-up MFA | During specific operations | Require MFA for sensitive paths only | + +### Configure TOTP MFA + +```bash +# Enable TOTP MFA method +vault write sys/mfa/method/totp/my-totp \ + issuer=Vault \ + period=30 \ + key_size=20 \ + algorithm=SHA1 \ + digits=6 + +# Generate admin QR code (Step-up MFA) +vault write sys/mfa/method/totp/my-totp/admin-generate \ + entity_id= +``` + +--- + +## Control Groups + +Require approval from authorized users before granting access. + +```bash +# Create control group policy +vault policy write requires-approval - < +``` + +### Namespace Limits and Restrictions + +| Configuration | Value/Limit | +|---------------|-------------| +| Default mount table limit | ~4,600 namespaces | +| Recommended max depth | 2-3 levels | +| Invalid characters | `/`, `\`, `..`, `%`, `+` | +| Reserved names | `sys`, `auth`, `identity`, `cubbyhole` | + +--- + +## Performance Replication + +Performance Replication provides read scaling and geographic distribution. + +### Enable Performance Replication + +```bash +# On Primary Cluster +vault write -f sys/replication/performance/primary/enable + +# Generate activation token +vault write sys/replication/performance/primary/secondary-token \ + id=region-2 \ + ttl=1h + +# On Secondary Cluster +vault write sys/replication/performance/secondary/enable \ + token= +``` + +### Promote Secondary to Primary + +```bash +# On secondary (emergency failover) +vault write -f sys/replication/performance/secondary/promote + +# Demote old primary +vault write -f sys/replication/performance/primary/demote +``` + +### Performance Replication Considerations + +| Item | Replicated? | +|------|-------------| +| Secrets engine mounts | Yes | +| Auth method mounts | Yes | +| Policies | Yes | +| Tokens | **No** | +| Leases | **No** | +| Local mounts | **No** | + +### Batch Tokens for Cross-Cluster Operations + +Batch tokens ARE portable across PR clusters: + +```bash +# Create batch token +vault token create -type=batch -policy=my-policy + +# Use on any PR cluster +export VAULT_TOKEN= +vault kv get -namespace=ns1 secret/data/myapp +``` + +--- + +## Disaster Recovery Replication + +DR Replication provides a hot standby for business continuity. + +### Enable DR Replication + +```bash +# On Primary Cluster +vault write -f sys/replication/dr/primary/enable + +# Generate activation token +vault write sys/replication/dr/primary/secondary-token \ + id=dr-site \ + ttl=1h + +# On DR Secondary Cluster +vault write sys/replication/dr/secondary/enable \ + token= +``` + +### DR Failover Procedure + +```bash +# 1. On DR secondary, generate operation token (requires recovery keys) +vault operator generate-root -dr-token + +# 2. Promote DR secondary to primary +vault write -f sys/replication/dr/secondary/promote \ + dr_operation_token= + +# 3. Update DNS/load balancer to point to new primary + +# 4. After recovery, demote old primary and re-establish replication +``` + +### DR Best Practices + +1. DR cluster MUST be in separate region from primary +2. Mirror primary cluster specifications exactly +3. Use different KMS/HSM in DR region +4. Take backups from DR cluster to avoid loading primary +5. Test DR failover quarterly with documented runbooks +6. Never promote PR as DR - use dedicated DR clusters + +--- + +## Sentinel Policies + +### Policy Types + +| Type | Applies To | Use Case | +|------|-----------|----------| +| EGP (Endpoint Governing) | API paths | Enforce rules on specific endpoints | +| RGP (Role Governing) | Tokens/identities | Apply rules based on requester identity | + +### Write Sentinel Policy + +```bash +# Create EGP policy +vault write sys/policies/egp/require-mfa \ + policy=@require-mfa.sentinel \ + paths="secret/*" \ + enforcement_level="hard-mandatory" +``` + +### Enforcement Levels + +| Level | Behavior | +|-------|----------| +| `advisory` | Log failure but allow operation | +| `soft-mandatory` | Block operation but can be overridden | +| `hard-mandatory` | Block operation, no override | + +### Example: Require MFA for Admin Paths + +```python +# require-mfa.sentinel +import "mfa" +import "strings" + +# Only apply to sys/ paths +precond = rule { + strings.has_prefix(request.path, "sys/") +} + +main = rule when precond { + mfa.methods.totp.valid +} +``` + +### Example: Restrict by Time + +```python +# business-hours.sentinel +import "time" + +# Block writes outside business hours +main = rule when request.operation in ["create", "update", "delete"] { + time.now.hour >= 9 and + time.now.hour < 17 and + time.now.weekday_name not in ["Saturday", "Sunday"] +} +``` + +### Example: Restrict by Identity Group + +```python +# require-group.sentinel +import "identity" + +# Only security-team can access privileged paths +main = rule { + "security-team" in identity.groups.names +} +``` + +--- + +## Multi-Factor Authentication (MFA) + +### Login MFA vs Step-up MFA + +| Type | When Applied | Configuration | +|------|--------------|---------------| +| Login MFA | During authentication | Configure on auth method | +| Step-up MFA | During path access | Configure in policy | + +### Configure TOTP Method + +```bash +# Create TOTP method +vault write sys/mfa/method/totp/my-totp \ + issuer="MyCompany Vault" \ + period=30 \ + key_size=20 \ + algorithm=SHA1 \ + digits=6 \ + skew=1 + +# For Login MFA - bind to auth method +vault write auth/userpass/mfa_config \ + type="totp" \ + mount_accessor=$(vault auth list -format=json | jq -r '.["userpass/"].accessor') +``` + +### Generate TOTP for User (Step-up MFA) + +```bash +# Admin generates QR code for entity +vault write sys/mfa/method/totp/my-totp/admin-generate \ + entity_id=$(vault read -field=id identity/entity/name/alice) +``` + +### Configure Step-up MFA in Policy + +```hcl +path "secret/data/sensitive/*" { + capabilities = ["read"] + mfa_methods = ["my-totp"] +} +``` + +--- + +## Control Groups + +Control Groups require approval from authorized users before granting access. + +### Configure Control Group Policy + +```hcl +path "secret/data/production/*" { + capabilities = ["read"] + + control_group = { + factor "approvers" { + identity { + group_names = ["security-team", "senior-engineers"] + approvals = 2 + } + } + ttl = "1h" + max_ttl = "4h" + } +} +``` + +### Control Group Workflow + +```bash +# 1. User requests access +vault kv get secret/production/database +# Returns: control group accessor + +# 2. Approvers authorize +vault write sys/control-group/authorize accessor= + +# 3. After required approvals, user completes request +vault kv get secret/production/database +``` + +--- + +## HSM Integration + +### PKCS#11 Configuration + +```hcl +# Vault configuration file +seal "pkcs11" { + lib = "/usr/lib/softhsm/libsofthsm2.so" + slot = "0" + pin = "1234" + key_label = "vault-hsm-key" + hmac_key_label = "vault-hsm-hmac" + generate_key = "true" +} +``` + +### HSM Best Practices + +1. Use dedicated HSM partition for Vault +2. Configure HSM HA for seal availability +3. Test HSM failover procedures +4. Monitor HSM health alongside Vault health +5. Plan for HSM key rotation procedures + +--- + +## Additional Resources + +- [Namespaces](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) +- [Performance Replication](https://developer.hashicorp.com/vault/docs/enterprise/replication) +- [DR Replication](https://developer.hashicorp.com/vault/docs/enterprise/replication/dr) +- [Sentinel Policies](https://developer.hashicorp.com/vault/docs/enterprise/sentinel) +- [MFA](https://developer.hashicorp.com/vault/docs/enterprise/mfa) +- [Control Groups](https://developer.hashicorp.com/vault/docs/enterprise/control-groups) +- [HSM Integration](https://developer.hashicorp.com/vault/docs/enterprise/hsm) + +--- + +## Related + +- [auth-methods.md](../../authentication/skills/auth-methods/references/auth-methods.md) - Authentication configuration +- [policies.md](../../authentication/skills/policies/references/policies.md) - ACL policy syntax +- [production-operations.md](../../operations/skills/production-operations/references/production-operations.md) - HA and DR operations diff --git a/vault/hashicorp-integrations/.claude-plugin/plugin.json b/vault/hashicorp-integrations/.claude-plugin/plugin.json new file mode 100644 index 0000000..3eee949 --- /dev/null +++ b/vault/hashicorp-integrations/.claude-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "vault-hashicorp-integrations", + "version": "0.1.0", + "description": "Vault secrets engines for HashiCorp products - generate dynamic tokens for Consul, Nomad, and Terraform Cloud/Enterprise", + "author": "HashiCorp", + "homepage": "https://developer.hashicorp.com/vault/docs/secrets", + "repository": "https://github.com/hashicorp/agent-skills", + "license": "MPL-2.0", + "keywords": [ + "vault", + "consul", + "nomad", + "terraform", + "dynamic-credentials", + "acl-tokens", + "api-tokens" + ], + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "VAULT_ADDR", + "-e", + "VAULT_TOKEN", + "-e", + "VAULT_NAMESPACE", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${VAULT_ADDR}", + "VAULT_TOKEN": "${VAULT_TOKEN}", + "VAULT_NAMESPACE": "${VAULT_NAMESPACE}" + } + } + } +} diff --git a/vault/hashicorp-integrations/SPEC.md b/vault/hashicorp-integrations/SPEC.md new file mode 100644 index 0000000..47d73aa --- /dev/null +++ b/vault/hashicorp-integrations/SPEC.md @@ -0,0 +1,99 @@ +# Vault HashiCorp Integrations Plugin Specification + +## Overview + +This plugin provides skills for Vault's secrets engines that generate dynamic credentials for other HashiCorp products. These engines enable centralized credential management across your HashiCorp stack. + +## User Stories + +### Consul Secrets Engine + +**US-1**: As a platform engineer, I want Vault to generate dynamic Consul ACL tokens, so that my services have just-in-time access to Consul without long-lived credentials. + +**US-2**: As a security engineer, I want Consul tokens to be automatically revoked when leases expire, so that credential sprawl is eliminated. + +**US-3**: As a developer, I want to request Consul tokens scoped to specific services and nodes, so that my application has least-privilege access. + +### Nomad Secrets Engine + +**US-4**: As a platform engineer, I want Vault to generate dynamic Nomad ACL tokens, so that job submissions use ephemeral credentials. + +**US-5**: As an SRE, I want to map Vault roles to Nomad ACL policies, so that token permissions are consistently defined. + +**US-6**: As a developer, I want to request Nomad tokens for specific environments, so that I can deploy to staging without production access. + +### Terraform Cloud Secrets Engine + +**US-7**: As a DevOps engineer, I want Vault to generate dynamic Terraform Cloud API tokens, so that CI/CD pipelines don't need long-lived tokens. + +**US-8**: As a platform engineer, I want to generate team-scoped TFC tokens, so that automation can manage specific workspaces. + +**US-9**: As an administrator, I want to rotate organization tokens through Vault, so that compromise recovery is automated. + +## Functional Requirements + +### Consul Secrets Engine (FR-1 through FR-6) + +| ID | Requirement | +|----|-------------| +| FR-1 | Document Consul secrets engine setup and configuration | +| FR-2 | Provide role definitions for policies, node identities, and service identities | +| FR-3 | Include dynamic token generation and lease management | +| FR-4 | Document Consul Enterprise namespace and partition support | +| FR-5 | Provide ACL bootstrap integration with Vault | +| FR-6 | Include token TTL and automatic rotation patterns | + +### Nomad Secrets Engine (FR-7 through FR-11) + +| ID | Requirement | +|----|-------------| +| FR-7 | Document Nomad secrets engine setup and configuration | +| FR-8 | Provide role mapping to Nomad ACL policies | +| FR-9 | Include dynamic token generation workflows | +| FR-10 | Document management token requirements | +| FR-11 | Provide lease configuration and renewal patterns | + +### Terraform Cloud Secrets Engine (FR-12 through FR-18) + +| ID | Requirement | +|----|-------------| +| FR-12 | Document Terraform Cloud secrets engine setup | +| FR-13 | Provide organization, team, and user role types | +| FR-14 | Include dynamic team token generation | +| FR-15 | Document user token management | +| FR-16 | Provide organization token rotation workflows | +| FR-17 | Include Terraform Enterprise on-prem configuration | +| FR-18 | Document token expiration and max_ttl behavior | + +## Skills Matrix + +| Skill | Product | Credential Types | +|-------|---------|------------------| +| consul-secrets | HashiCorp Consul | ACL tokens (policies, service identities, node identities) | +| nomad-secrets | HashiCorp Nomad | ACL tokens (client tokens mapped to policies) | +| terraform-cloud-secrets | Terraform Cloud/Enterprise | API tokens (organization, team, user) | + +## Integration Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ HashiCorp Vault │ +├─────────────────┬─────────────────┬─────────────────────┤ +│ consul/ │ nomad/ │ terraform/ │ +│ secrets engine │ secrets engine │ secrets engine │ +└────────┬────────┴────────┬────────┴──────────┬──────────┘ + │ │ │ + ▼ ▼ ▼ + ┌───────────┐ ┌───────────┐ ┌─────────────────┐ + │ Consul │ │ Nomad │ │ Terraform Cloud │ + │ Cluster │ │ Cluster │ │ / Enterprise │ + └───────────┘ └───────────┘ └─────────────────┘ +``` + +## References + +- [Consul Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/consul) +- [Nomad Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/nomad) +- [Terraform Cloud Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/terraform) +- [Administer Consul ACL Tokens with Vault](https://developer.hashicorp.com/consul/tutorials/vault-secure/vault-consul-secrets) +- [Generate Nomad Tokens with Vault](https://developer.hashicorp.com/nomad/tutorials/integrate-vault/vault-nomad-secrets) diff --git a/vault/hashicorp-integrations/skills/consul-secrets/SKILL.md b/vault/hashicorp-integrations/skills/consul-secrets/SKILL.md new file mode 100644 index 0000000..2edc352 --- /dev/null +++ b/vault/hashicorp-integrations/skills/consul-secrets/SKILL.md @@ -0,0 +1,241 @@ +--- +name: consul-secrets +description: Use when generating dynamic Consul ACL tokens through Vault, configuring the Consul secrets engine, or managing Consul credentials. Covers policies, service identities, and node identities. +--- + +# Consul Secrets Engine + +Generate dynamic Consul ACL tokens through Vault with automatic lease management. + +## Reference + +- [Consul Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/consul) +- [Vault Consul Tutorial](https://developer.hashicorp.com/consul/tutorials/vault-secure/vault-consul-secrets) +- For complete role configuration and Enterprise features, see [references/consul-secrets.md](references/consul-secrets.md) + +## Overview + +The Consul secrets engine generates dynamic Consul ACL tokens based on: +- Consul ACL policies +- Service identities (Consul 1.5+) +- Node identities (Consul 1.8+) + +Tokens are automatically revoked when leases expire. + +## Setup + +### Enable the Engine + +```bash +vault secrets enable consul +``` + +### Configure Access + +```bash +# Option 1: Let Vault bootstrap Consul ACL system +vault write consul/config/access \ + address="127.0.0.1:8500" + +# Option 2: Use existing management token +vault write consul/config/access \ + address="https://consul.example.com:8501" \ + token="$CONSUL_MANAGEMENT_TOKEN" \ + ca_cert="@/path/to/ca.crt" +``` + +### TLS Configuration + +```bash +vault write consul/config/access \ + address="https://consul.example.com:8501" \ + token="$CONSUL_MANAGEMENT_TOKEN" \ + ca_cert="@ca.crt" \ + client_cert="@client.crt" \ + client_key="@client.key" +``` + +## Role Configuration + +### Policy-Based Roles (Consul 1.4+) + +```bash +# Create Consul ACL policy first +consul acl policy create -name readonly \ + -rules='key_prefix "" { policy = "read" }' + +# Create Vault role using policy +vault write consul/roles/readonly \ + consul_policies="readonly" +``` + +### Service Identity Roles (Consul 1.5+) + +```bash +# Role with service identity +vault write consul/roles/web-service \ + service_identities="web:dc1" \ + service_identities="api:dc1,dc2" +``` + +### Node Identity Roles (Consul 1.8+) + +```bash +# Role with node identity +vault write consul/roles/server-nodes \ + node_identities="server-1:dc1" \ + node_identities="server-2:dc1" +``` + +### Combined Role + +```bash +vault write consul/roles/platform \ + consul_policies="platform-policy" \ + service_identities="platform-svc:dc1" \ + node_identities="platform-node:dc1" \ + ttl=1h \ + max_ttl=24h +``` + +## Generate Credentials + +```bash +# Read credentials for a role +vault read consul/creds/readonly + +# Key Value +# lease_id consul/creds/readonly/abc123 +# lease_duration 768h +# lease_renewable true +# accessor a715994d-f5fd-1194-73df +# token b31fb56c-0936-5428-8c5f +``` + +### Use the Token + +```bash +# Set environment variable +export CONSUL_HTTP_TOKEN=$(vault read -field=token consul/creds/readonly) + +# Verify token +consul acl token read -self +``` + +## Consul Enterprise Features + +### Namespace-Scoped Roles (Consul 1.7+) + +```bash +vault write consul/roles/team-a \ + consul_roles="team-a-role" \ + consul_namespace="team-a" +``` + +### Partition-Scoped Roles (Consul 1.11+) + +```bash +vault write consul/roles/admin-partition \ + consul_roles="admin-management" \ + partition="admin1" +``` + +## Lease Management + +### Configure Default Lease + +```bash +vault write consul/config/access \ + address="127.0.0.1:8500" \ + token="$CONSUL_TOKEN" + +# Set default TTL +vault secrets tune -default-lease-ttl=1h consul/ +vault secrets tune -max-lease-ttl=24h consul/ +``` + +### Renew Lease + +```bash +vault lease renew consul/creds/readonly/abc123 +``` + +### Revoke Lease + +```bash +vault lease revoke consul/creds/readonly/abc123 +``` + +## Integration Pattern + +``` +┌──────────┐ 1. Request creds ┌───────────┐ +│ App │ ──────────────────► │ Vault │ +└────┬─────┘ └─────┬─────┘ + │ │ + │ 2. Create ACL token + │ │ + │ ▼ + │ ┌───────────┐ + │ 3. Use token │ Consul │ + └──────────────────────────►│ Cluster │ + └───────────┘ +``` + +## Policy Examples + +### Read-Only Policy + +```hcl +key_prefix "" { + policy = "read" +} +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + +### Service-Specific Policy + +```hcl +service "web" { + policy = "write" +} +service_prefix "" { + policy = "read" +} +key_prefix "web/" { + policy = "write" +} +``` + +## API Examples + +### Create Role + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"consul_policies":"readonly","ttl":"1h"}' \ + $VAULT_ADDR/v1/consul/roles/my-role +``` + +### Generate Credentials + +```bash +curl -X GET \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + $VAULT_ADDR/v1/consul/creds/my-role +``` + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| "ACL not found" | Policy doesn't exist in Consul | Create policy in Consul first | +| "Permission denied" | Vault token lacks Consul management | Use management token for config | +| Token not working | Consul ACLs not enabled | Enable ACLs in Consul config | +| Stale credentials | Consul agent config issue | Check Consul replication status | diff --git a/vault/hashicorp-integrations/skills/consul-secrets/references/consul-secrets.md b/vault/hashicorp-integrations/skills/consul-secrets/references/consul-secrets.md new file mode 100644 index 0000000..e8eecf4 --- /dev/null +++ b/vault/hashicorp-integrations/skills/consul-secrets/references/consul-secrets.md @@ -0,0 +1,103 @@ +--- +name: consul-secrets +description: Reference documentation for Vault Consul secrets engine configuration and role types. +--- + +# Consul Secrets Engine Reference + +## Configuration + +| Parameter | Description | +|-----------|-------------| +| `address` | Consul agent address (host:port) | +| `token` | Consul management token | +| `scheme` | http or https | +| `ca_cert` | CA certificate for TLS | +| `client_cert` | Client certificate for mTLS | +| `client_key` | Client private key for mTLS | + +## Role Types + +### Policy-Based (Consul 1.4+) + +```bash +vault write consul/roles/ \ + consul_policies="policy1,policy2" \ + ttl=1h \ + max_ttl=24h +``` + +### Service Identity (Consul 1.5+) + +```bash +vault write consul/roles/ \ + service_identities="svc:dc1" \ + service_identities="svc:dc1,dc2" +``` + +### Node Identity (Consul 1.8+) + +```bash +vault write consul/roles/ \ + node_identities="node:dc1" +``` + +### Consul Roles (Consul 1.5+) + +```bash +vault write consul/roles/ \ + consul_roles="consul-role-name" +``` + +## Enterprise Parameters + +| Parameter | Consul Version | Description | +|-----------|----------------|-------------| +| `consul_namespace` | 1.7+ | Namespace for token | +| `partition` | 1.11+ | Admin partition for token | + +## API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/consul/config/access` | Configure Consul access | +| POST | `/consul/roles/:name` | Create/update role | +| GET | `/consul/roles/:name` | Read role | +| LIST | `/consul/roles` | List roles | +| DELETE | `/consul/roles/:name` | Delete role | +| GET | `/consul/creds/:name` | Generate credentials | + +## Token Response + +```json +{ + "lease_id": "consul/creds/role/abc123", + "lease_duration": 3600, + "renewable": true, + "data": { + "accessor": "uuid", + "token": "secret-token", + "local": false, + "consul_namespace": "ns1", + "partition": "default" + } +} +``` + +## Consul Policy Syntax + +```hcl +# Key-value access +key_prefix "" { policy = "read" } +key "specific/key" { policy = "write" } + +# Service registration +service_prefix "" { policy = "read" } +service "web" { policy = "write" } + +# Node access +node_prefix "" { policy = "read" } + +# Agent operations +agent_prefix "" { policy = "read" } +``` diff --git a/vault/hashicorp-integrations/skills/nomad-secrets/SKILL.md b/vault/hashicorp-integrations/skills/nomad-secrets/SKILL.md new file mode 100644 index 0000000..e78c779 --- /dev/null +++ b/vault/hashicorp-integrations/skills/nomad-secrets/SKILL.md @@ -0,0 +1,281 @@ +--- +name: nomad-secrets +description: Use when generating dynamic Nomad ACL tokens through Vault, configuring the Nomad secrets engine, or integrating Vault with Nomad job scheduling. Covers role mapping and credential generation. +--- + +# Nomad Secrets Engine + +Generate dynamic Nomad ACL tokens through Vault for job scheduling and cluster operations. + +## Reference + +- [Nomad Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/nomad) +- [Vault Nomad Tutorial](https://developer.hashicorp.com/nomad/tutorials/integrate-vault/vault-nomad-secrets) +- For complete role configuration and token types, see [references/nomad-secrets.md](references/nomad-secrets.md) + +## Overview + +The Nomad secrets engine generates dynamic ACL tokens that: +- Are mapped to Nomad ACL policies +- Have configurable TTLs with automatic revocation +- Support both management and client token types + +**Requirement:** Nomad 0.7.0+ with ACLs enabled. + +## Setup + +### Enable the Engine + +```bash +vault secrets enable nomad +``` + +### Bootstrap Nomad ACLs + +```bash +# If Nomad ACLs not bootstrapped yet +nomad acl bootstrap +# Accessor ID = 95a0ee55-eaa6-2c0a-a900 +# Secret ID = c25b6ca0-ea4e-000f-807a (save this!) +``` + +### Configure Vault Access + +```bash +# Using bootstrap or management token +vault write nomad/config/access \ + address="http://127.0.0.1:4646" \ + token="$NOMAD_MANAGEMENT_TOKEN" + +# With TLS +vault write nomad/config/access \ + address="https://nomad.example.com:4646" \ + token="$NOMAD_MANAGEMENT_TOKEN" \ + ca_cert="@/path/to/ca.crt" +``` + +### Configure Lease Settings + +```bash +vault write nomad/config/lease \ + ttl=3600 \ + max_ttl=86400 +``` + +## Role Configuration + +### Map to Single Policy + +```bash +vault write nomad/roles/deployer \ + policies="deploy" +``` + +### Map to Multiple Policies + +```bash +vault write nomad/roles/platform \ + policies="deploy,read-logs,submit-jobs" +``` + +### Global Tokens + +```bash +# For multi-region Nomad clusters +vault write nomad/roles/global-admin \ + policies="admin" \ + global=true +``` + +### Token Type + +```bash +# Client token (default) +vault write nomad/roles/app-submitter \ + policies="submit-job" \ + type="client" + +# Management token (full access) +vault write nomad/roles/nomad-admin \ + type="management" +``` + +## Generate Credentials + +```bash +# Generate token +vault read nomad/creds/deployer + +# Key Value +# lease_id nomad/creds/deployer/abc123 +# lease_duration 1h +# lease_renewable true +# accessor_id a715994d-f5fd-1194-73df +# secret_id b31fb56c-0936-5428-8c5f +``` + +### Use the Token + +```bash +# Set environment variable +export NOMAD_TOKEN=$(vault read -field=secret_id nomad/creds/deployer) + +# Submit a job +nomad job run myapp.nomad + +# Verify token +nomad acl token self +``` + +## Nomad Policy Examples + +### Read-Only Policy + +```hcl +# readonly.policy.hcl +namespace "*" { + policy = "read" +} +node { + policy = "read" +} +``` + +### Job Submitter Policy + +```hcl +# deploy.policy.hcl +namespace "default" { + policy = "write" + capabilities = ["submit-job", "read-logs", "alloc-exec"] +} +node { + policy = "read" +} +``` + +### Namespace Admin Policy + +```hcl +# ns-admin.policy.hcl +namespace "production" { + policy = "write" + capabilities = ["submit-job", "read-logs", "alloc-exec", "alloc-lifecycle"] +} +namespace "staging" { + policy = "write" +} +``` + +### Create Policies in Nomad + +```bash +nomad acl policy apply readonly readonly.policy.hcl +nomad acl policy apply deploy deploy.policy.hcl +``` + +## Integration Pattern + +``` +┌──────────┐ 1. Request creds ┌───────────┐ +│ CI/CD │ ──────────────────► │ Vault │ +│ Pipeline │ └─────┬─────┘ +└────┬─────┘ │ + │ 2. Create ACL token + │ │ + │ ▼ + │ ┌───────────┐ + │ 3. Submit job │ Nomad │ + └──────────────────────────►│ Cluster │ + └───────────┘ +``` + +## Lease Management + +### Renew Token Lease + +```bash +vault lease renew nomad/creds/deployer/abc123 +``` + +### Revoke Token + +```bash +vault lease revoke nomad/creds/deployer/abc123 +``` + +### Revoke All Tokens for Role + +```bash +vault lease revoke -prefix nomad/creds/deployer +``` + +## Multi-Region Configuration + +For federated Nomad clusters: + +```bash +# Configure region in access +vault write nomad/config/access \ + address="https://nomad.dc1.example.com:4646" \ + token="$NOMAD_TOKEN" + +# Generate global tokens +vault write nomad/roles/global-deployer \ + policies="deploy" \ + global=true +``` + +## API Examples + +### Create Role + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"policies":"deploy","type":"client"}' \ + $VAULT_ADDR/v1/nomad/roles/deployer +``` + +### Generate Credentials + +```bash +curl -X GET \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + $VAULT_ADDR/v1/nomad/creds/deployer +``` + +## CI/CD Integration + +### GitHub Actions Example + +```yaml +jobs: + deploy: + steps: + - name: Get Nomad Token + run: | + NOMAD_TOKEN=$(vault read -field=secret_id nomad/creds/deployer) + echo "NOMAD_TOKEN=$NOMAD_TOKEN" >> $GITHUB_ENV + + - name: Deploy to Nomad + run: nomad job run app.nomad +``` + +### GitLab CI Example + +```yaml +deploy: + script: + - export NOMAD_TOKEN=$(vault read -field=secret_id nomad/creds/deployer) + - nomad job run app.nomad +``` + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| "ACL support disabled" | Nomad ACLs not enabled | Enable ACLs in Nomad config | +| "Permission denied" | Vault token lacks management | Use management token for config | +| Policy not found | Policy name mismatch | Verify policy exists in Nomad | +| Token immediately invalid | Clock skew | Sync time between Vault and Nomad | diff --git a/vault/hashicorp-integrations/skills/nomad-secrets/references/nomad-secrets.md b/vault/hashicorp-integrations/skills/nomad-secrets/references/nomad-secrets.md new file mode 100644 index 0000000..e15bb65 --- /dev/null +++ b/vault/hashicorp-integrations/skills/nomad-secrets/references/nomad-secrets.md @@ -0,0 +1,103 @@ +--- +name: nomad-secrets +description: Reference documentation for Vault Nomad secrets engine configuration and role types. +--- + +# Nomad Secrets Engine Reference + +## Configuration + +### Access Configuration + +| Parameter | Description | +|-----------|-------------| +| `address` | Nomad API address | +| `token` | Nomad management token | +| `ca_cert` | CA certificate for TLS | +| `client_cert` | Client certificate for mTLS | +| `client_key` | Client private key for mTLS | + +### Lease Configuration + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `ttl` | Default lease duration | 1h | +| `max_ttl` | Maximum lease duration | 32d | + +## Role Parameters + +| Parameter | Description | +|-----------|-------------| +| `policies` | Comma-separated list of Nomad policies | +| `global` | Create token valid in all regions | +| `type` | `client` (default) or `management` | + +## API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/nomad/config/access` | Configure Nomad access | +| POST | `/nomad/config/lease` | Configure default lease | +| POST | `/nomad/roles/:name` | Create/update role | +| GET | `/nomad/roles/:name` | Read role | +| LIST | `/nomad/roles` | List roles | +| DELETE | `/nomad/roles/:name` | Delete role | +| GET | `/nomad/creds/:name` | Generate credentials | + +## Token Response + +```json +{ + "lease_id": "nomad/creds/role/abc123", + "lease_duration": 3600, + "renewable": true, + "data": { + "accessor_id": "uuid", + "secret_id": "token-value" + } +} +``` + +## Nomad Policy Syntax + +```hcl +# Namespace permissions +namespace "default" { + policy = "write" + capabilities = ["submit-job", "read-logs"] +} + +namespace "*" { + policy = "read" +} + +# Node permissions +node { + policy = "read" +} + +# Agent permissions +agent { + policy = "read" +} + +# Operator permissions +operator { + policy = "read" +} +``` + +## Nomad Capabilities + +| Capability | Description | +|------------|-------------| +| `submit-job` | Submit new jobs | +| `dispatch-job` | Dispatch parameterized jobs | +| `read-logs` | Read task logs | +| `alloc-exec` | Exec into allocations | +| `alloc-lifecycle` | Restart/stop allocations | +| `csi-write-volume` | Manage CSI volumes | +| `csi-mount-volume` | Mount CSI volumes | +| `list-jobs` | List all jobs | +| `parse-job` | Parse job files | +| `read-job` | Read job details | diff --git a/vault/hashicorp-integrations/skills/terraform-cloud-secrets/SKILL.md b/vault/hashicorp-integrations/skills/terraform-cloud-secrets/SKILL.md new file mode 100644 index 0000000..2373e37 --- /dev/null +++ b/vault/hashicorp-integrations/skills/terraform-cloud-secrets/SKILL.md @@ -0,0 +1,269 @@ +--- +name: terraform-cloud-secrets +description: Use when generating dynamic Terraform Cloud or Enterprise API tokens through Vault. Covers organization, team, and user token types with rotation and lease management. +--- + +# Terraform Cloud Secrets Engine + +Generate dynamic HCP Terraform (Terraform Cloud) and Terraform Enterprise API tokens through Vault. + +## Reference + +- [Terraform Cloud Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/terraform) +- [TFC API Tokens](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) +- For complete token types and workspace patterns, see [references/terraform-cloud-secrets.md](references/terraform-cloud-secrets.md) + +## Overview + +The Terraform Cloud secrets engine generates: +- **Organization tokens**: Full org-level access (single active token) +- **Team tokens**: Scoped to team permissions (multiple active tokens) +- **User tokens**: Scoped to user permissions (multiple active tokens) +- **Legacy team tokens**: Deprecated, single active token per team + +## Setup + +### Enable the Engine + +```bash +vault secrets enable terraform +``` + +### Configure for Terraform Cloud + +```bash +vault write terraform/config \ + token="$TFC_TOKEN" +``` + +### Configure for Terraform Enterprise + +```bash +vault write terraform/config \ + address="https://tfe.example.com" \ + token="$TFE_TOKEN" +``` + +## Token Types + +### Team Tokens (Recommended) + +Dynamic tokens scoped to a team with configurable TTL: + +```bash +# Get team ID from TFC API or UI +# Teams API: GET /organizations/{org}/teams + +# Create role +vault write terraform/role/ci-team \ + team_id="team-abc123" \ + credential_type=team \ + description="CI/CD pipeline token" \ + ttl=1h \ + max_ttl=24h + +# Generate token +vault read terraform/creds/ci-team +``` + +### User Tokens + +Dynamic tokens for a specific user: + +```bash +# Get user ID from TFC API or profile +# Account API: GET /account/details + +vault write terraform/role/my-user \ + user_id="user-xyz789" + +vault read terraform/creds/my-user +``` + +### Organization Tokens + +Single active token for organization-level operations: + +```bash +vault write terraform/role/org-admin \ + organization="my-org" \ + credential_type=organization + +# Rotate (invalidates previous token) +vault write -f terraform/rotate-role/org-admin + +# Read current token +vault read terraform/creds/org-admin +``` + +### Legacy Team Tokens (Deprecated) + +```bash +vault write terraform/role/legacy-team \ + team_id="team-abc123" \ + credential_type=team_legacy + +# Rotate (invalidates previous token) +vault write -f terraform/rotate-role/legacy-team +``` + +## Token Comparison + +| Type | Multiple Active | Auto-Expire | Use Case | +|------|-----------------|-------------|----------| +| Team | Yes | Yes (max_ttl) | CI/CD, automation | +| User | Yes | Yes (max_ttl) | Individual automation | +| Organization | No | No | Org-level admin | +| Legacy Team | No | No | Backward compatibility | + +## Role Configuration Options + +```bash +vault write terraform/role/example \ + team_id="team-abc123" \ + credential_type=team \ + description="Token description shown in TFC" \ + ttl=2h \ + max_ttl=12h +``` + +| Option | Description | +|--------|-------------| +| `team_id` | TFC team ID (for team/legacy roles) | +| `user_id` | TFC user ID (for user roles) | +| `organization` | Organization name (for org roles) | +| `credential_type` | `team`, `user`, `organization`, `team_legacy` | +| `description` | Visible in TFC token list | +| `ttl` | Lease duration | +| `max_ttl` | Maximum lease duration, sets TFC ExpiredAt | + +## Generate Credentials + +```bash +vault read terraform/creds/ci-team + +# Key Value +# lease_id terraform/creds/ci-team/abc123 +# lease_duration 1h +# lease_renewable true +# token tftk.abcdef1234567890 +# token_id at-456defghi789 +# description CI/CD pipeline token(42) +# expired_at 2024-01-15T12:00:00Z +``` + +## Use the Token + +### Environment Variable + +```bash +export TFE_TOKEN=$(vault read -field=token terraform/creds/ci-team) +terraform init +terraform plan +``` + +### Terraform Configuration + +```hcl +# main.tf +terraform { + cloud { + organization = "my-org" + workspaces { + name = "my-workspace" + } + } +} +``` + +### API Calls + +```bash +curl -H "Authorization: Bearer $(vault read -field=token terraform/creds/ci-team)" \ + https://app.terraform.io/api/v2/organizations/my-org/workspaces +``` + +## CI/CD Integration + +### GitHub Actions + +```yaml +jobs: + terraform: + steps: + - name: Get TFC Token + run: | + export TFE_TOKEN=$(vault read -field=token terraform/creds/ci-team) + echo "TFE_TOKEN=$TFE_TOKEN" >> $GITHUB_ENV + + - name: Terraform Plan + run: terraform plan +``` + +### GitLab CI + +```yaml +plan: + script: + - export TFE_TOKEN=$(vault read -field=token terraform/creds/ci-team) + - terraform init + - terraform plan +``` + +## Token Scope Recommendations + +| Use Case | Token Type | Scope | +|----------|------------|-------| +| CI/CD pipeline | Team | Team with workspace access | +| Developer automation | User | Individual user account | +| Org-level management | Organization | Full org access | +| Workspace-specific | Team | Limited team membership | + +## Lease Management + +### Renew Token + +```bash +vault lease renew terraform/creds/ci-team/abc123 +``` + +### Revoke Token + +```bash +vault lease revoke terraform/creds/ci-team/abc123 +``` + +### Rotate Stored Token (Org/Legacy) + +```bash +vault write -f terraform/rotate-role/org-admin +``` + +## API Examples + +### Create Role + +```bash +curl -X POST \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + -d '{"team_id":"team-abc123","credential_type":"team","ttl":"1h"}' \ + $VAULT_ADDR/v1/terraform/role/ci-team +``` + +### Generate Credentials + +```bash +curl -X GET \ + -H "X-Vault-Token: $VAULT_TOKEN" \ + $VAULT_ADDR/v1/terraform/creds/ci-team +``` + +## Troubleshooting + +| Issue | Cause | Resolution | +|-------|-------|------------| +| "Team not found" | Wrong team ID | Verify team ID in TFC API | +| "Unauthorized" | Config token lacks permission | Use token with team/org management | +| Token expires early | TFC ExpiredAt reached | Increase max_ttl | +| Duplicate description error | TFC requires unique descriptions | Random suffix added automatically | +| Org token invalidated | Another process rotated | Use team tokens for concurrency | diff --git a/vault/hashicorp-integrations/skills/terraform-cloud-secrets/references/terraform-cloud-secrets.md b/vault/hashicorp-integrations/skills/terraform-cloud-secrets/references/terraform-cloud-secrets.md new file mode 100644 index 0000000..2db0e7c --- /dev/null +++ b/vault/hashicorp-integrations/skills/terraform-cloud-secrets/references/terraform-cloud-secrets.md @@ -0,0 +1,106 @@ +--- +name: terraform-cloud-secrets +description: Reference documentation for Vault Terraform Cloud secrets engine token types and configuration. +--- + +# Terraform Cloud Secrets Engine Reference + +## Configuration + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `address` | TFC/TFE API address | https://app.terraform.io | +| `token` | TFC API token for configuration | Required | + +## Role Parameters + +| Parameter | Description | +|-----------|-------------| +| `credential_type` | `team`, `user`, `organization`, or `team_legacy` | +| `organization` | Organization name (for org roles) | +| `team_id` | Team ID (for team/legacy roles) | +| `user_id` | User ID (for user roles) | +| `description` | Token description (visible in TFC) | +| `ttl` | Lease duration | +| `max_ttl` | Maximum duration (sets ExpiredAt in TFC) | + +## Token Type Comparison + +| Type | Multiple Active | Auto-Expire | Vault Stores | +|------|-----------------|-------------|--------------| +| team | Yes | Yes | No (generated each time) | +| user | Yes | Yes | No (generated each time) | +| organization | No | No | Yes (stored, rotated) | +| team_legacy | No | No | Yes (stored, rotated) | + +## API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/terraform/config` | Configure TFC access | +| POST | `/terraform/role/:name` | Create/update role | +| GET | `/terraform/role/:name` | Read role | +| LIST | `/terraform/role` | List roles | +| DELETE | `/terraform/role/:name` | Delete role | +| GET | `/terraform/creds/:name` | Generate credentials | +| POST | `/terraform/rotate-role/:name` | Rotate stored token | + +## Credential Response + +```json +{ + "lease_id": "terraform/creds/role/abc123", + "lease_duration": 3600, + "renewable": true, + "data": { + "token": "tftk.abc123...", + "token_id": "at-xyz789", + "description": "Token description(42)", + "expired_at": "2024-01-16T10:00:00Z" + } +} +``` + +## Finding IDs + +### Team ID + +```bash +# Via TFC API +curl -H "Authorization: Bearer $TFC_TOKEN" \ + https://app.terraform.io/api/v2/organizations/$ORG/teams + +# Or check TFC UI: Settings > Teams > team name in URL +``` + +### User ID + +```bash +# Via TFC API (current user) +curl -H "Authorization: Bearer $TFC_TOKEN" \ + https://app.terraform.io/api/v2/account/details +``` + +### Organization Name + +```bash +# Via TFC API +curl -H "Authorization: Bearer $TFC_TOKEN" \ + https://app.terraform.io/api/v2/organizations +``` + +## Token Permissions Required + +| Role Type | Config Token Needs | +|-----------|-------------------| +| team | Team token management | +| user | User token management | +| organization | Organization token access | + +## TFC API Token Types + +| TFC Token Type | Scope | Vault Role Type | +|----------------|-------|-----------------| +| User token | User's permissions across orgs | user | +| Team token | Team's workspace permissions | team | +| Org token | Full organization access | organization | diff --git a/vault/mcp-integration/.claude-plugin/plugin.json b/vault/mcp-integration/.claude-plugin/plugin.json new file mode 100644 index 0000000..d3a5afe --- /dev/null +++ b/vault/mcp-integration/.claude-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "vault-mcp-integration", + "version": "0.1.0", + "description": "Skills for using the Vault MCP Server with Claude and other AI assistants for secrets management workflows", + "author": "HashiCorp", + "homepage": "https://github.com/hashicorp/vault-mcp-server", + "repository": "https://github.com/hashicorp/agent-skills", + "license": "MPL-2.0", + "keywords": [ + "vault", + "mcp", + "model-context-protocol", + "claude", + "ai", + "secrets", + "automation" + ], + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "VAULT_ADDR", + "-e", + "VAULT_TOKEN", + "-e", + "VAULT_NAMESPACE", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${VAULT_ADDR}", + "VAULT_TOKEN": "${VAULT_TOKEN}", + "VAULT_NAMESPACE": "${VAULT_NAMESPACE}" + } + } + } +} diff --git a/vault/mcp-integration/SPEC.md b/vault/mcp-integration/SPEC.md new file mode 100644 index 0000000..2259c56 --- /dev/null +++ b/vault/mcp-integration/SPEC.md @@ -0,0 +1,117 @@ +# Specification: vault-mcp-integration + +**Status**: Published +**Version**: 0.1.0 + +--- + +## Overview + +This plugin provides skills for using the HashiCorp Vault MCP (Model Context Protocol) Server to enable AI assistants like Claude to interact with Vault for secrets management. It covers server setup, configuration, and common workflow patterns using MCP tools. + +--- + +## User Stories + +### US-1: Developer Setting Up Vault MCP Server (P1) + +A developer wants to configure the Vault MCP Server so Claude or another AI assistant can help manage secrets in their development Vault instance. + +**Acceptance Criteria**: +1. Given a setup request, when the skill is invoked, then it provides Docker and from-source installation options. +2. Given a VS Code question, when asked about integration, then the skill provides mcp.json configuration. +3. Given a security question, when asked about production use, then the skill explains security considerations and CORS configuration. + +### US-2: Platform Engineer Configuring MCP for Team (P1) + +A platform engineer needs to configure the Vault MCP Server for team use with appropriate security controls. + +**Acceptance Criteria**: +1. Given a multi-user question, when the skill is invoked, then it explains rate limiting and session management. +2. Given a transport question, when asked about stdio vs HTTP, then the skill provides trade-offs for each mode. +3. Given a TLS question, when asked about secure connections, then the skill provides certificate configuration. + +### US-3: Developer Managing Secrets via MCP (P1) + +A developer wants to use Claude with the Vault MCP Server to create, read, and manage secrets in a KV secrets engine. + +**Acceptance Criteria**: +1. Given a KV management request, when the skill is invoked, then it provides workflow patterns for create_mount, write_secret, read_secret. +2. Given a listing question, when asked how to explore secrets, then the skill shows list_mounts and list_secrets patterns. +3. Given a cleanup question, when asked about deletion, then the skill explains delete_secret and delete_mount usage. + +### US-4: DevOps Engineer Automating Mount Management (P2) + +A DevOps engineer wants to use AI-assisted workflows to create and configure secrets engine mounts. + +**Acceptance Criteria**: +1. Given a mount creation request, when the skill is invoked, then it provides create_mount patterns for KV v1/v2. +2. Given a mount listing question, when asked about discovery, then the skill shows list_mounts usage. +3. Given a cleanup question, when asked about mount removal, then the skill explains delete_mount with warnings. + +--- + +## Functional Requirements + +| ID | Requirement | +|----|-------------| +| FR-001 | Skill MUST cover Vault MCP Server installation (Docker, source) | +| FR-002 | Skill MUST explain transport modes (stdio, StreamableHTTP) | +| FR-003 | Skill MUST cover environment variables (VAULT_ADDR, VAULT_TOKEN, VAULT_NAMESPACE) | +| FR-004 | Skill MUST include VS Code/Claude Desktop integration | +| FR-005 | Skill MUST cover rate limiting configuration | +| FR-006 | Skill MUST explain CORS and security considerations | +| FR-007 | Skill MUST cover all MCP tools: create_mount, list_mounts, delete_mount | +| FR-008 | Skill MUST cover all MCP tools: write_secret, read_secret, list_secrets, delete_secret | +| FR-009 | Skill MUST include example workflows for common tasks | +| FR-010 | Skill MUST differentiate KV v1 vs v2 patterns with MCP | + +--- + +## Skills Included + +| Skill | Description | +|-------|-------------| +| `vault-mcp-server` | Install and configure the Vault MCP Server | +| `mcp-secrets-workflows` | Use MCP tools for secrets management workflows | + +--- + +## MCP Tools Reference + +### Mount Management Tools + +| Tool | Parameters | Description | +|------|------------|-------------| +| `create_mount` | type, path, description | Create KV v1, KV v2, or PKI mount | +| `list_mounts` | (none) | List all mounts in Vault | +| `delete_mount` | path | Delete a mount | + +### Key-Value Tools + +| Tool | Parameters | Description | +|------|------------|-------------| +| `write_secret` | mount, path, key, value | Write a secret to KV mount | +| `read_secret` | mount, path | Read a secret from KV mount | +| `list_secrets` | mount, path | List secrets under a path | +| `delete_secret` | mount, path, key (optional) | Delete secret or specific key | + +--- + +## Non-Functional Requirements + +### NFR-1: Security Awareness + +Skills MUST include security notes about not using MCP server with untrusted clients or LLMs. + +### NFR-2: Local-Only Recommendation + +Skills MUST note the MCP server is intended for local development use at this stage. + +--- + +## References + +- [Vault MCP Server GitHub](https://github.com/hashicorp/vault-mcp-server) +- [Model Context Protocol](https://modelcontextprotocol.io/introduction) +- [VS Code MCP Integration](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) diff --git a/vault/mcp-integration/skills/mcp-secrets-workflows/SKILL.md b/vault/mcp-integration/skills/mcp-secrets-workflows/SKILL.md new file mode 100644 index 0000000..b6f9d49 --- /dev/null +++ b/vault/mcp-integration/skills/mcp-secrets-workflows/SKILL.md @@ -0,0 +1,295 @@ +--- +name: mcp-secrets-workflows +description: Use Vault MCP Server tools for secrets management workflows. Use when asked about managing secrets with Claude, creating KV mounts via MCP, reading/writing secrets through AI assistants, or automating Vault operations with MCP tools. Covers create_mount, list_mounts, write_secret, read_secret, list_secrets, and delete_secret tool patterns. +--- + +# MCP Secrets Workflows + +This skill covers common secrets management workflows using the Vault MCP Server tools with Claude or other AI assistants. + +## Reference + +- [Vault MCP Server GitHub](https://github.com/hashicorp/vault-mcp-server) +- [Detailed Workflows Reference](references/mcp-secrets-workflows.md) + +--- + +## When to Use This Skill + +- **Mount management**: Creating, listing, and deleting secrets engine mounts +- **Secret operations**: Writing, reading, listing, and deleting secrets +- **Workflow patterns**: Common multi-step operations with MCP tools +- **KV patterns**: Understanding KV v1 vs v2 differences with MCP + +--- + +## Prerequisites + +Before using these workflows, ensure: +1. Vault MCP Server is running and connected +2. Your Vault token has appropriate policies +3. Required secrets engines are enabled + +--- + +## Mount Management Tools + +### create_mount + +Create a new secrets engine mount. + +**Parameters:** +- `type` (required): Mount type - `kv`, `kv2`, `pki` +- `path` (required): Mount path +- `description` (optional): Description for the mount + +**Example Prompts:** +``` +"Create a KV v2 secrets engine at path 'myapp'" +"Set up a new KV mount called 'team-secrets' with description 'Team A secrets'" +``` + +**Workflow:** +``` +1. Tool: create_mount + - type: "kv2" + - path: "myapp" + - description: "Application secrets for MyApp" +``` + +### list_mounts + +List all secrets engine mounts. + +**Parameters:** None + +**Example Prompts:** +``` +"Show me all the secrets engines in Vault" +"What mounts are available?" +``` + +### delete_mount + +Delete a secrets engine mount. + +**Parameters:** +- `path` (required): Path of mount to delete + +> **Warning**: This permanently deletes all secrets in the mount! + +**Example Prompts:** +``` +"Delete the secrets engine at path 'old-app'" +"Remove the mount called 'deprecated'" +``` + +--- + +## Key-Value Secret Tools + +### write_secret + +Write a secret to a KV mount. + +**Parameters:** +- `mount` (required): Mount path +- `path` (required): Secret path within mount +- `key` (required): Key name +- `value` (required): Value to store + +**Example Prompts:** +``` +"Store API key 'abc123' at myapp/config" +"Write database password 'secret' to myapp/db-creds" +``` + +**Workflow:** +``` +1. Tool: write_secret + - mount: "myapp" + - path: "config" + - key: "api_key" + - value: "abc123" +``` + +### read_secret + +Read a secret from a KV mount. + +**Parameters:** +- `mount` (required): Mount path +- `path` (required): Secret path within mount + +**Example Prompts:** +``` +"Read the secrets at myapp/config" +"Get the database credentials from myapp/db-creds" +``` + +### list_secrets + +List secrets under a path. + +**Parameters:** +- `mount` (required): Mount path +- `path` (optional): Path to list (defaults to root) + +**Example Prompts:** +``` +"List all secrets in myapp" +"Show what's under myapp/databases/" +``` + +### delete_secret + +Delete a secret or specific key. + +**Parameters:** +- `mount` (required): Mount path +- `path` (required): Secret path +- `key` (optional): Specific key to delete (if omitted, deletes entire secret) + +**Example Prompts:** +``` +"Delete the secret at myapp/old-config" +"Remove the 'deprecated_key' from myapp/config" +``` + +--- + +## Common Workflow Patterns + +### Pattern 1: Bootstrap New Application + +Complete workflow for setting up secrets for a new application: + +``` +Step 1: Create a dedicated KV mount + Tool: create_mount + - type: "kv2" + - path: "newapp" + - description: "NewApp production secrets" + +Step 2: Write initial secrets + Tool: write_secret (multiple calls) + - mount: "newapp", path: "config", key: "api_key", value: "" + - mount: "newapp", path: "config", key: "secret_key", value: "" + - mount: "newapp", path: "database", key: "connection_string", value: "" + +Step 3: Verify secrets were written + Tool: list_secrets + - mount: "newapp" +``` + +### Pattern 2: Audit Existing Secrets + +Discover and review secrets in a mount: + +``` +Step 1: List all mounts to find target + Tool: list_mounts + +Step 2: List secrets in target mount + Tool: list_secrets + - mount: "myapp" + +Step 3: Read specific secrets (iterate through paths) + Tool: read_secret + - mount: "myapp", path: "config" + - mount: "myapp", path: "database" +``` + +### Pattern 3: Rotate a Secret + +Update an existing secret value: + +``` +Step 1: Read current secret to verify path + Tool: read_secret + - mount: "myapp" + - path: "config" + +Step 2: Write new value (KV v2 creates new version) + Tool: write_secret + - mount: "myapp" + - path: "config" + - key: "api_key" + - value: "" + +Step 3: Verify update + Tool: read_secret + - mount: "myapp" + - path: "config" +``` + +### Pattern 4: Clean Up Deprecated Secrets + +Remove old secrets systematically: + +``` +Step 1: List secrets to identify targets + Tool: list_secrets + - mount: "legacy-app" + +Step 2: Delete individual secrets + Tool: delete_secret + - mount: "legacy-app" + - path: "old-config" + +Step 3: Optionally delete entire mount + Tool: delete_mount + - path: "legacy-app" +``` + +--- + +## KV v1 vs KV v2 Differences + +| Aspect | KV v1 | KV v2 | +|--------|-------|-------| +| Versioning | No | Yes (keeps history) | +| Delete behavior | Permanent | Soft delete (can undelete) | +| Metadata | No | Yes (custom_metadata) | +| Check-and-set | No | Yes (cas parameter) | + +When using MCP tools: +- Both versions use the same tool parameters +- KV v2 automatically versions writes +- Delete on KV v2 is recoverable via Vault CLI + +--- + +## Required Policies + +Ensure your Vault token has appropriate permissions: + +```hcl +# Mount management +path "sys/mounts/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +# KV v2 secrets +path "myapp/data/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "myapp/metadata/*" { + capabilities = ["list", "read", "delete"] +} +``` + +--- + +## Best Practices + +- **Least privilege**: Use tokens with minimal required permissions +- **Audit trail**: All MCP operations are logged in Vault audit log +- **KV v2 preferred**: Use versioned secrets for recoverability +- **Path conventions**: Use consistent naming (e.g., `app/environment/type`) +- **Sensitive data**: Remember LLM can see secret values - use carefully + +--- + +For detailed workflow examples and advanced patterns, see [references/mcp-secrets-workflows.md](references/mcp-secrets-workflows.md). diff --git a/vault/mcp-integration/skills/mcp-secrets-workflows/references/mcp-secrets-workflows.md b/vault/mcp-integration/skills/mcp-secrets-workflows/references/mcp-secrets-workflows.md new file mode 100644 index 0000000..725dc04 --- /dev/null +++ b/vault/mcp-integration/skills/mcp-secrets-workflows/references/mcp-secrets-workflows.md @@ -0,0 +1,498 @@ +--- +name: mcp-secrets-workflows-reference +description: Detailed reference for Vault MCP Server tool usage patterns and common secrets management workflows +--- + +# MCP Secrets Workflows Reference + +This reference provides detailed patterns for using Vault MCP Server tools. + +--- + +## MCP Tools Reference + +### Mount Management Tools + +#### create_mount + +Creates a new secrets engine mount in Vault. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `type` | string | Yes | Mount type: `kv`, `kv2`, `pki` | +| `path` | string | Yes | Mount path (no leading/trailing slashes) | +| `description` | string | No | Human-readable description | + +**Examples:** + +``` +Create a KV v2 mount: + type: "kv2" + path: "myapp" + description: "Application secrets for MyApp" + +Create a KV v1 mount: + type: "kv" + path: "legacy-app" + +Create a PKI mount: + type: "pki" + path: "pki-internal" +``` + +**Notes:** +- Mount paths must be unique +- Cannot create mounts at reserved paths (sys/, auth/, etc.) +- Type `kv2` is recommended over `kv` for versioning + +--- + +#### list_mounts + +Lists all secrets engine mounts in Vault. + +**Parameters:** None + +**Response includes:** +- Mount path +- Type +- Description +- Configuration + +**Usage:** +``` +"What secrets engines are available?" +"List all mounts" +"Show me the secrets engines" +``` + +--- + +#### delete_mount + +Deletes a secrets engine mount. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `path` | string | Yes | Mount path to delete | + +**Warning:** This permanently deletes all secrets stored in the mount! + +**Examples:** + +``` +Delete a mount: + path: "old-app" +``` + +**Notes:** +- Requires appropriate permissions +- Cannot be undone +- All secrets in mount are permanently deleted + +--- + +### Key-Value Tools + +#### write_secret + +Writes a key-value pair to a secret path. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `mount` | string | Yes | Mount path | +| `path` | string | Yes | Secret path within mount | +| `key` | string | Yes | Key name | +| `value` | string | Yes | Value to store | + +**Examples:** + +``` +Write a single key: + mount: "myapp" + path: "config" + key: "api_key" + value: "sk_live_abc123" + +Write to nested path: + mount: "myapp" + path: "databases/postgres" + key: "password" + value: "secretpassword" +``` + +**Notes:** +- KV v2: Creates new version, preserves history +- KV v1: Overwrites existing value +- Multiple keys require multiple write_secret calls + +--- + +#### read_secret + +Reads a secret from a path. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `mount` | string | Yes | Mount path | +| `path` | string | Yes | Secret path within mount | + +**Examples:** + +``` +Read a secret: + mount: "myapp" + path: "config" + +Read nested path: + mount: "myapp" + path: "databases/postgres" +``` + +**Response includes:** +- All key-value pairs at the path +- Metadata (KV v2): version, created_time, etc. + +--- + +#### list_secrets + +Lists secret paths under a given path. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `mount` | string | Yes | Mount path | +| `path` | string | No | Path to list (defaults to root) | + +**Examples:** + +``` +List all secrets in mount: + mount: "myapp" + +List under specific path: + mount: "myapp" + path: "databases" +``` + +**Notes:** +- Returns paths, not secret values +- Paths ending with `/` are directories +- Useful for discovery + +--- + +#### delete_secret + +Deletes a secret or specific key. + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `mount` | string | Yes | Mount path | +| `path` | string | Yes | Secret path | +| `key` | string | No | Specific key to delete | + +**Examples:** + +``` +Delete entire secret: + mount: "myapp" + path: "old-config" + +Delete specific key: + mount: "myapp" + path: "config" + key: "deprecated_key" +``` + +**Notes:** +- KV v2: Soft delete (can be undeleted via Vault CLI) +- KV v1: Permanent delete +- Without `key`: deletes entire secret +- With `key`: deletes only that key + +--- + +## Complete Workflow Examples + +### Example 1: New Application Setup + +Complete workflow for bootstrapping secrets for a new application. + +**Goal:** Set up secrets infrastructure for "payments-service" + +**Step-by-step:** + +``` +Step 1: Create dedicated mount + Tool: create_mount + Parameters: + type: "kv2" + path: "payments-service" + description: "Secrets for payments microservice" + +Step 2: Write database credentials + Tool: write_secret + Parameters: + mount: "payments-service" + path: "database/postgres" + key: "host" + value: "postgres.internal.example.com" + + Tool: write_secret + Parameters: + mount: "payments-service" + path: "database/postgres" + key: "username" + value: "payments_app" + + Tool: write_secret + Parameters: + mount: "payments-service" + path: "database/postgres" + key: "password" + value: "generated-secure-password" + +Step 3: Write API keys + Tool: write_secret + Parameters: + mount: "payments-service" + path: "integrations/stripe" + key: "secret_key" + value: "sk_live_xxx" + + Tool: write_secret + Parameters: + mount: "payments-service" + path: "integrations/stripe" + key: "webhook_secret" + value: "whsec_xxx" + +Step 4: Verify setup + Tool: list_secrets + Parameters: + mount: "payments-service" +``` + +--- + +### Example 2: Secret Rotation + +Update existing secrets while maintaining audit trail. + +**Goal:** Rotate database password for an application + +**Step-by-step:** + +``` +Step 1: Read current secret (verify path) + Tool: read_secret + Parameters: + mount: "myapp" + path: "database" + +Step 2: Write new password (KV v2 creates new version) + Tool: write_secret + Parameters: + mount: "myapp" + path: "database" + key: "password" + value: "new-secure-password-2024" + +Step 3: Verify update + Tool: read_secret + Parameters: + mount: "myapp" + path: "database" +``` + +**Note:** Previous version remains accessible via Vault CLI for rollback. + +--- + +### Example 3: Secrets Discovery and Audit + +Explore existing secrets structure. + +**Goal:** Understand what secrets exist in a mount + +**Step-by-step:** + +``` +Step 1: List all mounts + Tool: list_mounts + +Step 2: List top-level secrets + Tool: list_secrets + Parameters: + mount: "myapp" + +Step 3: Explore subdirectories + Tool: list_secrets + Parameters: + mount: "myapp" + path: "databases" + +Step 4: Read specific secrets + Tool: read_secret + Parameters: + mount: "myapp" + path: "databases/postgres" +``` + +--- + +### Example 4: Cleanup Deprecated Secrets + +Remove old secrets systematically. + +**Goal:** Clean up secrets for decommissioned application + +**Step-by-step:** + +``` +Step 1: Audit existing secrets + Tool: list_secrets + Parameters: + mount: "old-app" + +Step 2: Document secrets (for backup purposes) + Tool: read_secret (for each path) + +Step 3: Delete individual secrets + Tool: delete_secret + Parameters: + mount: "old-app" + path: "config" + + Tool: delete_secret + Parameters: + mount: "old-app" + path: "database" + +Step 4: Delete the mount + Tool: delete_mount + Parameters: + path: "old-app" +``` + +**Warning:** Ensure secrets are no longer needed before deletion! + +--- + +## KV v1 vs KV v2 Behavior + +### Write Behavior + +| Aspect | KV v1 | KV v2 | +|--------|-------|-------| +| Write same path | Overwrites | Creates new version | +| History | None | Full version history | +| Rollback | Not possible | Restore previous version | + +### Delete Behavior + +| Aspect | KV v1 | KV v2 | +|--------|-------|-------| +| Default delete | Permanent | Soft delete | +| Recovery | Not possible | Undelete via CLI | +| Permanent delete | Same as delete | Requires "destroy" | + +### Path Differences + +``` +KV v1 API path: secret/myapp/config +KV v2 API path: secret/data/myapp/config + +MCP tools abstract this difference - use: + mount: "secret" + path: "myapp/config" +``` + +--- + +## Error Handling + +### Common Errors + +| Error | Cause | Solution | +|-------|-------|----------| +| "permission denied" | Token lacks policy | Update token policy | +| "no route to host" | Vault unreachable | Check VAULT_ADDR | +| "mount does not exist" | Invalid mount path | Use list_mounts to find | +| "secret not found" | Path doesn't exist | Use list_secrets to explore | + +### Required Policies + +```hcl +# Policy for full MCP access +path "sys/mounts" { + capabilities = ["read", "list"] +} + +path "sys/mounts/*" { + capabilities = ["create", "delete", "read", "list"] +} + +# For KV v2 secrets +path "+/data/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} + +path "+/metadata/*" { + capabilities = ["read", "list", "delete"] +} +``` + +--- + +## Best Practices + +### Security + +1. **Minimal permissions**: Use tokens with only required capabilities +2. **Sensitive awareness**: Remember LLM can see secret values +3. **Audit logging**: All operations are logged in Vault audit log +4. **Short TTLs**: Use short-lived tokens for MCP sessions + +### Organization + +1. **Consistent naming**: Use pattern like `app/environment/type` +2. **Logical grouping**: Group related secrets under same path +3. **Documentation**: Use mount descriptions for discoverability +4. **KV v2 preferred**: Enable versioning for recoverability + +### Workflow + +1. **Verify before delete**: Always list/read before deleting +2. **Test in dev**: Practice workflows in development first +3. **Backup sensitive**: Document critical secrets before changes +4. **Incremental changes**: Make small, verifiable changes + +--- + +## Additional Resources + +- [Vault MCP Server GitHub](https://github.com/hashicorp/vault-mcp-server) +- [KV Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/kv) +- [Vault Policies](https://developer.hashicorp.com/vault/docs/concepts/policies) + +--- + +## Related + +- [vault-mcp-server.md](../vault-mcp-server/references/vault-mcp-server.md) - MCP server configuration +- [secrets-engines.md](../../../secrets-management/skills/secrets-engines/references/secrets-engines.md) - Secrets engine configuration +- [policies.md](../../../authentication/skills/policies/references/policies.md) - Policy syntax diff --git a/vault/mcp-integration/skills/vault-mcp-server/SKILL.md b/vault/mcp-integration/skills/vault-mcp-server/SKILL.md new file mode 100644 index 0000000..dd5f641 --- /dev/null +++ b/vault/mcp-integration/skills/vault-mcp-server/SKILL.md @@ -0,0 +1,266 @@ +--- +name: vault-mcp-server +description: Install and configure the Vault MCP Server for AI-assisted secrets management. Use when asked about setting up MCP for Vault, configuring Claude or VS Code to use Vault, or integrating AI assistants with HashiCorp Vault. Covers Docker setup, transport modes, environment variables, and security configuration. +--- + +# Vault MCP Server + +The Vault MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) server that enables AI assistants like Claude to interact with HashiCorp Vault for secrets management. + +## Reference + +- [Vault MCP Server GitHub](https://github.com/hashicorp/vault-mcp-server) +- [Detailed MCP Server Reference](references/vault-mcp-server.md) + +--- + +## When to Use This Skill + +- **Setup**: Installing Vault MCP Server via Docker or from source +- **VS Code**: Configuring mcp.json for VS Code integration +- **Claude Desktop**: Setting up Claude to use Vault +- **Security**: Understanding CORS, rate limiting, and TLS options +- **Troubleshooting**: Debugging MCP server connectivity + +--- + +## Security Notes + +> **Warning**: The MCP server is intended for local development use. The server may expose Vault data to the connected MCP client and LLM. Do not use with untrusted MCP clients or LLMs. + +> **Important**: If using StreamableHTTP transport, always configure `MCP_ALLOWED_ORIGINS` to prevent DNS rebinding attacks. + +--- + +## Quick Start (Docker) + +```bash +# Start Vault MCP Server with Docker +docker run -i --rm \ + -e VAULT_ADDR='http://host.docker.internal:8200' \ + -e VAULT_TOKEN='' \ + hashicorp/vault-mcp-server +``` + +--- + +## Installation Options + +### Docker (Recommended) + +```bash +# Pull the official image +docker pull hashicorp/vault-mcp-server + +# Run in stdio mode (for Claude Desktop, VS Code) +docker run -i --rm \ + -e VAULT_ADDR='http://host.docker.internal:8200' \ + -e VAULT_TOKEN='' \ + -e VAULT_NAMESPACE='admin' \ + hashicorp/vault-mcp-server + +# Run in HTTP mode +docker run --rm -p 8080:8080 \ + -e VAULT_ADDR='http://vault:8200' \ + -e VAULT_TOKEN='' \ + -e TRANSPORT_MODE='http' \ + -e MCP_ALLOWED_ORIGINS='http://localhost:3000' \ + hashicorp/vault-mcp-server +``` + +### From Source + +```bash +git clone https://github.com/hashicorp/vault-mcp-server.git +cd vault-mcp-server + +# Build +make build + +# Run stdio mode +./vault-mcp-server + +# Run HTTP mode +./vault-mcp-server http --transport-port 8080 +``` + +--- + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `VAULT_ADDR` | `http://127.0.0.1:8200` | Vault server address | +| `VAULT_TOKEN` | (required) | Vault authentication token | +| `VAULT_NAMESPACE` | (optional) | Vault Enterprise namespace | +| `TRANSPORT_MODE` | `stdio` | `stdio` or `http` | +| `TRANSPORT_HOST` | `127.0.0.1` | HTTP bind host | +| `TRANSPORT_PORT` | `8080` | HTTP bind port | +| `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path | +| `MCP_ALLOWED_ORIGINS` | `""` | CORS allowed origins (comma-separated) | +| `MCP_CORS_MODE` | `strict` | `strict`, `development`, or `disabled` | +| `MCP_TLS_CERT_FILE` | `""` | TLS certificate path | +| `MCP_TLS_KEY_FILE` | `""` | TLS key path | +| `MCP_RATE_LIMIT_GLOBAL` | `10:20` | Global rate limit (rps:burst) | +| `MCP_RATE_LIMIT_SESSION` | `5:10` | Per-session rate limit (rps:burst) | + +--- + +## VS Code Integration + +Create `.vscode/mcp.json` in your workspace: + +### Stdio Mode (Recommended) + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "vault_addr", + "description": "Vault Address", + "password": false + }, + { + "type": "promptString", + "id": "vault_token", + "description": "Vault Token", + "password": true + } + ], + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-e", "VAULT_ADDR=${input:vault_addr}", + "-e", "VAULT_TOKEN=${input:vault_token}", + "hashicorp/vault-mcp-server" + ] + } + } +} +``` + +### HTTP Mode + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "vault_token", + "description": "Vault Token", + "password": true + } + ], + "servers": { + "vault-mcp-server": { + "url": "http://localhost:8080/mcp?VAULT_ADDR=http://127.0.0.1:8200", + "headers": { + "X-Vault-Token": "${input:vault_token}" + } + } + } +} +``` + +--- + +## Transport Modes + +### Stdio Mode (Default) + +- Used by Claude Desktop, VS Code with Docker +- MCP server runs as subprocess +- Communication via stdin/stdout +- Best for local development + +### StreamableHTTP Mode + +- Server runs as HTTP service +- Multiple clients can connect +- Requires CORS configuration for security +- Use for shared development environments + +--- + +## Rate Limiting + +Control request rates to protect your Vault server: + +```bash +# Global: 10 requests/second, burst of 20 +# Session: 5 requests/second, burst of 10 +docker run -i --rm \ + -e VAULT_ADDR='http://vault:8200' \ + -e VAULT_TOKEN='' \ + -e MCP_RATE_LIMIT_GLOBAL='10:20' \ + -e MCP_RATE_LIMIT_SESSION='5:10' \ + hashicorp/vault-mcp-server +``` + +--- + +## TLS Configuration + +For secure HTTP transport: + +```bash +docker run --rm -p 8443:8443 \ + -v /path/to/certs:/certs:ro \ + -e TRANSPORT_MODE='http' \ + -e TRANSPORT_PORT='8443' \ + -e MCP_TLS_CERT_FILE='/certs/cert.pem' \ + -e MCP_TLS_KEY_FILE='/certs/key.pem' \ + hashicorp/vault-mcp-server +``` + +--- + +## Available MCP Tools + +Once connected, the following tools are available: + +| Tool | Description | +|------|-------------| +| `create_mount` | Create KV, KV v2, or PKI mount | +| `list_mounts` | List all mounts | +| `delete_mount` | Delete a mount | +| `write_secret` | Write secret to KV mount | +| `read_secret` | Read secret from KV mount | +| `list_secrets` | List secrets in path | +| `delete_secret` | Delete secret or key | + +For detailed tool usage patterns, see [mcp-secrets-workflows](../mcp-secrets-workflows/SKILL.md). + +--- + +## Troubleshooting + +### Connection Refused + +```bash +# Check Vault is accessible +curl $VAULT_ADDR/v1/sys/health + +# For Docker, use host.docker.internal (macOS/Windows) +# or --network=host (Linux) +docker run --network=host -i --rm \ + -e VAULT_ADDR='http://127.0.0.1:8200' \ + hashicorp/vault-mcp-server +``` + +### Token Errors + +```bash +# Verify token is valid +vault token lookup + +# Check token has required policies +vault token capabilities $VAULT_TOKEN sys/mounts +``` + +--- + +For detailed configuration examples and advanced patterns, see [references/vault-mcp-server.md](references/vault-mcp-server.md). diff --git a/vault/mcp-integration/skills/vault-mcp-server/references/vault-mcp-server.md b/vault/mcp-integration/skills/vault-mcp-server/references/vault-mcp-server.md new file mode 100644 index 0000000..73f34f2 --- /dev/null +++ b/vault/mcp-integration/skills/vault-mcp-server/references/vault-mcp-server.md @@ -0,0 +1,441 @@ +--- +name: vault-mcp-server-reference +description: Detailed configuration reference for the Vault MCP Server including installation, transport modes, environment variables, and IDE integration +--- + +# Vault MCP Server Reference + +This reference provides detailed configuration for the HashiCorp Vault MCP Server. + +--- + +## Overview + +The Vault MCP Server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to enable AI assistants to interact with HashiCorp Vault. It supports both stdio and StreamableHTTP transports. + +--- + +## Installation + +### Docker (Recommended) + +```bash +# Pull latest image +docker pull hashicorp/vault-mcp-server + +# Verify installation +docker run --rm hashicorp/vault-mcp-server --version +``` + +### From Source + +```bash +# Clone repository +git clone https://github.com/hashicorp/vault-mcp-server.git +cd vault-mcp-server + +# Build (requires Go 1.24+) +make build + +# Build Docker image +make docker-build + +# Build with custom registry +make docker-build DOCKER_REGISTRY=your-registry.com +``` + +--- + +## Transport Modes + +### Stdio Mode (Default) + +Standard input/output mode for subprocess communication. + +```bash +# Run in stdio mode +./vault-mcp-server +# or explicitly +./vault-mcp-server stdio + +# With Docker +docker run -i --rm \ + -e VAULT_ADDR='http://host.docker.internal:8200' \ + -e VAULT_TOKEN='' \ + hashicorp/vault-mcp-server +``` + +**When to use:** +- Claude Desktop integration +- VS Code with Docker +- Local development +- Single-user scenarios + +### StreamableHTTP Mode + +HTTP server mode for multi-client access. + +```bash +# Run in HTTP mode +./vault-mcp-server http --transport-port 8080 + +# With Docker +docker run --rm -p 8080:8080 \ + -e TRANSPORT_MODE='http' \ + -e TRANSPORT_PORT='8080' \ + -e VAULT_ADDR='http://vault:8200' \ + -e VAULT_TOKEN='' \ + hashicorp/vault-mcp-server +``` + +**When to use:** +- Shared development environments +- Multiple clients connecting +- Custom tooling integration + +--- + +## Environment Variables Reference + +### Vault Connection + +| Variable | Default | Required | Description | +|----------|---------|----------|-------------| +| `VAULT_ADDR` | `http://127.0.0.1:8200` | No | Vault server URL | +| `VAULT_TOKEN` | - | **Yes** | Authentication token | +| `VAULT_NAMESPACE` | - | No | Enterprise namespace | + +### Transport Configuration + +| Variable | Default | Description | +|----------|---------|-------------| +| `TRANSPORT_MODE` | `stdio` | `stdio` or `http` | +| `TRANSPORT_HOST` | `127.0.0.1` | HTTP bind address | +| `TRANSPORT_PORT` | `8080` | HTTP bind port | +| `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path | + +### Security Configuration + +| Variable | Default | Description | +|----------|---------|-------------| +| `MCP_ALLOWED_ORIGINS` | `""` | CORS allowed origins (comma-separated) | +| `MCP_CORS_MODE` | `strict` | `strict`, `development`, `disabled` | +| `MCP_TLS_CERT_FILE` | `""` | TLS certificate file path | +| `MCP_TLS_KEY_FILE` | `""` | TLS private key file path | + +### Rate Limiting + +| Variable | Default | Description | +|----------|---------|-------------| +| `MCP_RATE_LIMIT_GLOBAL` | `10:20` | Global limit (requests/sec:burst) | +| `MCP_RATE_LIMIT_SESSION` | `5:10` | Per-session limit (requests/sec:burst) | + +--- + +## IDE Integration + +### Visual Studio Code + +Create `.vscode/mcp.json` in your workspace: + +#### Stdio Mode with Docker + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "vault_addr", + "description": "Vault Address (e.g., http://127.0.0.1:8200)", + "password": false + }, + { + "type": "promptString", + "id": "vault_token", + "description": "Vault Token", + "password": true + }, + { + "type": "promptString", + "id": "vault_namespace", + "description": "Vault Namespace (optional)", + "password": false + } + ], + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-e", "VAULT_ADDR=${input:vault_addr}", + "-e", "VAULT_TOKEN=${input:vault_token}", + "-e", "VAULT_NAMESPACE=${input:vault_namespace}", + "hashicorp/vault-mcp-server" + ] + } + } +} +``` + +#### HTTP Mode + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "vault_token", + "description": "Vault Token", + "password": true + }, + { + "type": "promptString", + "id": "vault_namespace", + "description": "Vault Namespace (optional)", + "password": false + } + ], + "servers": { + "vault-mcp-server": { + "url": "http://localhost:8080/mcp?VAULT_ADDR=http://127.0.0.1:8200", + "headers": { + "X-Vault-Token": "${input:vault_token}", + "X-Vault-Namespace": "${input:vault_namespace}" + } + } + } +} +``` + +### Claude Desktop + +Add to Claude Desktop configuration: + +```json +{ + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-e", "VAULT_ADDR=http://host.docker.internal:8200", + "-e", "VAULT_TOKEN=", + "hashicorp/vault-mcp-server" + ] + } + } +} +``` + +### Gemini Extensions + +```bash +# Create environment file +cat > ~/.gemini/.env << EOF +VAULT_ADDR=http://127.0.0.1:8200 +VAULT_TOKEN= +VAULT_NAMESPACE=admin +EOF + +# Install and run +gemini extensions install https://github.com/hashicorp/vault-mcp-server +gemini +``` + +--- + +## HTTP Mode Configuration Details + +### CORS Configuration + +```bash +# Strict mode (default) - requires explicit origins +docker run -p 8080:8080 \ + -e TRANSPORT_MODE='http' \ + -e MCP_CORS_MODE='strict' \ + -e MCP_ALLOWED_ORIGINS='http://localhost:3000,https://myapp.example.com' \ + hashicorp/vault-mcp-server + +# Development mode - allows localhost automatically +docker run -p 8080:8080 \ + -e TRANSPORT_MODE='http' \ + -e MCP_CORS_MODE='development' \ + hashicorp/vault-mcp-server + +# Disabled - no CORS headers (not recommended) +docker run -p 8080:8080 \ + -e TRANSPORT_MODE='http' \ + -e MCP_CORS_MODE='disabled' \ + hashicorp/vault-mcp-server +``` + +### TLS Configuration + +```bash +# Generate self-signed certificate (development) +openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes + +# Run with TLS +docker run -p 8443:8443 \ + -v $(pwd)/certs:/certs:ro \ + -e TRANSPORT_MODE='http' \ + -e TRANSPORT_PORT='8443' \ + -e MCP_TLS_CERT_FILE='/certs/cert.pem' \ + -e MCP_TLS_KEY_FILE='/certs/key.pem' \ + hashicorp/vault-mcp-server +``` + +### Rate Limiting + +```bash +# Configure rate limits +# Format: requests_per_second:burst_size +docker run -p 8080:8080 \ + -e TRANSPORT_MODE='http' \ + -e MCP_RATE_LIMIT_GLOBAL='20:50' \ + -e MCP_RATE_LIMIT_SESSION='10:25' \ + hashicorp/vault-mcp-server +``` + +--- + +## Vault Configuration in HTTP Mode + +In HTTP mode, Vault configuration can be provided through multiple methods (in order of precedence): + +1. **HTTP Query Parameters**: `?VAULT_ADDR=...` +2. **HTTP Headers**: `X-Vault-Token`, `X-Vault-Namespace` +3. **Environment Variables**: Standard Vault env vars + +### Example Request + +```bash +curl -X POST http://localhost:8080/mcp \ + -H "Content-Type: application/json" \ + -H "X-Vault-Token: hvs.xxx" \ + -H "X-Vault-Namespace: admin" \ + -d '{"method": "list_mounts"}' +``` + +--- + +## Docker Networking + +### macOS / Windows + +Use `host.docker.internal` to access host network: + +```bash +docker run -i --rm \ + -e VAULT_ADDR='http://host.docker.internal:8200' \ + hashicorp/vault-mcp-server +``` + +### Linux + +Use `--network=host` or explicit IP: + +```bash +# Option 1: Host network +docker run --network=host -i --rm \ + -e VAULT_ADDR='http://127.0.0.1:8200' \ + hashicorp/vault-mcp-server + +# Option 2: Docker network with Vault container +docker network create mcp +docker run --network=mcp -i --rm \ + -e VAULT_ADDR='http://vault:8200' \ + hashicorp/vault-mcp-server +``` + +--- + +## Security Considerations + +### Token Permissions + +Create a dedicated token with minimal permissions: + +```hcl +# Minimal policy for MCP operations +path "sys/mounts" { + capabilities = ["read", "list"] +} + +path "sys/mounts/*" { + capabilities = ["create", "delete"] +} + +path "secret/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +``` + +```bash +vault policy write mcp-user mcp-policy.hcl +vault token create -policy=mcp-user -ttl=8h +``` + +### Audit Logging + +All MCP operations are logged in Vault audit logs: + +```bash +# Enable audit logging +vault audit enable file file_path=/var/log/vault/audit.log + +# View MCP operations +grep "mcp" /var/log/vault/audit.log +``` + +--- + +## Troubleshooting + +### Connection Issues + +```bash +# Test Vault connectivity +curl $VAULT_ADDR/v1/sys/health + +# Check Docker can reach Vault +docker run --rm curlimages/curl \ + curl -s http://host.docker.internal:8200/v1/sys/health +``` + +### Token Issues + +```bash +# Verify token +vault token lookup + +# Check capabilities +vault token capabilities $VAULT_TOKEN sys/mounts +vault token capabilities $VAULT_TOKEN secret/data/test +``` + +### Debug Logging + +```bash +# Enable debug output +docker run -i --rm \ + -e VAULT_ADDR='http://host.docker.internal:8200' \ + -e VAULT_TOKEN='' \ + -e LOG_LEVEL='debug' \ + hashicorp/vault-mcp-server +``` + +--- + +## Additional Resources + +- [Vault MCP Server GitHub](https://github.com/hashicorp/vault-mcp-server) +- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification) +- [VS Code MCP Integration](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) + +--- + +## Related + +- [mcp-secrets-workflows.md](../mcp-secrets-workflows/references/mcp-secrets-workflows.md) - MCP tool usage patterns +- [auth-methods.md](../../../authentication/skills/auth-methods/references/auth-methods.md) - Token authentication diff --git a/vault/operations/.claude-plugin/plugin.json b/vault/operations/.claude-plugin/plugin.json new file mode 100644 index 0000000..1733b3d --- /dev/null +++ b/vault/operations/.claude-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "vault-operations", + "version": "0.1.0", + "description": "Skills for deploying and operating Vault. Covers Kubernetes integration (VSO, Injector, CSI), production operations, HA/DR, monitoring, and troubleshooting.", + "author": "HashiCorp", + "homepage": "https://developer.hashicorp.com/vault/docs/internals", + "repository": "https://github.com/hashicorp/agent-skills", + "license": "MPL-2.0", + "keywords": [ + "vault", + "operations", + "kubernetes", + "vso", + "vault-secrets-operator", + "ha", + "disaster-recovery", + "monitoring", + "troubleshooting", + "hashicorp" + ], + "mcpServers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "VAULT_ADDR", + "-e", + "VAULT_TOKEN", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${VAULT_ADDR}", + "VAULT_TOKEN": "${VAULT_TOKEN}" + } + } + } +} diff --git a/vault/operations/SPEC.md b/vault/operations/SPEC.md new file mode 100644 index 0000000..d9f6a01 --- /dev/null +++ b/vault/operations/SPEC.md @@ -0,0 +1,108 @@ +# Specification: vault-operations + +**Status**: Published +**Version**: 0.2.0 + +--- + +## Overview + +This plugin provides skills for deploying Vault in Kubernetes, operating production clusters, and troubleshooting issues. Covers HA architecture, disaster recovery, monitoring, upgrades, and common operational patterns. + +--- + +## User Stories + +### US-1: Platform Engineer Deploying Vault on Kubernetes (P1) + +A platform engineer needs to deploy Vault on Kubernetes and integrate it with application workloads using Vault Secrets Operator. + +**Acceptance Criteria**: +1. Given a user asks about Kubernetes deployment, when the skill is invoked, then it provides VSO, Agent Injector, or CSI options with trade-offs. +2. Given a VSO configuration question, when queried, then the skill provides VaultAuth, VaultStaticSecret, and VaultDynamicSecret CRD examples. +3. Given an Agent Injector question, when asked, then the skill explains annotation-based injection with complete annotation reference. +4. Given a selection question, when asked which to use, then the skill provides a decision matrix for VSO/CSI/Injector selection. + +### US-2: Architect Designing HA/DR Deployment (P1) + +A solutions architect needs to design a highly available Vault deployment with disaster recovery capabilities. + +**Why this priority**: Enterprise Vault deployments require HA and DR for production readiness. + +**Acceptance Criteria**: +1. Given an HA architecture question, when the skill is invoked, then it explains 5-node Raft clusters with 3-AZ distribution (2-2-1 pattern). +2. Given a DR question, when queried, then it explains replication types, DR failover procedures, and batch token portability. +3. Given an auto-unseal question, when asked about options, then the skill explains Cloud KMS, HSM, and Transit unseal with Seal HA (1.16+). +4. Given a cluster sizing question, when asked, then the skill provides instance sizing recommendations. + +### US-3: Operations Engineer Monitoring Vault (P2) + +An operations engineer needs to set up monitoring, alerting, and backup procedures for production Vault. + +**Acceptance Criteria**: +1. Given a monitoring question, when the skill is invoked, then it provides critical metrics and alert thresholds. +2. Given a backup question, when queried, then the skill explains Raft snapshots and automated backup procedures. +3. Given an upgrade question, when asked, then the skill provides Autopilot rolling upgrade procedures. +4. Given an audit question, when asked about logging, then the skill explains multiple audit devices and privileged endpoint monitoring. + +### US-4: SRE Troubleshooting Vault Issues (P1) + +An SRE needs to diagnose why Vault is returning errors, failing to authenticate clients, or responding slowly. + +**Why this priority**: Production troubleshooting is a common, high-stress scenario where accurate guidance is critical. + +**Acceptance Criteria**: +1. Given a user reports Vault errors, when the skill is invoked, then it provides systematic troubleshooting steps (seal status, leader election, storage health, audit logs). +2. Given an authentication failure, when asked for help, then the skill identifies common causes and solutions. +3. Given performance issues, when queried, then the skill suggests metrics analysis, connection pooling, and caching strategies. +4. Given an anti-patterns question, when asked, then the skill lists common operational anti-patterns to avoid. + +--- + +## Functional Requirements + +| ID | Requirement | +|----|-------------| +| FR-001 | Skill MUST cover VSO with VaultAuth, VaultStaticSecret, VaultDynamicSecret CRDs | +| FR-002 | Skill MUST cover Agent Injector with complete annotation reference | +| FR-003 | Skill MUST cover CSI Provider with SecretProviderClass | +| FR-004 | Skill MUST include VSO/CSI/Injector decision matrix | +| FR-005 | Skill MUST cover 5-node Raft HA with 3-AZ distribution | +| FR-006 | Skill MUST explain auto-unseal options (KMS, HSM, Transit) | +| FR-007 | Skill MUST cover Seal HA (1.16+) configuration | +| FR-008 | Skill MUST include DR failover procedures | +| FR-009 | Skill MUST cover Autopilot for rolling upgrades | +| FR-010 | Skill MUST cover automated Raft snapshots | +| FR-011 | Skill MUST explain critical monitoring metrics | +| FR-012 | Skill MUST cover multiple audit devices requirement | +| FR-013 | Skill MUST list privileged endpoints to monitor | +| FR-014 | Skill MUST include troubleshooting decision trees | +| FR-015 | Skill MUST cover operational anti-patterns | + +--- + +## Skills Included + +| Skill | Description | +|-------|-------------| +| `kubernetes-integration` | VSO, Agent Injector, CSI Provider configuration | +| `production-operations` | HA, DR, monitoring, backup, upgrades | +| `troubleshooting` | Diagnose seal, auth, permission, and performance issues | + +--- + +## Content Sources + +- HashiCorp Vault Documentation +- Vault Tutorials +- CSA Enterprise Patterns (genericized) + +--- + +## References + +- [Vault on Kubernetes](https://developer.hashicorp.com/vault/docs/platform/k8s) +- [Vault Secrets Operator](https://developer.hashicorp.com/vault/docs/platform/k8s/vso) +- [Vault Agent Injector](https://developer.hashicorp.com/vault/docs/platform/k8s/injector) +- [Integrated Storage (Raft)](https://developer.hashicorp.com/vault/docs/configuration/storage/raft) +- [Vault Telemetry](https://developer.hashicorp.com/vault/docs/internals/telemetry) diff --git a/vault/operations/skills/kubernetes-integration/SKILL.md b/vault/operations/skills/kubernetes-integration/SKILL.md new file mode 100644 index 0000000..46a90a7 --- /dev/null +++ b/vault/operations/skills/kubernetes-integration/SKILL.md @@ -0,0 +1,208 @@ +--- +name: kubernetes-integration +description: Integrate Vault with Kubernetes. Use when asked about Vault Secrets Operator (VSO), Agent Injector, CSI Provider, Kubernetes auth, syncing secrets to Kubernetes, or pod-level secret injection patterns. +--- + +# Vault Kubernetes Integration + +Vault provides three primary methods for delivering secrets to Kubernetes workloads: Vault Secrets Operator (VSO), Agent Injector, and CSI Provider. Each has different trade-offs for security, complexity, and use cases. + +## Reference + +- [Vault Kubernetes Documentation](https://developer.hashicorp.com/vault/docs/platform/k8s) +- [Detailed Kubernetes Reference](references/kubernetes.md) + +--- + +## When to Use This Skill + +- **VSO (Vault Secrets Operator)**: Kubernetes-native secret sync to K8s Secrets +- **Agent Injector**: Sidecar-based secret injection via annotations +- **CSI Provider**: Mount secrets as ephemeral volumes +- **Kubernetes auth**: Configure pods to authenticate with Vault +- **Secret rotation**: Automatic secret updates in running pods + +--- + +## Method Comparison + +| Feature | VSO | Agent Injector | CSI Provider | +|---------|-----|----------------|--------------| +| Secret storage | K8s Secret | In-memory files | Ephemeral volume | +| Rotation | Automatic | Automatic | Manual restart | +| Complexity | Low | Medium | Low | +| Resource overhead | Controller only | Sidecar per pod | DaemonSet | +| Best for | K8s-native apps | Legacy apps | Security-conscious | + +--- + +## Vault Secrets Operator (VSO) - Recommended + +VSO syncs Vault secrets to native Kubernetes Secrets. + +### Installation + +```bash +helm repo add hashicorp https://helm.releases.hashicorp.com +helm install vault-secrets-operator hashicorp/vault-secrets-operator \ + --namespace vault-secrets-operator-system \ + --create-namespace +``` + +### Configure Authentication + +```yaml +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultAuth +metadata: + name: vault-auth +spec: + method: kubernetes + mount: kubernetes + kubernetes: + role: my-app + serviceAccount: my-app-sa + vaultConnectionRef: vault-connection +``` + +### Sync Static Secrets + +```yaml +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultStaticSecret +metadata: + name: my-app-secrets +spec: + vaultAuthRef: vault-auth + mount: secret + path: myapp/config + type: kv-v2 + refreshAfter: 60s + destination: + name: my-app-secret + create: true +``` + +### Sync Dynamic Secrets + +```yaml +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultDynamicSecret +metadata: + name: db-creds +spec: + vaultAuthRef: vault-auth + mount: database + path: creds/readonly + destination: + name: db-credentials + create: true + renewalPercent: 67 +``` + +--- + +## Agent Injector + +Injects secrets via sidecar container using annotations. + +### Installation + +```bash +helm install vault hashicorp/vault \ + --set "injector.enabled=true" \ + --set "server.enabled=false" +``` + +### Pod Annotations + +```yaml +apiVersion: v1 +kind: Pod +metadata: + annotations: + vault.hashicorp.com/agent-inject: "true" + vault.hashicorp.com/role: "my-app" + vault.hashicorp.com/agent-inject-secret-config.txt: "secret/data/myapp/config" +spec: + serviceAccountName: my-app-sa + containers: + - name: app + image: myapp:latest + volumeMounts: + - name: vault-secrets + mountPath: /vault/secrets + readOnly: true +``` + +### Template Annotations + +```yaml +annotations: + vault.hashicorp.com/agent-inject: "true" + vault.hashicorp.com/role: "my-app" + vault.hashicorp.com/agent-inject-secret-config.txt: "secret/data/myapp/config" + vault.hashicorp.com/agent-inject-template-config.txt: | + {{- with secret "secret/data/myapp/config" -}} + DB_HOST={{ .Data.data.host }} + DB_USER={{ .Data.data.username }} + DB_PASS={{ .Data.data.password }} + {{- end }} +``` + +--- + +## CSI Provider + +Mounts secrets as ephemeral volumes. + +### SecretProviderClass + +```yaml +apiVersion: secrets-store.csi.x-k8s.io/v1 +kind: SecretProviderClass +metadata: + name: vault-db-creds +spec: + provider: vault + parameters: + vaultAddress: "https://vault.example.com:8200" + roleName: "my-app" + objects: | + - objectName: "db-password" + secretPath: "secret/data/myapp/db" + secretKey: "password" +``` + +### Pod Usage + +```yaml +spec: + containers: + - name: app + volumeMounts: + - name: secrets-store + mountPath: "/mnt/secrets" + readOnly: true + volumes: + - name: secrets-store + csi: + driver: secrets-store.csi.k8s.io + readOnly: true + volumeAttributes: + secretProviderClass: vault-db-creds +``` + +--- + +## Best Practices + +- **Use VSO** for new Kubernetes-native applications +- **Use Agent Injector** for legacy apps or complex templating +- **Use CSI Provider** when K8s Secrets are not acceptable +- **Enable Kubernetes auth** in Vault for all methods +- **Use separate service accounts** per application role + +--- + +For complete configurations including RBAC setup, multi-cluster patterns, and troubleshooting, see [references/kubernetes.md](references/kubernetes.md). diff --git a/vault/operations/skills/kubernetes-integration/references/kubernetes.md b/vault/operations/skills/kubernetes-integration/references/kubernetes.md new file mode 100644 index 0000000..4a0615c --- /dev/null +++ b/vault/operations/skills/kubernetes-integration/references/kubernetes.md @@ -0,0 +1,638 @@ +--- +name: vault-kubernetes +description: Comprehensive guidance on Vault Kubernetes integration including VSO, Agent Injector, and CSI Provider +--- + +# Vault Kubernetes Integration + +This reference provides comprehensive guidance on integrating Vault with Kubernetes. + +--- + +## Supported Kubernetes Versions + +| Component | Supported Versions | +| ----------- | ------------------- | +| VSO | Kubernetes 1.29 - 1.33 | +| Agent Injector | Kubernetes 1.16+ | +| CSI Provider | Kubernetes 1.16+ | + +VSO also supports Red Hat OpenShift 4.10+. + +--- + +## Integration Options + +| Method | Use Case | Complexity | +| -------- | ---------- | ------------ | +| **Vault Secrets Operator (VSO)** | Modern K8s-native, CRD-based | Low | +| **Vault Agent Injector** | Sidecar injection via annotations | Medium | +| **CSI Provider** | Mount secrets as volumes | Medium | +| **Direct API** | Custom integration | High | + +--- + +## Vault Secrets Operator (VSO) + +Kubernetes-native operator that syncs Vault secrets to Kubernetes Secrets. + +### Installation + +```bash +# Add HashiCorp Helm repo +helm repo add hashicorp https://helm.releases.hashicorp.com +helm repo update + +# Install VSO +helm install vault-secrets-operator hashicorp/vault-secrets-operator \ + -n vault-secrets-operator-system \ + --create-namespace +``` + +### Configure Vault Connection + +```yaml +# VaultConnection CRD +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultConnection +metadata: + name: vault-connection + namespace: default +spec: + address: https://vault.example.com:8200 + caCertSecretRef: vault-ca-cert # Optional: custom CA + skipTLSVerify: false +``` + +### Configure Authentication + +```yaml +# VaultAuth CRD - Kubernetes auth +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultAuth +metadata: + name: vault-auth + namespace: default +spec: + vaultConnectionRef: vault-connection + method: kubernetes + mount: kubernetes + kubernetes: + role: my-app + serviceAccount: my-app-sa + audiences: + - vault +``` + +### Sync Static Secrets + +```yaml +# VaultStaticSecret - sync KV secrets +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultStaticSecret +metadata: + name: my-app-secrets + namespace: default +spec: + vaultAuthRef: vault-auth + mount: secret + path: myapp/config + type: kv-v2 + refreshAfter: 60s + destination: + name: my-app-secret + create: true + labels: + app: my-app + transformation: + excludeRaw: true + templates: + username: + text: "{{ .Secrets.username }}" + password: + text: "{{ .Secrets.password }}" +``` + +### Sync Dynamic Secrets + +```yaml +# VaultDynamicSecret - database credentials +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultDynamicSecret +metadata: + name: db-creds + namespace: default +spec: + vaultAuthRef: vault-auth + mount: database + path: creds/readonly + destination: + name: db-credentials + create: true + renewalPercent: 75 +``` + +### Sync PKI Certificates + +```yaml +# VaultPKISecret - TLS certificates +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultPKISecret +metadata: + name: web-tls + namespace: default +spec: + vaultAuthRef: vault-auth + mount: pki_int + role: web-servers + commonName: web.example.com + altNames: + - www.example.com + ttl: 72h + destination: + name: web-tls-secret + create: true + type: kubernetes.io/tls +``` + +--- + +## Vault Agent Injector + +Sidecar injection using Kubernetes MutatingWebhook. + +### Agent Injector Installation + +```bash +helm install vault hashicorp/vault \ + --set "injector.enabled=true" \ + --set "injector.externalVaultAddr=https://vault.example.com:8200" +``` + +### Pod Annotations + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: my-app + annotations: + # Enable injection + vault.hashicorp.com/agent-inject: "true" + + # Vault role for authentication + vault.hashicorp.com/role: "my-app" + + # Secret to inject + vault.hashicorp.com/agent-inject-secret-config.txt: "secret/data/myapp/config" + + # Template for secret format + vault.hashicorp.com/agent-inject-template-config.txt: | + {{- with secret "secret/data/myapp/config" -}} + DATABASE_URL=postgresql://{{ .Data.data.username }}:{{ .Data.data.password }}@db:5432/mydb + {{- end }} +spec: + serviceAccountName: my-app-sa + containers: + - name: app + image: my-app:latest + # Secrets available at /vault/secrets/config.txt +``` + +### Common Annotations + +```yaml +annotations: + # Authentication + vault.hashicorp.com/agent-inject: "true" + vault.hashicorp.com/role: "my-app" + vault.hashicorp.com/auth-path: "auth/kubernetes" + + # Secret injection + vault.hashicorp.com/agent-inject-secret-: "" + vault.hashicorp.com/agent-inject-template-: "