Config Obfuscation - rConfig V8

Config Obfuscation: Mask Secrets Before They Leave the Server

Config Obfuscation prevents sensitive values (passwords, secrets, communities, tokens) from being exposed in configuration text, search contexts, and diffs shown in the UI or returned via API.

It is designed to reduce accidental leakage during everyday workflows (config viewing, diffs, searches, exports) without changing the stored configuration files.

rConfig also has a separate, older environment flag named MASK_DEVICE_CREDENTIALS. That flag is narrower and protects device credential fields and a few credential-adjacent responses (UI and REST API). It is not the same feature as Config Obfuscation.

Availability

Config Obfuscation is available from rConfig 8.1.2+.

Output-only masking

This feature masks output only. It does not modify stored configuration backups on disk.

---

When to Use It

• Security hardening: prevent secrets from being casually visible to read-only users.
• Screen sharing / demos: reduce risk during troubleshooting sessions.
• Audit & compliance: consistently mask known sensitive patterns (SNMP communities, enable secrets, local user passwords).
• Change workflows: ensure diffs and change previews don’t leak secrets.

---

How It Works

At render-time (and API response time), rConfig runs the configuration text through an obfuscation pass:

1. Check if the feature is enabled.
2. Check whether the current user is allowed to view unmasked output.
3. Load the enabled rules (cached).
4. Apply rules in order (sort_order, then id).

This means you can tune masking without changing how configs are collected or stored.

---

Enablement & Environment Variables

These are configured via your .env:

Variable	Default	Purpose
MASK_DEVICE_CREDENTIALS	false	Legacy masking for device credential fields, selected debug output, and some integration secrets
CONFIG_OBFUSCATION_ENABLED	false	Enables/disables obfuscation globally
CONFIG_OBFUSCATION_CACHE_SECONDS	300	Cache TTL for enabled rules and “unmasked roles” setting
CONFIG_OBFUSCATION_DEFAULT_REPLACEMENT	********	Default replacement when a rule has no replacement, i.e. <REDACTED> or [SECRET],

Caching

Rule changes and status toggles clear the obfuscation cache automatically. If you change .env values, you may still need to reload config/cache depending on your deployment.

---

Legacy Device Credential Masking (MASK_DEVICE_CREDENTIALS)

MASK_DEVICE_CREDENTIALS is an environment-level safeguard for device credentials themselves, not a rule-based config text masking system.

How to Enable It

Set this in your .env:

MASK_DEVICE_CREDENTIALS=true

Then reload your application config as you normally would for environment changes.

If it remains:

MASK_DEVICE_CREDENTIALS=false

then this legacy masking layer stays off.

What It Does

When enabled, rConfig applies fixed masking behavior in a few specific places:

• Device API/UI payloads omit or mask device_username, device_password, and device_enable_password instead of returning raw values.
• Device debug output replaces known device password values with ********.
• Credential-set passwords loaded through the device credential relation are also masked in debug output.
• Some integration responses, such as the HashiCorp Vault config response, replace sensitive tokens with ********.

This behavior is fixed in code. It does not use database rules, per-role access settings, or custom replacement strings.

Why It Is Different From Config Obfuscation

MASK_DEVICE_CREDENTIALS and Config Obfuscation solve related but different problems:

Area	MASK_DEVICE_CREDENTIALS	Config Obfuscation
Primary target	Stored device credential fields and a few secret-adjacent responses	Configuration text, searches, previews, exports, and diffs
Configuration model	Single .env flag	.env flag plus database-backed rules and Settings UI
Custom rules	No	Yes
Per-role unmask access	No	Yes
Replacement control	Fixed ********	Per-rule replacement or global default
Best use	Hide application-managed credentials from routine API/UI exposure	Redact secrets found inside collected config text

In short: MASK_DEVICE_CREDENTIALS protects credential fields rConfig already knows about. Config Obfuscation protects secret patterns found inside config content.

Important Interaction When MASK_DEVICE_CREDENTIALS=false

Setting MASK_DEVICE_CREDENTIALS=false does not disable Config Obfuscation.

If you have:

MASK_DEVICE_CREDENTIALS=false
CONFIG_OBFUSCATION_ENABLED=true

then the legacy device-credential masking layer is off, but Config Obfuscation still runs for config content and diffs.

For device debug output specifically, rConfig still attempts to replace exact known device secret values with ******** before applying obfuscation rules when Config Obfuscation is enabled. This means debug output may still hide secrets even when MASK_DEVICE_CREDENTIALS is set to false.

---

Rules

Rules are stored in the database (config_obfuscation_rules) and applied to any config output that is wired into the obfuscator.

Rule Types

Type	Match Behavior	Replacement Behavior
regex	PCRE regex over the full content	Uses preg_replace()
prefix	Line starts with pattern	Replaces the entire line
suffix	Line ends with pattern	Replaces the entire line
contains	Line contains pattern	Replaces the entire line
exact	Line exactly equals pattern	Replaces the entire line

Prefer regex when you need partial masking

If you want to keep part of a line (e.g. keep enable secret 5 and redact only the hash), use regex with capture groups.

Replacement Precedence (Rule vs Global)

• If a rule’s replacement is set, it wins.
• If a rule’s replacement is blank, rConfig uses CONFIG_OBFUSCATION_DEFAULT_REPLACEMENT.

The {default} Token

For regex rules, it’s common to preserve a prefix with capture groups. {default} lets you inject the global default into a rule replacement.

Example:

pattern:     ^(enable secret\s+\S+\s+)(.+)$
replacement: $1{default}

If your default is ********, output becomes:

enable secret 5 ********

If your default is [REDACTED], output becomes:

enable secret 5 [REDACTED]

---

Example Rules

rConfig ships with “Insert example rules” to help you get started. These examples are intentionally conservative and designed to be edited.

Existing example rules

If you inserted example rules before updating your default replacement strategy, those rows won’t auto-update (they’re skipped by name). Edit or delete/re-add them if you want different behavior.

Suggested examples:

Cisco: Enable Secret

pattern:     ^(enable secret\s+\S+\s+)(.+)$
replacement: $1{default}

Cisco: Username Password

pattern:     ^(username\s+\S+\s+password\s+)(.+)$
replacement: $1{default}

SNMP Community

pattern:     ^(snmp-server community\s+)(\S+)(.*)$
replacement: $1{default}$3

Cisco: Enable Password (value only)

pattern:     (?<=enable password )\S+
replacement: {default}

Regex performance

Avoid overly complex patterns that can backtrack heavily. Test with realistic config samples and keep patterns as specific as possible.

---

Who Can View Unmasked Output

By default, when obfuscation is enabled, users see masked output.

To allow specific roles to view unmasked output, set Allowed unmasked roles in Settings. This is stored in:

• settings.config_obfuscation_unmasked_roles (array of role IDs)

If the authenticated user has any role in that list, output is returned unmasked.

---

UI: Where to Configure It

Navigate to:

Settings → Security & Access → Config Obfuscation

Tabs:

• Rules: Create, edit, enable/disable, delete rules; insert example rules.
• Access: Pick which roles are allowed to view unmasked output.

Admin access

Only administrators can access the Settings panel for this feature. This is the default hardcoded admin role, but you can create a custom role with setting.view and setting.update permissions to delegate access.

---

Troubleshooting

“My default replacement isn’t showing”

• Ensure the rule’s replacement is blank, or uses {default}.
• If a rule’s replacement is hard-coded (e.g. ********), it will override the global default.

“My rule masks too much (whole line disappears)”

• Non-regex rule types (contains, prefix, etc.) replace the entire line.
• Switch to a regex rule and use capture groups to preserve what you want.

“Nothing is being masked”

• Confirm CONFIG_OBFUSCATION_ENABLED=true.
• Confirm the rule is enabled.
• Confirm your user is not in an allowed unmasked role.

Troubleshooting

If a rule is not masking as expected, verify the pattern against a real config sample. For regex rules, check and iterate on the pattern in https://regex101.com/ to ensure it matches exactly what you intend.

---

Related Documentation

• Configuration Backups
• Configuration Diffs
• Config Editor
• Snippets