What Is the Log Masking Feature in Grok2API? Implementation and Usage Guide

Grok2API automatically redacts sensitive data from logs by intercepting log entries before emission and replacing values matching a predefined or custom key list with masked strings.

The log masking feature in Grok2API protects credentials and secrets from accidental exposure in application logs by sanitizing structured data at the observability layer. Located in the chenyme/grok2api repository, this feature is implemented in the central logger component at backend/internal/infra/observability/logger.go and automatically masks fields like password, api_key, and token without requiring manual redaction in application code.

How Log Masking Works in Grok2API

The logger implements a five-step interception process that transforms sensitive values before they reach storage. According to the source code in backend/internal/infra/observability/logger.go, the process works as follows:

1. Structured Logging: All entries route through a custom wrapper using a structured logging backend.
2. Sensitive Field Registration: The maskList slice maintains hardcoded keys (e.g., password, api_key, token) deemed sensitive.
3. Field Traversal: Before emission, the masking interceptor recursively examines log fields.
4. Value Replacement: When a field name matches maskList, the value becomes ***** while preserving the data structure.
5. Extensible Registration: The exported AddMaskKey(key string) function allows runtime addition of custom sensitive keys.

Implementation Details in logger.go

The core masking logic resides in backend/internal/infra/observability/logger.go. The implementation guarantees that downstream log analysis tools receive parseable JSON while eliminating secret exposure.

Key technical components include:

• maskList slice: Contains the default set of sensitive field names.
• AddMaskKey(key string): Public API to append custom keys to the mask list during application initialization.
• MaskValue(value string): Utility for manual string masking when automatic field detection is insufficient.

Practical Usage Examples

Automatic Masking of Struct Fields

When logging request payloads containing sensitive fields, the logger automatically redacts values based on field names:

type CreateUserRequest struct {
    Username string `json:"username"`
    Password string `json:"password"` // Automatically masked
}

func CreateUser(c *gin.Context) {
    var req CreateUserRequest
    _ = c.BindJSON(&req)
    
    // Password field is automatically replaced with *****
    logger.Info("Creating user", zap.Any("payload", req))
}

Result in logs:

INFO  Creating user  {"payload":{"username":"alice","password":"*****"}}

Registering Custom Mask Keys

For application-specific secrets, register custom keys during initialization in backend/cmd/grok2api/main.go or an init() function:

func init() {
    // Add custom sensitive field names
    logger.AddMaskKey("dbSecret")
    logger.AddMaskKey("internalToken")
}

Once registered, any log field named dbSecret or internalToken automatically renders as *****.

Manual Value Masking

For ad-hoc masking outside structured logging:

secret := "s3cr3t-token"
masked := logger.MaskValue(secret) // Returns "*****"
logger.Debug("Token obtained", zap.String("token", masked))

Summary

• Automatic protection: The maskList in backend/internal/infra/observability/logger.go automatically redacts default sensitive fields like password and api_key.
• Customizable coverage: Use AddMaskKey(key string) to extend protection to application-specific secrets without modifying core logger code.
• Manual utilities: The MaskValue() function provides ad-hoc redaction for non-structured data.
• Zero-config defaults: The feature requires no configuration for standard fields but allows runtime extension via the public API.

Frequently Asked Questions

Which fields are masked by default in Grok2API?

The default maskList in backend/internal/infra/observability/logger.go includes common sensitive keys such as password, api_key, and token. Any log field matching these names automatically renders as ***** regardless of the data source or nesting level within the log entry.

How do I add custom sensitive fields to the mask list?

Call logger.AddMaskKey("yourFieldName") during application initialization, typically in backend/cmd/grok2api/main.go or an init() function. This extends the default maskList slice without requiring modifications to the logger source code.

Does log masking affect log parsing and analysis tools?

No. The masking interceptor preserves the original JSON structure and field names, only replacing the values with *****. Downstream log aggregation systems can still parse the fields and detect their presence while the actual secrets remain concealed.

Can I use the masking function outside of the standard logger?

Yes. The logger.MaskValue(value string) function provides programmatic access to the masking logic for ad-hoc string sanitization, useful when logging raw strings or debugging output that bypasses structured field logging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}