mapbox-token-security

Mapbox 令牌安全技能

此技能提供安全管理 Mapbox 访问令牌的专业知识，帮助你安全、高效地管理令牌。

令牌类型及适用场景

公共令牌（pk.*）

特征：

• 可安全地公开在客户端代码中
• 仅限特定的公共作用域
• 可设置 URL 限制
• 无法访问敏感 API

适用场景：

• 客户端 Web 应用
• 移动应用
• 面向公众的演示
• 网站中的嵌入式地图

允许的作用域：

• styles:tiles - 显示样式图块（栅格）
• styles:read - 读取样式规范
• fonts:read - 访问 Mapbox 字体
• datasets:read - 读取数据集数据
• vision:read - 访问 Vision API

私密令牌（sk.*）

特征：

• 绝不可公开在客户端代码中
• 可使用任意作用域访问完整 API
• 仅限服务端使用
• 可创建和管理其他令牌

适用场景：

• 服务端应用
• 后端服务
• CI/CD 流水线
• 管理任务
• 令牌管理

常见作用域：

• styles:write - 创建或修改样式
• styles:list - 列出所有样式
• tokens:read - 查看令牌信息
• tokens:write - 创建或修改令牌
• 用户反馈管理作用域

临时令牌（tk.*）

特征：

• 有效期短（最长 1 小时）
• 由私密令牌创建
• 用于单一目的
• 自动过期

适用场景：

• 一次性操作
• 临时委派访问权限
• 短期演示
• 注重安全性的工作流

作用域管理最佳实践

最小权限原则

始终只授予所需的最少作用域：

❌ 错误：

// Overly permissive - don't do this
{
  scopes: [
    'styles:read',
    'styles:write',
    'styles:list',
    'styles:delete',
    'tokens:read',
    'tokens:write'
  ];
}

✅ 正确：

// Only what's needed for displaying a map
{
  scopes: ['styles:read', 'fonts:read'];
}

按使用场景组合作用域

公共地图显示（客户端）：

{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "Public token for map display",
  "allowedUrls": ["https://myapp.com/*"]
}

样式管理（服务端）：

{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "Backend style management - SECRET TOKEN"
}

令牌管理（服务端）：

{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "Token management only - SECRET TOKEN"
}

只读访问：

{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "Auditing/monitoring - SECRET TOKEN"
}

URL 限制

URL 限制的重要性

URL 限制可限制公共令牌的使用位置，防止令牌泄露后被未经授权地使用。

有效的 URL 模式

✅ 推荐的模式：

https://myapp.com/*           # Production domain
https://*.myapp.com/*         # All subdomains
https://staging.myapp.com/*   # Staging environment
http://localhost:*            # Local development

❌ 避免使用：

*                             # No restriction (insecure)
http://*                      # Any HTTP site (insecure)
*.com/*                       # Too broad

多环境策略

为每个环境创建单独的令牌：

// Production
{
  note: "Production - myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://myapp.com/*", "https://www.myapp.com/*"]
}

// Staging
{
  note: "Staging - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

// Development
{
  note: "Development - localhost",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["http://localhost:*", "http://127.0.0.1:*"]
}

令牌的存储与处理

服务端（私密令牌）

✅ 应当：

• 存储在环境变量中
• 使用密钥管理服务（AWS Secrets Manager、HashiCorp Vault）
• 对静态存储的数据进行加密
• 通过 IAM 策略限制访问
• 记录令牌使用情况

❌ 不要：

• 在源代码中硬编码
• 提交到版本控制系统
• 以明文形式存储在配置文件中
• 通过电子邮件或 Slack 分享
• 在多个服务之间重复使用

示例：安全的环境变量：

# .env (NEVER commit this file)
MAPBOX_SECRET_TOKEN=sk.ey...

# .gitignore (ALWAYS include .env)
.env
.env.local
.env.*.local

客户端（公共令牌）

✅ 应当：

• 仅使用公共令牌
• 应用 URL 限制
• 为每个应用使用不同的令牌
• 定期轮换
• 监控使用情况

❌ 不要：

• 公开私密令牌
• 使用未设置 URL 限制的令牌
• 在无关应用之间共享令牌
• 使用作用域过多的令牌

示例：安全的客户端用法：

// Public token with URL restrictions - SAFE
const mapboxToken = 'pk.eyJ1IjoiZXhhbXBsZSIsImEiOiJjbGV4YW1wbGUifQ.example';

// This token is restricted to your domain
// and only has styles:read scope
mapboxgl.accessToken = mapboxToken;

令牌轮换策略

何时轮换令牌

必须轮换：

• 令牌暴露在公共代码仓库中
• 团队成员离职且曾有令牌访问权限
• 怀疑令牌已遭泄露或发生安全事件
• 服务停用
• 合规要求

定期轮换：

• 每 90 天一次（生产环境建议）
• 每 30 天一次（高安全性环境）
• 重大部署后
• 安全审计期间

轮换流程

零停机轮换：

1. 创建具有相同作用域的新令牌
2. 将新令牌部署到金丝雀／预发布环境
3. 使用新令牌验证功能
4. 逐步推广到生产环境
5. 监控问题24-48 小时
6. 确认后撤销旧令牌
7. 更新文档，注明轮换日期

紧急轮换：

1. 立即撤销已泄露的令牌
2. 创建替代令牌
3. 向所有服务部署紧急更新
4. 通知团队发生了安全事件
5. 调查泄露原因
6. 更新流程以防止再次发生

监控与审计

跟踪令牌使用情况

需要监控的指标：

• 每个令牌的 API 请求量
• 请求的地理分布
• 各令牌的错误率
• 异常流量峰值模式
• 来自未授权域名的请求

针对以下情况发出警报：

• 从意外的 IP／区域访问
• 流量突然激增（超过正常水平的 200%）
• 错误率较高（超过 10%）
• 请求来自允许的 URL 之外
• 非工作时间的访问模式

定期安全审计

每月检查清单：

• 检查所有有效令牌
• 确认令牌作用域仍然合适
• 检查未使用的令牌（闲置超过 30 天则撤销）
• 确认 URL 限制仍然有效
• 检查团队成员的访问权限
• 检查公开代码仓库中是否存在令牌（扫描 GitHub）
• 确认文档为最新版本

每季度检查清单：

• 轮换生产令牌
• 全面盘点令牌
• 审查访问控制
• 更新事件响应流程
• 为团队开展安全培训

常见安全错误

1. 在客户端代码中暴露机密令牌

❌ 严重错误：

// NEVER DO THIS - Secret token in client code
const map = new mapboxgl.Map({
  accessToken: 'sk.eyJ1IjoiZXhhbXBsZSIsI...' // SECRET TOKEN
});

✅ 正确做法：

// Public token only in client code
const map = new mapboxgl.Map({
  accessToken: 'pk.eyJ1IjoiZXhhbXBsZSIsI...' // PUBLIC TOKEN
});

2. 作用域权限过宽

❌ 范围过广：

{
  "scopes": ["styles:*", "tokens:*"]
}

✅ 范围明确：

{
  "scopes": ["styles:read"]
}

3. 缺少 URL 限制

❌ 没有限制：

{
  "scopes": ["styles:read"],
  "allowedUrls": [] // Token works anywhere
}

✅ 限制域名：

{
  "scopes": ["styles:read"],
  "allowedUrls": ["https://myapp.com/*"]
}

4. 长期使用令牌而不轮换

❌ 从不轮换：

Token created: Jan 2020
Last rotation: Never
Still in production: Yes

✅ 定期轮换：

Token created: Dec 2024
Last rotation: Dec 2024
Next rotation: Mar 2025

5. 将令牌提交到版本控制系统

❌ 提交到 Git：

// config.js (committed to repo)
export const MAPBOX_TOKEN = 'sk.eyJ1IjoiZXhhbXBsZSI...';

✅ 使用环境变量：

// config.js
export const MAPBOX_TOKEN = process.env.MAPBOX_SECRET_TOKEN;

# .env (in .gitignore)
MAPBOX_SECRET_TOKEN=sk.eyJ1IjoiZXhhbXBsZSI...

事件响应计划

如果令牌遭到泄露

立即采取的措施（前 15 分钟）：

1. 通过 Mapbox 控制面板或 API 撤销令牌
2. 创建替代令牌，必要时使用不同的作用域／限制
3. 更新所有使用该泄露令牌的服务
4. 通过事件频道通知团队

调查（24 小时内）： 5. 检查访问日志以了解泄露情况 6. 检查 Mapbox 控制面板中的未授权使用情况 7. 确定根本原因（令牌是如何泄露的？） 8. 记录事件，包括时间线和影响

预防（1 周内）： 9. 更新流程以防止再次发生 10. 实施额外的防护措施（CI 检查、机密扫描） 11. 根据经验教训培训团队 12. 更新文档，说明新的安全措施

最佳实践摘要

安全检查清单

创建令牌：

• 客户端使用公开令牌，服务端使用密钥令牌
• 按最小权限原则设置作用域
• 为公开令牌添加 URL 限制
• 使用描述性名称/备注以便识别令牌
• 记录预期用途和环境

令牌管理：

• 将密钥令牌存储在环境变量或密钥管理器中
• 切勿将令牌提交到版本控制系统
• 每 90 天轮换一次令牌（或按政策执行）
• 及时删除未使用的令牌
• 按环境区分令牌（开发/预发布/生产）

监控：

• 跟踪令牌使用模式
• 为异常活动设置警报
• 定期进行安全审计（每月）
• 每季度审查团队访问权限
• 扫描代码仓库，查找暴露的令牌

事件响应：

• 制定令牌撤销流程文档
• 紧急联系人名单
• 记录令牌轮换流程
• 事后审查模板
• 对团队进行安全流程培训

何时使用此技能

在以下情况下调用此技能：

• 创建新令牌
• 决定使用公开令牌还是密钥令牌
• 设置令牌限制
• 实施令牌轮换
• 调查安全事件
• 开展安全审计
• 对团队进行令牌安全培训
• 审查代码中是否暴露令牌