If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hashicorp/vault shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 2 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hashicorp/vault repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hashicorp/vault.

What it runs against: a local clone of hashicorp/vault — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hashicorp/vault | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hashicorp/vault. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hashicorp/vault.git
#   cd vault
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hashicorp/vault and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hashicorp/vault(\\.git)?\\b" \\
  && ok "origin remote is hashicorp/vault" \\
  || miss "origin remote is not hashicorp/vault (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f ".go-version" \\
  && ok ".go-version" \\
  || miss "missing critical file: .go-version"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hashicorp/vault"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HashiCorp Vault is a secrets management and encryption-as-a-service platform written in Go that securely stores, encrypts, and dynamically generates secrets (API keys, database credentials, certificates) with fine-grained access control and comprehensive audit logging. It provides a unified interface to manage secrets across infrastructure while supporting multiple storage backends (disk, Consul) and dynamic secret engines for systems like AWS and SQL databases. Vault is a modular monorepo: the core server logic lives in the main Go code, auth methods are in separate API modules (api/auth/approle, api/auth/kubernetes, etc.), the UI is a separate Ember.js application in TypeScript/Handlebars, and infrastructure tooling (Dockerfile, .build/ scripts, .github/actions/) handles containerization and CI/CD. The architecture separates the HTTP API server (core) from pluggable auth backends and secret engines.

DevOps engineers, platform teams, and security professionals who need to manage machine-to-machine authentication, rotate credentials automatically, and enforce least-privilege access across microservices and cloud infrastructure. Vault is used by teams running on Kubernetes, traditional VMs, or hybrid environments who require centralized secrets management with audit compliance.

Vault is production-ready and actively maintained by HashiCorp; the repo shows 19.9MB of Go code, extensive CI/CD workflows (.github/workflows/), enterprise-grade features, and a mature test suite. The project supports Go 1.25.0, maintains multiple authentication auth modules (approle, kubernetes, ldap, etc.), and is widely deployed in enterprise environments. Regular updates and security patches are evident from the .copywrite.hcl and dependabot.yml configurations.

Standard open source risks apply.

The repo is actively developed with recent Go module bumps (go 1.25.0), GitHub Actions workflows for build/test/deploy (.github/workflows/), Dependabot integration for dependency updates, and instructions for contributors (.github/instructions/) covering Golang, Ember.js, and testing patterns. The presence of .github/actions/ for custom build, containerization, and setup steps suggests continuous integration and delivery improvements are ongoing.

git clone https://github.com/hashicorp/vault.git
cd vault
# Review Makefile and .build/go.sh for build dependencies
make bootstrap # or check Makefile for the primary build target
make dev      # likely target for local development

Daily commands: Inferred from structure: make dev (see Makefile in root), or .build/go.sh and .build/entrypoint.sh for containerized builds. The repo uses Docker (Dockerfile present) and likely supports docker build + docker run for containerized Vault server startup.

• .github/workflows/build.yml — Primary CI/CD pipeline that builds and tests all Vault changes; every PR must pass these checks before merge.
• .github/workflows/ci.yml — Continuous integration workflow that runs unit tests, linting, and code quality checks across the entire codebase.
• .go-version — Specifies the exact Go version (1.25.0) required to build Vault; critical for reproducible builds and dependency compatibility.
• .golangci.yml — Go linter configuration that enforces code quality standards; violations block PR merges.
• .github/CODEOWNERS — Defines which teams/maintainers must review changes to specific files; ensures architectural decisions are vetted.
• .copywrite.hcl — License header validation configuration ensuring all source files comply with HashiCorp's licensing and attribution requirements.

Add a new GitHub Actions workflow for testing

1. Create new workflow file in .github/workflows/ following existing patterns (e.g., test-go.yml, test-ui.yml) (.github/workflows/)
2. Reference version constraints from .go-version and .node-version to match repo standards (.go-version)
3. Add reusable actions from .github/actions/ (build-vault, set-up-go, install-tools) to avoid duplication (.github/actions/)
4. Document the new workflow's purpose in the PR and link from .github/pull_request_template.md if it affects review process (.github/pull_request_template.md)

Update Go dependencies and version constraints

1. Verify Go version compatibility in .go-version before updating dependencies (.go-version)
2. Update go.mod and go.sum in the module (e.g., api/auth/approle/go.mod shows current dependencies) (api/auth/approle/go.mod)
3. Run linting against new versions using configuration in .golangci.yml (.golangci.yml)
4. Add changelog entry referencing the dependency upgrade for release notes (.release/ci.hcl)

Add a new code ownership rule for a subsystem

1. Edit .github/CODEOWNERS to add path patterns and required reviewer teams for the new subsystem (.github/CODEOWNERS)
2. Ensure the PR template in .github/pull_request_template.md highlights that owners must review (.github/pull_request_template.md)
3. Verify linting and security requirements apply by checking .golangci.yml and security scan workflows (.github/workflows/security-scan.yml)

Create a new distribution or packaging format

1. Add new package definition under .release/linux/package/ or new .release/docker/ entrypoint as needed (.release/)
2. Reference release pipeline config .release/ci.hcl and add build steps for the new format (.release/ci.hcl)
3. Add build artifact generation step to .github/workflows/build-artifacts-ce.yml or build-artifacts-ent.yml (.github/workflows/build-artifacts-ce.yml)
4. Update .copywrite.hcl if new source files are created to ensure license compliance (.copywrite.hcl)

• Go 1.25.0 (.go-version) — Primary language for Vault; provides strong concurrency primitives and cross-platform compilation essential for secrets management.
• GitHub Actions (.github/workflows/) — Native CI/CD integration with repo; enables rapid feedback on all commits and PRs before merge.
• golangci-lint (.golangci.yml) — Enforces consistent code quality and catches common Go mistakes; gates all PRs to maintain baseline standards.
• Docker (.release/docker/) — Simplifies Vault deployment across environments and enables containerized testing in CI/CD pipelines.
• HCL 1.0 (.release/linux/package/etc/vault.d/vault.hcl) — Domain-specific configuration language for Vault; provides intuitive syntax for operators familiar with HashiCorp tools.

• Single main branch with feature branch PR workflow

  • Why: Enables fast iteration and single source of truth; simplifies release management.
  • Consequence: Requires robust CI/CD to prevent broken builds; enforces strict code review via CODEOWNERS.

• Monorepo structure (600 files, shared modules like api/auth/approle/)

  • Why: Allows atomic refactoring across Vault core and auth plugins; reduces dependency version conflicts.
  • Consequence: Larger CI pipeline; must manage cross-module compatibility carefully; all changes share same release cycle.

• Mandatory CODEOWNERS review (.github/CODEOWNERS)

  • Why: Ensures security-critical changes (auth, encryption) are vetted by experts; prevents regressions in sensitive areas.
  • Consequence: May slow down trivial PRs; requires maintaining active maintainer teams and clear ownership boundaries.

• Pre-commit/pre-push hooks (.hooks/)

  • Why: Catches issues before GitHub Actions runs; saves CI time and provides fast local feedback.
  • Consequence: Developer discipline required; hooks can be bypassed with --no-verify (intentionally, for emergencies).

• Not a frontend-only service: Vault is a server with both CLI and UI; this repo focuses on backend stability over UI polish.
• Not a cloud-native only tool: Supports on-premises and hybrid deployments; does not assume Kubernetes or managed services.
• Not real-time secret rotation: Vault manages static secrets and encryption keys; rotation is explicit and operator-initiated.
• Not a logging/audit tool: Integrates with external audit backends; does not provide centralized log analysis.
• Not a policy engine: Vault enforces access control; policy decision logic lives in the operator's usage, not Vault itself.

Secrets in logs: Vault sanitizes sensitive output but developer code must explicitly handle redaction; accidental logs of tokens/keys are easy. Module split: Vault uses multiple Go modules (api/auth/approle has its own go.mod); ensure you're in the right directory when running tests. Build dependencies: the .build/ scripts may require specific Go versions or system tools not listed in go.mod—check .github/actions/install-tools/action.yml and .build/system.sh. TLS/PKI complexity: Vault's encryption and auth flows heavily use x509, elliptic curves, and key material—misunderstanding the crypto layer leads to subtle bugs. Enterprise vs OSS: the codebase contains enterprise features behind build flags; check if your change affects both paths.

• Secret Engine — Vault's plugin architecture relies on secret engines to generate and manage dynamic credentials; understanding how engines integrate is essential for extending Vault functionality
• Auth Method (Plugin Pattern) — Vault's extensibility model uses pluggable auth methods (AppRole, OIDC, JWT, etc.); the api/auth/ module structure shows how to implement custom auth flows
• Unsealing and Root Key Management — Vault requires explicit unsealing to decrypt its storage; understanding Shamir secret sharing and key threshold schemes is critical for operations
• Encryption at Rest with AES-GCM — All secrets in Vault's persistent storage are encrypted with AES-GCM; developers need to understand how the master key and data encryption keys relate
• Audit Logging (Structured Logging) — Vault produces detailed structured audit logs for compliance; contributing code must maintain audit trail correctness via explicit logging hooks
• Policy as Code (HCL-based ACLs) — Vault policies are defined in HCL and determine what secrets users/machines can access; the policy language and evaluation engine are central to security
• Token-based Authentication with TTL/Leasing — All Vault clients authenticate via short-lived tokens with configurable TTLs and lease cycles; understanding token renewal and revocation is fundamental

• hashicorp/consul — Companion service for distributed secrets storage and service mesh integration; Vault can use Consul as a storage backend
• hashicorp/terraform — Terraform has a Vault provider (hashicorp/terraform-provider-vault) for managing Vault resources as infrastructure-as-code
• hashicorp/boundary — Sister product for privileged access management; often deployed alongside Vault for PAM + secrets workflows
• kubernetes/kubernetes — Vault integrates deeply with Kubernetes for auth (JWT, service account projection) and secret injection via sidecar and CSI driver
• hashicorp/web-unified-docs — Official documentation source repo; Vault's user and operator guides are maintained there, referenced in the README

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive GitHub Actions workflow for AppRole auth module testing and linting

The repo has modular auth packages (e.g., api/auth/approle with its own go.mod) but no dedicated CI workflow for these sub-modules. Currently, .github/workflows contains build.yml, ci.yml, and code-checker.yml but none specifically validate the AppRole module's dependencies, tests, or module integrity. This would catch module-specific regressions early and ensure the separated auth modules remain maintainable.

• [ ] Create .github/workflows/auth-module-ci.yml to test api/auth/approle and other auth submodules independently
• [ ] Include go mod tidy validation to catch dependency drift in module-specific go.mod files
• [ ] Add golangci-lint and go test steps for each auth module's test suite
• [ ] Integrate with existing set-up-go action in .github/actions/set-up-go/action.yml

Implement dependency update validation for transitive dependencies in auth modules

The api/auth/approle go.mod shows many indirect dependencies (cenkalti/backoff, go-jose, hashicorp/go-retryablehttp, etc.). While dependabot.yml exists, there's no specific workflow to validate that version bumps in these transitive deps don't introduce breaking changes or security issues specific to the auth module API surface. This prevents supply-chain vulnerabilities from propagating undetected.

• [ ] Create .github/workflows/auth-dependency-audit.yml that runs go mod graph analysis on auth modules
• [ ] Add nancy or gosec scanning specifically for api/auth/* modules against known vulnerability databases
• [ ] Document in .github/instructions/generic/golang.instructions.md how auth module maintainers should handle transitive dependency updates
• [ ] Reference existing tooling patterns from code-checker.yml

Add integration test workflow for AppRole authentication flow end-to-end

While ci.yml and build.yml exist, there's no dedicated workflow for testing the AppRole authentication module's real-world usage patterns against a running Vault instance. This catches breaking changes in the auth flow that unit tests alone might miss. The repo already has enos-lint.yml for infrastructure testing patterns.

• [ ] Create .github/workflows/auth-approle-integration-test.yml that spins up a Vault container
• [ ] Implement test matrix for different Vault versions (to catch compatibility regressions)
• [ ] Add tests covering: RoleID/SecretID authentication, token refresh, request signing with AppRole credentials
• [ ] Leverage existing containerize action in .github/actions/containerize/action.yml and build-vault action patterns

• Add test coverage for all auth method examples in api/auth/*/: several modules likely lack comprehensive integration tests. Start with api/auth/approle/ to understand the pattern, then add similar test suites to other auth methods.
• Enhance contributor documentation: .github/instructions/ exists but is sparse. Add a 'Vault Architecture 101' markdown file explaining the core auth flow, secret engine pattern, and request lifecycle for new developers.
• Fix or document missing observability: the repo has CI but may lack dashboard links or runbook documentation for common development failures. Create .github/docs/troubleshooting.md with solutions for common build/test failures seen in GitHub Actions logs.

The HashiCorp Vault codebase demonstrates a mature security posture with several positive indicators: automated security scanning workflows, secret scanning configuration, comprehensive CI/CD pipeline, and CODEOWNERS governance. However, opportunities exist for improvement including pinning the Docker base image to a specific version, verifying Go version appropriateness, ensuring non-root container execution, and regular auditing of indirect dependencies. The presence of '.secret_scanning.yml' and automated workflows indicates security-aware development practices. No hardcoded secrets or obvious injection vulnerabilities are apparent from the file structure analysis. Dependencies appear to be from reputable sources managed through Go's module system.

• Medium · Outdated Go Version — go.mod (go 1.25.0). The go.mod file specifies Go 1.25.0, which may be a future or non-standard version. Verify this is intentional and that the version is properly supported and receives security updates. Using unsupported or unstable Go versions can introduce vulnerabilities. Fix: Verify Go version alignment with current stable releases from golang.org. Use a stable, currently-supported Go version and ensure regular updates for security patches.
• Low · Indirect Dependency Management Risk — go.mod (indirect dependencies). The module has multiple indirect dependencies that are not directly managed. While go.mod handles transitive dependencies, the lack of direct version pinning for security-critical packages like 'golang.org/x/net' and 'golang.org/x/text' could introduce supply chain risks. Fix: Regularly audit indirect dependencies using 'go list -u -m all' and 'nancy' or 'govulncheck' tools. Consider pinning critical security packages directly if updates lag behind known vulnerabilities.
• Medium · Secrets Scanning Configuration Present — .github/.secret_scanning.yml. The repository includes '.github/.secret_scanning.yml', which indicates secrets scanning is configured. While this is positive, the effectiveness depends on proper GitHub Advanced Security settings and rule configuration. Verify rules are comprehensive enough to catch all common secret patterns. Fix: Audit the secret scanning rules to ensure they cover all credential types (API keys, tokens, certificates, etc.). Enable push protection to prevent secrets from being committed. Regularly review scanning logs for bypasses.
• Low · Docker Image Base Version Not Pinned — Dockerfile (FROM alpine:3). The Dockerfile uses 'FROM alpine:3' without a specific version tag. This means the image will pull the latest alpine:3.x version, which could introduce unexpected changes or vulnerabilities between builds, reducing reproducibility. Fix: Pin the Alpine base image to a specific version (e.g., 'FROM alpine:3.18.6') to ensure consistent builds. Regularly update the pinned version with security patches while maintaining reproducibility.
• Medium · Insufficient Container Security Metadata — Dockerfile. While the Dockerfile includes labels, it lacks explicit security directives like 'USER' (non-root user execution), 'HEALTHCHECK', or read-only filesystem guidance. The provided snippet is truncated, but potential gaps exist. Fix: Add 'USER vault' (or appropriate non-root user) to run container processes without root privileges. Include HEALTHCHECK directives. Document security best practices for running the container securely (read-only root filesystem, capability dropping, etc.).
• Low · Unverified External Dependencies — go.mod (external dependencies). Several dependencies (e.g., 'go-jose/go-jose', 'cenkalti/backoff') are external third-party packages. While HashiCorp generally maintains standards, third-party supply chain risks exist. Fix: Use 'go mod verify' to ensure checksums match. Enable Go module security features ('GOSUMDB'). Periodically review dependency licenses and security advisories using 'nancy' or 'dependabot' (already configured in this repo).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.