Updated README to include detailed autounseal configuration description.

README.md

@@ -95,18 +95,16 @@ The default Vault unseal method uses Shamir's Secret Sharing, which requires man
 4. Apply the policy:
 
     ```shell
-    vault policy write transit-unseal-policy transit-unseal-policy.hcl
+    vault policy write transit-unseal transit_unseal_policy.hcl
     ```
 
 5. Create a token with the policy attached:
 
     ```shell
-    vault token create -policy="transit-unseal-policy"
+    vault token create -orphan -policy="transit-unseal" -wrap-ttl=120 -period=24h -field=wrapping_token > wrapping-token.txt
     ```
 
-    Save the generated token for later use.
+6. Copy the `wrapping-token.txt` file securely to the main Vault server. It can be copied using `scp` or any other secure method.
-
-6. Verify connectivity from the main Vault to the KMS Vault.
 
 7. Store the KMS Vault unseal key and root token securely. Make an offline backup of the KMS Vault.
 
@@ -156,16 +154,57 @@ Depending on main Vault state (new or existing), some of the following steps are
 
 1. If the main Vault is already initialized, shut it down and back up its data directory and configuration file.
 
-2. Update the main Vault configuration file (usually located at `/etc/vault.d/vault.hcl`) to include the Auto Unseal configuration:
+2. Verify connectivity from the main Vault to the KMS Vault.
+
+    ```shell
+    VAULT_ADDR=https://kms.koszewscy.waw.pl:8200 vault status
+    ```
+
+    or
+
+    ```shell
+    curl -s https://kms.koszewscy.waw.pl:8200/v1/sys/seal-status | jq .
+    ```
+
+
+3. Update the main Vault configuration file (usually located at `/etc/vault.d/vault.hcl`) to include the Auto Unseal configuration:
 
     ```hcl
+    ui = true
+
+    storage "file" {
+      path = "/opt/vault/data"
+    }
+
+    # HTTP listener
+    listener "tcp" {
+      address = "127.0.0.1:8200"
+      tls_disable = "true"
+    }
+
+    # HTTPS listener
+    listener "tcp" {
+      address       = "192.168.2.10:443"
+      tls_cert_file = "/opt/vault/tls/tls.crt"
+      tls_key_file  = "/opt/vault/tls/tls.key"
+    }
+
     seal "transit" {
-      address            = "https://pbs.koszewscy.waw.pl:8200"
+      address         = "https://kms.koszewscy.waw.pl:8200"
-      key_name           = "transit-unseal"
+      disable_renewal = "false"
-      mount_path        = "transit/"
+      key_name        = "unseal-key"
+      mount_path      = "transit/"
     }
     ```
-3. Put the KMS Vault token created earlier into the environment file `/etc/vault.d/vault.env`:
+
+
+4. Unwrap the token to get the KMS Vault token:
+
+    ```shell
+    VAULT_ADDR=https://kms.koszewscy.waw.pl:8200 vault unwrap -field=token $(cat wrapping-token.txt) > kms-vault-token.txt
+    ```
+
+5. Put the unwrapped KMS Vault token into the environment file `/etc/vault.d/vault.env`:
 
     ```shell
     VAULT_TOKEN="s.xxxxxxx"
@@ -178,6 +217,17 @@ Depending on main Vault state (new or existing), some of the following steps are
     EnvironmentFile=/etc/vault.d/vault.env
     ```
 
+5. Add systemd override `/etc/systemd/system/vault.service.d/override.conf` if not already present:
+
+    ```ini
+    [Service]
+    AmbientCapabilities=CAP_IPC_LOCK CAP_NET_BIND_SERVICE
+    CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK CAP_NET_BIND_SERVICE
+    NoNewPrivileges=yes
+    ```
+
+    That will allow the vault process to bind to low-numbered ports (443) and lock memory.
+
 5. If the main Vault was already initialized, start it and unseal with `-migrate` parameter.
 
     ```shell
@@ -189,6 +239,8 @@ Depending on main Vault state (new or existing), some of the following steps are
 
 7. Uninitialized main Vault will automatically encrypt the root key with the transit key from the KMS Vault during initialization and present recovery keys for Shamir's Secret Sharing.
 
+If for any reason the Auto Unseal method fails, you can always unseal the main Vault using the recovery keys provided during initialization. If the token expires, generate a new one using the KMS Vault, and transfer it to the main Vault as described above.
+
 ## Offline Backup
 
 Vault installs the following directories:

bin/vault-login

@@ -0,0 +1,17 @@
+# Check, if we are sourced, that's a requirement for this script
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  echo "This script must be sourced, not executed directly."
+  echo "Use: source bin/vault-login"
+  exit 1
+fi
+
+# v_login function may be added to .bashrc, .zprofile, etc.
+function v_login() {
+    local VAULT_USERNAME=${1:-adminslawek}
+    vault login -format=json -method=userpass username="$VAULT_USERNAME" |
+        jq -r '.auth | [.client_token, .accessor] | @tsv' | read -r VAULT_TOKEN TOKEN_ACCESSOR
+    echo "Logged in as $VAULT_USERNAME (Token accessor: $TOKEN_ACCESSOR)"
+    export VAULT_TOKEN TOKEN_ACCESSOR
+}
+
+v_login "$@"

docs/ENV_VARS.md

@@ -0,0 +1,69 @@
+# Environment Variables
+
+> Note: This list was generated by an AI Agent from a limited code search of the repository and may be incomplete.
+>
+> For the full code search results, see: https://github.com/hashicorp/vault/search?q=VAULT_&type=code.
+
+| Environment Variable                      | Purpose (short)                                                         |
+|-------------------------------------------|-------------------------------------------------------------------------|
+| `VAULT_ADDR`                              | Client/server address (API target)                                      |
+| `VAULT_AGENT_ADDR`                        | Agent address (deprecated usage/const)                                  |
+| `VAULT_ALLOW_PENDING_REMOVAL_MOUNTS`      | Allow Pending Removal builtins to be mounted                            |
+| `VAULT_CACERT_BYTES`                      | CA certificate bytes provided via env                                   |
+| `VAULT_CACERT`                            | CA certificate file for TLS verification                                |
+| `VAULT_CAPATH`                            | CA path for TLS verification                                            |
+| `VAULT_CLI_NO_COLOR`                      | Toggle colored CLI output                                               |
+| `VAULT_CLIENT_CERT`                       | Client TLS certificate path                                             |
+| `VAULT_CLIENT_KEY`                        | Client TLS key path                                                     |
+| `VAULT_CLIENT_TIMEOUT`                    | Client timeout configuration                                            |
+| `VAULT_CLUSTER_ADDR`                      | Cluster address for inter-node comms                                    |
+| `VAULT_CLUSTER_INTERFACE`                 | Interface name used to derive VAULT_CLUSTER_ADDR                        |
+| `VAULT_DETAILED`                          | Output detailed CLI information                                         |
+| `VAULT_DEV_LISTEN_ADDRESS`                | Dev-mode listen address (entrypoint default)                            |
+| `VAULT_DEV_ROOT_TOKEN_ID`                 | Dev-mode root token ID (used by entrypoint)                             |
+| `VAULT_DISABLE_FILE_PERMISSIONS_CHECK`    | Disable strict file permission checks (OpenShift/UBI entrypoint)        |
+| `VAULT_DISABLE_LOCAL_AUTH_MOUNT_ENTITIES` | Disable entities for local auth mounts via env                          |
+| `VAULT_DISABLE_REDIRECTS`                 | Disable HTTP redirects for client                                       |
+| `VAULT_DISABLE_RSA_DRBG`                  | Disable RSA DRBG path in cryptoutil (feature flag)                      |
+| `VAULT_ENABLE_RATE_LIMIT_AUDIT_LOGGING`   | Enable audit logging for rate-limited rejections                        |
+| `VAULT_EXPERIMENTS`                       | Comma-separated experiments enabled on startup                          |
+| `VAULT_FORMAT`                            | CLI output format                                                       |
+| `VAULT_HEADERS`                           | Additional headers for API client                                       |
+| `VAULT_HTTP_PROXY`                        | HTTP proxy configuration for client                                     |
+| `VAULT_LDAP_PASSWORD`                     | LDAP password fallback for CLI LDAP credential provider                 |
+| `VAULT_LICENSE_CI`                        | CI license helper for tests                                             |
+| `VAULT_LICENSE_PATH`                      | Path to enterprise license file                                         |
+| `VAULT_LICENSE`                           | Provide enterprise license blob                                         |
+| `VAULT_LOCAL_CONFIG`                      | Pass Vault JSON config via env (entrypoint writes to config dir)        |
+| `VAULT_LOG_FORMAT`                        | Control logger format (standard/json)                                   |
+| `VAULT_LOG_LEVEL`                         | Logging level for Vault                                                 |
+| `VAULT_MAX_RETRIES`                       | Max retries for client operations                                       |
+| `VAULT_MESSAGE_TYPE`                      | Serialization format for forwarded requests (json/json_compress/proto3) |
+| `VAULT_MFA`                               | MFA selection for client                                                |
+| `VAULT_MYSQL_PASSWORD`                    | MySQL password override for physical MySQL backend                      |
+| `VAULT_MYSQL_USERNAME`                    | MySQL username override for physical MySQL backend                      |
+| `VAULT_NAMESPACE`                         | Default namespace header for client requests                            |
+| `VAULT_PLUGIN_AUTOMTLS_ENABLED`           | Enable plugin AutoMTLS (plugin helper)                                  |
+| `VAULT_PLUGIN_METADATA_MODE`              | Control plugin metadata bootstrapping mode                              |
+| `VAULT_PLUGIN_TMPDIR`                     | Folder for Unix sockets for containerized plugins                       |
+| `VAULT_POSTUNSEAL_FUNC_CONCURRENCY`       | Concurrency for post-unseal functions (sets worker count)               |
+| `VAULT_PROXY_ADDR`                        | Proxy address configuration                                             |
+| `VAULT_RAFT_DISABLE_MAP_POPULATE`         | Disable MAP_POPULATE behaviour on Linux                                 |
+| `VAULT_RAFT_FREELIST_SYNC`                | BoltDB freelist sync toggle                                             |
+| `VAULT_RAFT_FREELIST_TYPE`                | BoltDB freelist type (array/map)                                        |
+| `VAULT_RAFT_INITIAL_MMAP_SIZE`            | Initial mmap size for Bolt DB                                           |
+| `VAULT_RAFT_MAX_BATCH_ENTRIES`            | Override Raft max batch entries                                         |
+| `VAULT_RAFT_MAX_BATCH_SIZE_BYTES`         | Override Raft max batch size bytes                                      |
+| `VAULT_RAFT_NODE_ID`                      | Raft node ID from environment                                           |
+| `VAULT_RAFT_PATH`                         | Raft data path from environment                                         |
+| `VAULT_RAFT_RETRY_JOIN_AS_NON_VOTER`      | Join Raft as non-voter via env                                          |
+| `VAULT_RATE_LIMIT`                        | Configure client-side or server rate limiting                           |
+| `VAULT_REDIRECT_ADDR`                     | API redirect address (can be set directly)                              |
+| `VAULT_REDIRECT_INTERFACE`                | Interface name used to derive VAULT_REDIRECT_ADDR                       |
+| `VAULT_SKIP_LOGGING_LEASE_EXPIRATIONS`    | Toggle logging of lease expirations                                     |
+| `VAULT_SKIP_VERIFY`                       | Skip TLS verification (insecure)                                        |
+| `VAULT_SRV_LOOKUP`                        | Enable SRV DNS lookup behavior                                          |
+| `VAULT_TLS_SERVER_NAME`                   | TLS server name for verification                                        |
+| `VAULT_TOKEN`                             | Default Vault token for client auth                                     |
+| `VAULT_UNWRAP_TOKEN`                      | Pass unwrap tokens to plugin (plugin helper)                            |
+| `VAULT_WRAP_TTL`                          | Default wrap TTL for client operations                                  |

docs/Identity.md

@@ -0,0 +1,140 @@
+# Identity and Authentication
+
+## Token Authentication
+
+Setup `VAULT_ADDR` and `VAULT_TOKEN` environment variables to authenticate with Vault using a token.
+
+Store the root token in 1Password and retrieve it when needed using CLI commands.
+
+```bash
+export OP_VAULT_TOKEN="op://Private/root Vault Koszewscy/password"
+export VAULT_ADDR="https://vault.koszewscy.waw.pl" VAULT_TOKEN="${OP_VAULT_TOKEN}"
+```
+
+Then, run the vault using:
+
+```bash
+op run -- vault login $VAULT_TOKEN
+```
+
+1Password CLI will fetch the token from the specified path in your 1Password vault and replace the secret reference with the actual token value when executing the command. However, that method adds a delay due to the `op run` command.
+
+Alternatively, you can directly set the `VAULT_TOKEN` environment variable by reading the token from 1Password:
+
+```bash
+export VAULT_TOKEN=$(op read "op://Private/root Vault Koszewscy/password")
+```
+
+With VAULT_TOKEN set, `vault` authenticates directly.
+
+## Userpass Authentication Method
+
+### Login with Userpass
+
+Userpass authentication allows users to log in with a username and password.
+
+```bash
+vault login -method=userpass username="your-username"
+```
+
+The token is stored in a file located at `~/.vault-token` by default. Although, the token file is secured with file permissions, it contains a plaintext token. Change the token time-to-live (TTL) to limit its validity period.
+
+```bash
+vault write auth/userpass/users/your-username max_token_ttl="12h" token_ttl="1h"
+```
+
+Limit the token's usage to known IP addresses for added security.
+
+```bash
+vault write auth/userpass/users/your-username token_bound_cidrs="192.168.2.0/24"
+```
+
+You can also set VAULT_TOKEN with the following command:
+
+```bash
+export VAULT_TOKEN=$(vault login -token-only -method=userpass username="your-username")
+```
+
+or a function like this:
+
+```bash
+function v_login() {
+    local VAULT_USERNAME=${1:-"your-username"}
+    vault login -format=json -method=userpass username="$VAULT_USERNAME" |
+        jq -r '.auth | [.client_token, .accessor] | @tsv' | read -r VAULT_TOKEN TOKEN_ACCESSOR
+    echo "Logged in as $VAULT_USERNAME (Token accessor: $TOKEN_ACCESSOR)"
+    export VAULT_TOKEN TOKEN_ACCESSOR
+}
+```
+
+> **Note:** The `-token-only` is an equivalent of `-field=token -no-store` options.
+
+You can then use the `TOKEN_ACCESSOR` to look up token details without exposing the actual token.
+
+```bash
+vault token lookup -accessor $TOKEN_ACCESSOR
+```
+
+Use the `vault token renew` command to renew the token before it expires.
+
+```bash
+vault token renew
+```
+
+### User Management
+
+List all users:
+
+```bash
+vault list auth/userpass/users
+```
+
+Create a new user:
+
+```bash
+vault write auth/userpass/users/new-username password="new-password" policies="default"
+```
+
+> **Note:** key="value" pairs may contain scalars or lists (comma-separated values).
+
+Read user details:
+
+```bash
+vault read auth/userpass/users/username
+```
+
+## Entities and Groups
+
+### Entities
+
+Docs: [https://developer.hashicorp.com/vault/api-docs/secret/identity/entity](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity)
+
+List entities by id:
+
+```bash
+vault list identity/entity/id
+```
+
+or by name:
+
+```bash
+vault list identity/entity/name
+```
+
+[Read entity details by id](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity#read-entity-by-id)
+or [by name](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity#read-entity-by-name):
+
+```bash
+vault read identity/entity/id/<entity-id>
+vault read identity/entity/name/<entity-name>
+```
+
+[Create a new entity](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity#create-an-entity):
+
+```bash
+vault write identity/entity name="entity-name" policies="default" metadata=key1=value1 metadata=key2=value2
+```
+
+### Entity Aliases
+
+Docs: [https://developer.hashicorp.com/vault/api-docs/secret/identity/entity-alias](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity-alias)

docs/README.md

@@ -0,0 +1,39 @@
+# General Vault Links and Commands
+
+## Useful commands
+
+Display the `curl` equivalent of a Vault CLI command:
+
+```bash
+vault <any_command> -output-curl-string
+```
+
+The following are equivalent:
+
+```bash
+curl -s -H "X-Vault-Request: true" -H "X-Vault-Token: $VAULT_TOKEN" "https://vault.koszewscy.waw.pl/v1/auth/userpass/users?list=true"
+```
+
+and
+
+```bash
+curl -s -X LIST -H "X-Vault-Request: true" -H "X-Vault-Token: $VAULT_TOKEN" https://vault.koszewscy.waw.pl/v1/auth/userpass/users
+```
+
+because the Vault uses non-standard HTTP method `LIST` for listing resources.
+
+## Environment Variables
+
+| Environment Variable                      | Purpose (short)                                                         |
+|-------------------------------------------|-------------------------------------------------------------------------|
+| `VAULT_ADDR`                              | Client/server address (API target)                                      |
+| `VAULT_DETAILED`                          | Output detailed CLI information                                         |
+| `VAULT_FORMAT`                            | CLI output format                                                       |
+| `VAULT_LOG_FORMAT`                        | Control logger format (standard/json)                                   |
+| `VAULT_LOG_LEVEL`                         | Logging level for Vault                                                 |
+| `VAULT_TOKEN`                             | Default Vault token for client auth                                     |
+| `VAULT_UNWRAP_TOKEN`                      | Pass unwrap tokens to plugin (plugin helper)                            |
+| `VAULT_WRAP_TTL`                          | Default wrap TTL for client operations                                  |
+
+> The list above is a small subset of all available environment variables, that I see most useful.
+> The rest can be found in the [ENV_VARS.md](ENV_VARS.md) file.

policies/README.md

@@ -1,5 +1,16 @@
 # HashiCorp Vault Policies
 
+## Defualt Policy
+
+The **default** policy is created automatically when Vault is initialized, but can be modified as needed. It provides basic access to Vault features for authenticated users.
+
+To restore the default policy to the newest default version, launch a development Vault server and copy the default policy from there:
+
+```bash
+vault policy read default > default_policy.hcl
+vault policy write default default_policy.hcl
+```
+
 ## Policy Commands
 
 ```bash
@@ -11,6 +22,12 @@ vault policy delete <policy-name>
 
 Format a policy file using `vault policy fmt <policy-file.hcl>`.
 
+Display required capabilities for a given path with:
+
+```bash
+vault <anycommand> -output-policy
+```
+
 ## Auditing
 
 To enable auditing, use the following command:
@@ -26,14 +43,42 @@ Add the following configuration to your Alloy setup:
 ```hcl
 loki.source.file "vault_audit_log" {
     targets = [
-        {"__path__" = "/var/log/vault/audit.log", "log_name" = "vault_audit", "level" = "info"},
+        {"__path__" = "/var/log/vault/audit.log", "log_name" = "vault_audit", "level" = "info", "service" = "vault"},
     ]
-    forward_to = [loki.write.default.receiver]
     tail_from_end = true
+    forward_to = [loki.process.vault_audit.receiver]
+}
+
+loki.process "vault_audit" {
+    stage.json {
+        expressions = {error = "error"}
+    }
+
+    stage.labels {
+        values = { __has_error = "error" }
+    }
+
+    stage.match {
+        selector = "{__has_error!=\"\"}"
+
+        stage.static_labels {
+            values = {level = "error"}
+        }
+    }
+
+    stage.label_drop {
+        values = ["__has_error"]
+    }
+
+    forward_to = [loki.write.default.receiver]
 }
 ```
 
-> **Note:** `tail_from_end = true` ensures that only new log entries are read, preventing the ingestion of old lines/entries. It is (probably) required because the audit log file does not contain timestamps and only entry guids.
+> **Note:** `tail_from_end = true` ensures that only new log entries are read, preventing the ingestion of old lines/entries.
+> It is (probably) required because the audit log file does not contain timestamps and only entry guids.
+> Without this setting, Alloy may re-ingest old log entries upon restart.
+>
+> `loki.process` extracts message level from the `error` field in the JSON log entry.
 
 Check auditing configuration with:
 
@@ -46,3 +91,7 @@ To disable auditing, use:
 ```bash
 vault audit disable file
 ```
+
+## References
+
+- [RSoP Tool](https://github.com/threatkey-oss/hvresult) - **hvresult** computes the Resultant Set of Policy (RSoP) for Hashicorp Vault ACLs.

policies/transit_unseal_policy.hcl

@@ -0,0 +1,7 @@
+path "transit/decrypt/unseal-key" {
+  capabilities = ["update"]
+}
+
+path "transit/encrypt/unseal-key" {
+  capabilities = ["update"]
+}