Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: Build a Vault Policy Linter

Build a small linter that parses Vault HCL policies and flags risky rules: wildcards on sys, sudo, missing data paths for KV v2, root-like access and overly broad globs, step by step.

Reviewing policies by eye does not scale. Teams that keep policies in Git often add a linter to pull requests that rejects obvious mistakes. In this project you build one in JavaScript that parses a simplified HCL policy and reports problems. You will practice reading policies critically, which is also a great exam of what you learned about capabilities and matching.

This is a learning project, not an official tool. It handles the common path "..." { capabilities = [...] } shape only. For production, test policies against a real Vault server and consider tooling such as Sentinel or Open Policy Agent in your pipeline.

Step 1: parse policies

A policy is a list of blocks. We use a regular expression because the format is regular enough for this exercise.

JS Step 1: a minimal parser

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 2: write the checks

Each check receives a rule and returns a message or nothing. Ideas for rules, from most to least serious:

  1. Catch-all: a path of * or +/* grants nearly everything.
  2. sudo on anything is a finding unless explicitly allowed.
  3. Writable sys/: update, create or delete under sys/ can change Vault itself.
  4. KV v2 mistake: a secret/... path without data/ or metadata/ for a mount that is KV v2 will not work.
  5. Broad wildcard with write: a glob plus create/update/delete at shallow depth.
  6. Prefix glob without slash: app* instead of app/*.
  7. Unneeded capability pair: read and delete on secrets used by an app.
JS Step 2: the linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 3: make it useful in a pipeline

  • Exit with a non-zero code when any finding is error level, so CI fails.
  • Add severities (error, warning) and an allow-list file for justified exceptions (for example the admin policy may use sudo).
  • Add a test with an expected-findings table for every rule (a "golden file").
  • Run it on pull requests that touch the policies/ folder.
  • Combine it with a dry run on a dev Vault: vault policy fmt for formatting and vault policy write into a scratch namespace.
JS Step 3: severities and exit status

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Challenges

  1. Detect two rules that overlap (one glob contains another) and warn when the longer rule has fewer capabilities.
  2. Warn when a policy gives list but no matching read.
  3. Support deny and report rules made useless by an earlier deny.
  4. Read the policy names from files in a folder.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why flag a policy path like secret/app/db on a KV v2 mount?

    KV v2 data is addressed as secret/data/..., so the rule would not grant access.
  2. 2. Why use an allow-list in a linter?

    Some risky rules are justified; an allow-list documents them.
  3. 3. What should a CI linter do when it finds an error-level problem?

    A failing exit status blocks the merge until it is fixed.

Summary

  • A policy linter parses blocks and applies small rule checks.
  • Focus on catch-alls, sudo, writable sys/, KV v2 paths and sloppy globs.
  • Add severities, exceptions and tests, and run it in CI.

Next: Troubleshooting and Practice