# How Configuration Values Are Masked for Security in Agent-Reach's `to_dict()` Method

> Agent-Reach's to_dict() method secures config data by masking sensitive values with previews and ellipses protecting your information.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-14

---

**The `Config.to_dict()` method in Agent-Reach masks sensitive configuration values by checking keys against a list of security markers and replacing matching values with an eight-character preview followed by ellipses.**

The Agent-Reach repository implements a secure configuration management system that prevents credential exposure in logs and debug output. When converting configuration objects to dictionaries for display purposes, the `to_dict()` method automatically identifies and obscures potential secrets based on key name patterns. This security feature is implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and ensures that API keys, tokens, and passwords remain protected while still allowing developers to verify that values are populated.

## How Sensitive Configuration Masking Works in `to_dict()`

The masking mechanism operates through a substring matching system that inspects every configuration key before serialization. This approach protects against accidental credential leaks in stack traces, log files, and CLI outputs.

### The Sensitive Markers List

At lines 110-123 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the method defines a comprehensive list of sensitive markers that indicate potential secret values:

```python

# Sensitive markers include:

# "key", "token", "password", "cookie", 

# "secret", "auth", and similar substrings

```

These markers cover common naming conventions for credentials across different services and authentication schemes. The list captures variations such as `api_key`, `github_token`, `password`, `secret_key`, and `auth_token` without requiring exhaustive enumeration of every possible key name.

### The Masking Logic Implementation

The `to_dict()` method processes each key-value pair through a case-insensitive check at lines 125-127. When the lower-cased key contains any sensitive marker, the implementation at lines 127-128 replaces the actual value with a truncated preview:

1. **For sensitive matches**: The value becomes the first eight characters followed by `...` (e.g., `"12345678..."`), or `None` if the value is falsy
2. **For non-sensitive keys**: Values pass through unchanged at lines 129-130

This selective masking ensures that file paths, boolean flags, and numeric settings remain fully visible while credential strings remain obscured.

## Code Implementation Details

The security filtering occurs within the `to_dict()` implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The method iterates over the internal configuration dictionary and applies the masking rules before returning the result:

```python
def to_dict(self):
    # Lines 110-123: Define sensitive markers

    sensitive_markers = ["key", "token", "password", 
                         "cookie", "secret", "auth"]
    
    result = {}
    # Lines 125-130: Iterate and mask

    for key, value in self._config.items():
        if any(marker in key.lower() for marker in sensitive_markers):
            # Mask sensitive values (lines 127-128)

            result[key] = value[:8] + "..." if value else None
        else:
            # Pass through non-sensitive values (lines 129-130)

            result[key] = value
    return result

```

The algorithm uses substring containment rather than exact matching, ensuring that keys like `EXA_API_KEY` or `github_token` trigger masking regardless of capitalization or surrounding text.

## Practical Usage Example

When working with the Agent-Reach configuration system, the `to_dict()` method provides safe serialization for debugging:

```python
from agent_reach.config import Config

# Assume the config file contains:

#   exa_api_key: "1234567890abcdef"

#   github_token: "ghp_abcdefghijklmnopqrstuvwxyz"

#   output_dir: "/tmp/reports"

cfg = Config()
print(cfg.to_dict())

```

**Output:**

```json
{
  "exa_api_key": "12345678...",
  "github_token": "ghp_abcd...",
  "output_dir": "/tmp/reports"
}

```

The API key and GitHub token are masked to their first eight characters, while the non-sensitive `output_dir` path displays in full. This behavior protects credentials if the output is redirected to logs or monitoring systems.

## Summary

- **Location**: The masking logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), specifically within the `to_dict()` method at lines 110-130.
- **Detection**: Sensitive keys are identified by checking for substrings including `"key"`, `"token"`, `"password"`, `"cookie"`, `"secret"`, and `"auth"`.
- **Transformation**: Matching values are truncated to eight characters plus ellipses (`...`), or set to `None` if empty.
- **Safety**: Non-sensitive configuration values pass through unchanged, ensuring usability for debugging while maintaining security for credentials.

## Frequently Asked Questions

### What specific key patterns trigger the masking behavior in `to_dict()`?

The `to_dict()` method checks for the following sensitive markers in a case-insensitive manner: `"key"`, `"token"`, `"password"`, `"cookie"`, `"secret"`, and `"auth"`. Any configuration key containing these substrings—such as `api_key`, `SECRET_TOKEN`, or `auth_header`—will have its value masked. This substring approach ensures broad coverage of credential naming conventions without requiring an exhaustive whitelist.

### How much of the original value is preserved when masking occurs?

When a key is identified as sensitive, the `to_dict()` method preserves only the first eight characters of the original value and appends three dots (`...`). If the value is falsy (empty string, `None`, etc.), it returns `None` instead. This eight-character preview allows developers to verify that a value is populated and distinguish between different keys without exposing the full credential string.

### Does the masking affect the actual stored configuration or just the dictionary output?

The masking only affects the dictionary returned by `to_dict()`; the underlying configuration values remain intact and fully accessible through the `Config` object's standard attribute or dictionary access methods. The `to_dict()` method creates a sanitized copy specifically for safe display purposes, ensuring that the original credentials remain available for actual API calls and authentication operations.

### Where else in the Agent-Reach codebase is configuration security handled?

Beyond the `to_dict()` masking in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the repository implements additional security measures in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) through the `make_private_dir` function. This utility creates configuration directories with restrictive file permissions, ensuring that sensitive configuration files are not world-readable on the filesystem. The test suite in [`tests/test_config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_config.py) verifies both the masking behavior and secure file handling.