diff --git a/docs/plans/fix-mapstructure-vulnerability.md b/docs/plans/fix-mapstructure-vulnerability.md
new file mode 100644
index 0000000..1d23b59
--- /dev/null
+++ b/docs/plans/fix-mapstructure-vulnerability.md
@@ -0,0 +1,36 @@
+# Fix mapstructure vulnerability
+
+## Context
+
+GitHub Dependabot alerts (GHSA-22qq-3xwm-r SEQ-5, GHSA-fv92-fjc5-jj9h) flag `github.com/go-viper/mapstructure/v2` (currently v2.2.1) for medium-severity information disclosure. Sensitive data can leak into error log messages when processing malformed input. The vulnerability is patched in v2.4.0+.
+
+This is an indirect dependency pulled in by `github.com/spf13/viper`.
+
+## Vulnerability Details
+
+- **Package**: `github.com/go-viper/mapstructure/v2`
+- **Current version**: v2.2.1
+- **Vulnerable range**: <= v2.3.0
+- **First patched version**: v2.4.0
+- **Latest available**: v2.5.0
+- **Severity**: Medium (4.5)
+- **Impact**: Information disclosure via error messages containing sensitive field values
+
+## Plan
+
+1. Run `go get github.com/go-viper/mapstructure/v2@v2.5.0` to upgrade the indirect dependency
+2. Run `go mod tidy` to clean up
+3. Run linter and `go test ./...` to verify nothing breaks
+4. Commit (including this plan document) and create PR
+
+## Files Modified
+
+- `go.mod` — version bump from v2.2.1 to v2.5.0
+- `go.sum` — updated checksums
+- `docs/plans/fix-mapstructure-vulnerability.md` — this plan document
+
+## Verification
+
+- `go test ./...` passes
+- `golangci-lint run` passes
+- Dependabot alerts for GHSA-fv92-fjc5-jj9h should auto-close after merge
diff --git a/go.mod b/go.mod
index c07fe94..0c8705b 100644
--- a/go.mod
+++ b/go.mod
@@ -30,7 +30,7 @@ require (
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-logfmt/logfmt v0.6.0 // indirect
-	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/google/go-querystring v1.1.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
diff --git a/go.sum b/go.sum
index 18cce5e..9d514f6 100644
--- a/go.sum
+++ b/go.sum
@@ -51,8 +51,8 @@ github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/go-logfmt/logfmt v0.6.0 h1:wGYYu3uicYdqXVgoYbvnkrPVXkuLM1p1ifugDMEdRi4=
 github.com/go-logfmt/logfmt v0.6.0/go.mod h1:WYhtIu8zTZfxdn5+rREduYbwxfcBr/Vr6KEVveWlfTs=
-github.com/go-viper/mapstructure/v2 v2.2.1 h1:ZAaOCxANMuZx5RCeg0mBdEZk7DZasvvZIxtHqx8aGss=
-github.com/go-viper/mapstructure/v2 v2.2.1/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=