Skip to content

Configuration Management

Configuration File Lifecycle — Agent Discovery, Secret Detection, Adoption, Versioning, and Discovery Policies

Document Version: 1.0.0
Last Updated: 2026-10-22
Enterprise Function (PoC / Enterprise license)

1. Overview

Application configuration files (.env, YAML, JSON, INI, properties, TOML, XML) are the most common place where credentials leak out of a secrets manager. Configuration Management closes that gap: MazeVault Agents scan managed hosts for configuration files, detect embedded secrets, and let operators adopt the files into a managed, versioned inventory where secrets are referenced from the vault instead of being stored in plain text.

Feature Description
Agent discovery Agents scan configured paths for configuration files and report candidates with a confidence score
Secret detection Content is matched against organization-defined secret patterns; potential secrets are counted and located
Rewrite plans For every detected secret the agent proposes where the value should live in the vault and which placeholder should replace it
Adoption workflow Review → Adopt (optionally extracting secrets into a project) or Ignore with a reason
Versioning Every adopted file has an immutable version history with original and secret-injected content hashes
Discovery policies Organization-level templates control scan scope, file types, exclusions, classification, and notifications
Overview dashboard Counts of managed files, pending review, compliant, and critical items

Configuration Management is available under Enterprise Functions → Configuration Management in the main menu.

License Requirement

Configuration Management is gated by the config_management license feature, which is granted to PoC and Enterprise licenses. On Small Business or unlicensed tenants the /api/v1/config-files, /api/v1/discovery-results, and secret naming policy endpoints return HTTP 403 and the page shows an upgrade banner. See Licensing.

2. How Agent Discovery Works

Configuration discovery runs as part of the agent's periodic filesystem scan, alongside certificate and keytab discovery.

  1. The agent downloads the organization's discovery policy bundle from the backend. The bundle is compiled from all active configuration templates (discovery policies, parsers, secret patterns, exclusion rules) and carries a policy_version
  2. Files under the configured scan paths are inspected up to the configured depth; excluded paths, extensions, and filenames are skipped
  3. The file type is detected from its name and extension:
File type Detected from
env .env and *.env
yaml .yaml, .yml
json .json
ini .ini
properties .properties
toml .toml
xml .xml
  1. The content is matched against the parser patterns and secret patterns of the bundle. Each secret match records the key, line, and severity
  2. The path is classified as system, application, or unknown according to the policy's classification paths
  3. A confidence score (0–1) is computed from the file type, classification, parser matches, and secret matches
  4. For every secret match a rewrite plan step is generated from the policy's rewrite plan rules (target secret path, placeholder, change reason)
  5. Results are submitted to the backend as discovery results; a persistent local index lets the agent skip unchanged files on the next run while a changed policy_version forces a full re-evaluation

Agents also receive a pre-computed list of password candidates from the bundle so that values already stored in the vault are recognised when found in files.

Discovery Paths

Scan paths, depth, and file types are defined in discovery policy templates (see section 6). The agent's own discovery.filesystem_paths / exclude_paths configuration applies to certificate discovery; configuration discovery follows the policy bundle.

3. Reviewing Discovered Configurations

Navigate to Enterprise Functions → Configuration Management → Discovered Configurations.

Each pending discovery result shows:

Column Description
File Path Full path on the host and the reporting agent
Source Discovery method (filesystem scan) and classification
Secrets Detected Number of potential secrets found by pattern matching
Confidence Score from 0 to 1; higher means the file is more likely a real application configuration
Discovered First time the agent reported the file

Actions

Action Effect
Preview Shows the detected patterns, their locations, and the proposed rewrite plan
Adopt Creates a managed configuration file in the selected project and marks the result adopted
Ignore Marks the result ignored with a reason; it moves to the Staging Area and no longer appears as pending

Adopting a File

  1. Click Adopt on the discovery result
  2. Select the project that will own the configuration file
  3. Optionally paste or confirm the file content so MazeVault can create the initial version
  4. Choose whether to extract secrets — when enabled, each detected secret value is stored as a project secret and the configuration file records a reference (secret_refs) to it, including the location in the file
  5. Optionally add an initial comment
  6. Click Adopt

The managed file is created with status managed, inherits the classification, confidence score, policy version, and rewrite plan from the discovery result, and receives version 1 with the original content hash. The adoption is written to the audit log as ADOPT_CONFIG_DISCOVERY_RESULT.

Secret Extraction

Extracting secrets writes the detected values into the selected project as new secrets. Review the detected patterns in Preview first so that false positives (for example example values or public identifiers) are not stored as secrets.

Discovery Result States

State Description
pending Reported by an agent, waiting for review
adopted Converted into a managed configuration file
ignored Dismissed with a reason (suppressed_reason)

4. Overview Dashboard

The Overview tab summarises the managed inventory:

Card Meaning
Total Files Number of managed configuration files
Pending Review Files still in discovered status that have not been fully processed
Compliant Files whose rotation_status is compliant — all referenced secrets are within rotation policy
Critical Files whose rotation_status is overdue — at least one referenced secret has missed its rotation

The table below the cards lists every managed file with its name, path, type, status, rotation status, number of referenced secrets, and last update.

5. Staging Area

The Staging Area tab lists discovery results that were ignored, together with the reason given. Use it to audit past decisions or to re-evaluate files that were dismissed too early. Ignored files are excluded from the pending queue but remain in the database so the agent does not re-report them as new.

6. Configuration Templates and Discovery Policies

Configuration discovery is driven by configuration templates defined at organization level under Project Settings → Config Templates. Templates have a type, a JSON definition, a priority, and an active flag; only active templates are compiled into the agent's policy bundle.

Template type Purpose Key definition fields
discovery_policy Where and how agents scan scan_paths, scan_depth, file_types, confidence_threshold, auto_adopt, schedule, classification.system_paths / application_paths, rewrite_plan_rules, notifications
parser How a file type is parsed file_types, patterns[] (named regex), ignore_paths, max_file_size_kb, encoding
secret_pattern What counts as a secret patterns[] (name, type, regex, severity, false_positive_hints), entropy_threshold, min_length, max_length
exclusion_rule What to skip rules[] (type, pattern, is_regex, reason), excluded_paths, excluded_extensions, excluded_filenames
naming_convention Resource naming templates used to render, parse, and auto-provision names (with Terraform export) —
secret_naming_policy Rules secrets must follow; exposes check, compliance, and suggestion endpoints —
resource_visibility_policy Which fields of a resource type are visible to which roles; editable by administrators only —

Each template can be validated and previewed before it is saved — validation returns field-level errors and warnings, preview shows how the compiled policy would behave.

Rewrite Plan Rules

A rewrite plan rule maps a detected key to a vault location:

{
  "name": "database-passwords",
  "key_pattern": "(?i)db_password|database\\.password",
  "secret_path_template": "{{classification}}/{{file_name}}/{{key}}",
  "placeholder_template": "${MAZEVAULT:{{secret_path}}}",
  "change_reason": "Move database password to vault"
}

Supported placeholders are {{classification}}, {{file_name}}, {{file_path}}, and {{key}} in secret_path_template, and {{secret_path}} in placeholder_template. Rendered tokens are lower-cased and sanitised. The resulting steps (action: replace_plaintext) are stored on the discovery result and on the adopted file (rewrite_plan) so the proposed change is traceable.

7. Versioning and Secret References

Every adopted configuration file keeps an immutable version history:

Field Description
version_number Sequential version
content_hash SHA-256 of the stored content
change_type / change_summary / change_reason What changed and why
changed_by User who created the version
approval_status auto_approved by default; approval workflows can require explicit sign-off
secret_refs Secrets referenced by this version with their location (JSONPath, XPath, or line reference)
rewrite_plan Rewrite steps applicable to this version

Original and secret-injected content are stored encrypted and are never returned by the API; only hashes and metadata are exposed.

8. Permissions

Permission Description Built-in roles
config:read View managed files, discovery results, overview, and templates org_admin, project_admin, user, secret_manager, certificate_manager
config:write Adopt or ignore discovery results; create, update, delete, validate, and preview templates org_admin, project_admin

Resource visibility policy templates additionally require administrator rights. Users see the Configuration Management menu entry whenever they hold config:read; the license feature decides whether the page is functional. See RBAC Roles.

9. Audit Trail

Audit action Trigger
ADOPT_CONFIG_DISCOVERY_RESULT Discovery result adopted (records project, file path, classification, policy version, rewrite plan steps, extract flag)
IGNORE_CONFIG_DISCOVERY_RESULT Discovery result ignored (records the reason)

Template changes and configuration file versions are recorded through the standard organization and project audit events. See Audit Logging.