安全概述

环境变量常存储敏感信息，安全处理至关重要。本文档概述 env 库的安全架构和核心特性。

安全架构

text

┌──────────────────────────────────────────────────────────────┐
│                           应用层                              │
├──────────────────────────────────────────────────────────────┤
│   SecureValue   │    掩码    │    清零    │   内存锁定        │
├──────────────────────────────────────────────────────────────┤
│                          Loader 层                            │
├──────────────────────────────────────────────────────────────┤
│     键验证      │   值验证   │   禁止键   │   大小限制         │
├──────────────────────────────────────────────────────────────┤
│                           解析层                              │
├──────────────────────────────────────────────────────────────┤
│    格式检测     │  展开检查  │       路径验证                  │
└──────────────────────────────────────────────────────────────┘

核心安全特性

特性	说明	文档
SecureValue	敏感值内存保护、自动清零	SecureValue API
禁止键	防止修改系统关键变量	常量与错误
敏感键检测	自动识别敏感配置键，日志脱敏工具	敏感数据脱敏
值验证	检测控制字符、空字节等	Config API
审计日志	完整操作追踪	组件工厂

SecureValue 简介

对于敏感数据，使用 GetSecure 而非 GetString：

// 不推荐
password := env.GetString("DB_PASSWORD")

// 推荐
secret := env.GetSecure("DB_PASSWORD")
defer secret.Close()
password := secret.Reveal()  // 仅在需要明文时调用

核心功能：

内存锁定 - 防止交换到磁盘（仅 Linux/macOS/Windows，其余平台 IsMemoryLockSupported() 返回 false、优雅降级）
自动清零 - Close() 时安全擦除内存
掩码显示 - Masked() 用于日志输出
线程安全 - 支持并发读取

完整 API

详见 SecureValue API。

日志安全

SecureValue 保护的是内存中的敏感值，而日志、错误信息和调试输出同样容易泄露密钥。env 提供一组独立的脱敏工具函数，无需依赖 Loader 即可使用：

IsSensitiveKey 自动检测密码、密钥、令牌等敏感键名
MaskValue / MaskKey 对值和键名脱敏后再输出
SanitizeForLog 扫描日志字符串中的 key=value 模式并掩码

// 日志中安全输出配置，避免泄露明文
log.Printf("加载配置: %s", env.MaskValue("DB_PASSWORD", password))
// 输出：加载配置：[MASKED:12 chars]

log.Printf("连接参数: %s", env.SanitizeForLog("user=admin password=s3cret"))
// 输出：连接参数：user=admin password=[MASKED]

完整指南

脱敏工具的完整用法详见敏感数据脱敏。

键/值验证

键验证

默认键名规则：^[A-Za-z][A-Za-z0-9_]*$

以字母开头
只包含字母、数字、下划线
长度不超过 MaxKeyLength

禁止键

内置禁止键防止修改系统关键变量：

类别	示例	风险
系统路径	`PATH`, `LD_LIBRARY_PATH`	命令/库劫持
动态链接	`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`	恶意库注入
Shell	`SHELL`, `IFS`, `BASH_ENV`	Shell 劫持
语言运行时	`PYTHONPATH`, `NODE_PATH`	模块劫持
Windows 系统	`COMSPEC`, `PATHEXT`, `SYSTEMROOT`, `WINDIR`	命令解释器/系统路径劫持

完整列表

查看 DefaultForbiddenKeys 获取完整禁止键列表。

值验证

启用值验证检测潜在危险：

cfg := env.ProductionConfig()
cfg.ValidateValues = true  // 检测控制字符、空字节等

文件安全基础

文件权限

bash

# 仅所有者可读写
chmod 600 .env

# 或更严格（只读）
chmod 400 .env

Git 忽略

bash

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

配置安全级别

预设	用途	特点
`DevelopmentConfig()`	开发环境	宽松限制、支持 YAML 语法
`TestingConfig()`	测试环境	覆盖已存在变量、测试隔离
`ProductionConfig()`	生产环境	严格验证 + 审计日志、不覆盖已存在变量

// 生产环境推荐配置
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.AllowedKeys = []string{"APP_NAME", "PORT", "DB_HOST", "API_KEY"}

展开作用域隔离

变量展开默认按「先文件、后进程环境」解析。对不可信配置来源，ExpansionScope: ExpansionFileOnly 可将引用范围限制在文件内部，阻断配置文件对进程机密（云凭证、令牌等）的探测与捕获（SEC-03）。配置方式与攻击场景详见变量展开 · 展开作用域。

安全概述 ​

安全架构 ​

核心安全特性 ​

SecureValue 简介 ​

日志安全 ​

键/值验证 ​

键验证 ​

禁止键 ​

值验证 ​

文件安全基础 ​

文件权限 ​

Git 忽略 ​

配置安全级别 ​

展开作用域隔离 ​

相关文档 ​