Security Overview

Environment variables often store sensitive information, making secure handling critical. This document provides an overview of the env library's security architecture and core features.

Security Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Application Layer                     │
├──────────────────────────────────────────────────────────────┤
│   SecureValue   │   Masking   │   Zeroing   │  Memory Lock  │
├──────────────────────────────────────────────────────────────┤
│                          Loader Layer                        │
├──────────────────────────────────────────────────────────────┤
│   Key Validation │  Value Validation │  Forbidden Keys │ Size Limits │
├──────────────────────────────────────────────────────────────┤
│                         Parsing Layer                        │
├──────────────────────────────────────────────────────────────┤
│  Format Detection │  Expansion Check │    Path Validation   │
└──────────────────────────────────────────────────────────────┘

Core Security Features

Feature	Description	Documentation
SecureValue	Sensitive value memory protection, auto-zeroing	SecureValue API
Forbidden Keys	Prevent modification of critical system variables	Constants & Errors
Sensitive Key Detection	Automatic identification of sensitive config keys	Constants & Errors
Value Validation	Detect control characters, null bytes, etc.	Config API
Audit Logging	Complete operation tracking	Component Factory

SecureValue Overview

For sensitive data, use GetSecure instead of GetString:

// Not recommended
password := env.GetString("DB_PASSWORD")

// Recommended
secret := env.GetSecure("DB_PASSWORD")
defer secret.Close()
password := secret.Reveal()  // Call only when plaintext is needed

Core capabilities:

• Memory Locking - Prevents swapping to disk (Linux/macOS/Windows/FreeBSD)
• Auto-Zeroing - Securely erases memory on Close()
• Masked Display - Masked() for log output
• Thread Safety - Supports concurrent reads

Full API

See SecureValue API for details.

Key/Value Validation

Key Validation

Default key name rule: ^[A-Za-z][A-Za-z0-9_]*$

• Must start with a letter
• Only letters, digits, and underscores
• Maximum length of MaxKeyLength

Forbidden Keys

Built-in forbidden keys prevent modification of critical system variables:

Category	Examples	Risk
System Paths	PATH, LD_LIBRARY_PATH	Command/library hijacking
Dynamic Linking	LD_PRELOAD, DYLD_INSERT_LIBRARIES	Malicious library injection
Shell	SHELL, IFS, BASH_ENV	Shell hijacking
Language Runtimes	PYTHONPATH, NODE_PATH	Module hijacking

Full List

See DefaultForbiddenKeys for the complete forbidden keys list.

Value Validation

Enable value validation to detect potential dangers:

cfg := env.ProductionConfig()
cfg.ValidateValues = true  // Detect control characters, null bytes, etc.

File Security Basics

File Permissions

# Read/write for owner only
chmod 600 .env

# Or stricter (read-only)
chmod 400 .env

Git Ignore

.env
.env.local
.env.*.local
*.pem
*.key

Configuration Security Levels

Preset	Use Case	Characteristics
DevelopmentConfig()	Development	Relaxed restrictions, YAML syntax support
TestingConfig()	Testing	Override existing variables, test isolation
ProductionConfig()	Production	Strict validation + audit logging, no override of existing variables

// Recommended production configuration
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.AllowedKeys = []string{"APP_NAME", "PORT", "DB_HOST", "API_KEY"}

Related Documentation

• SecureValue API - Complete API for secure value handling
• Constants & Errors - Forbidden keys list, sensitive key patterns
• Production Checklist - Pre-deployment security checks