typescript-security-review

TypeScript 安全审查

概述

对 TypeScript/Node.js 应用进行安全审查。依据 OWASP Top 10、特定框架的模式和生产就绪标准评估代码。按严重程度（严重、高、中、低）对发现的问题进行分类，并提供修复示例。将深入分析工作委托给 typescript-security-expert Agent。

适用场景

• 对 TypeScript/Node.js 代码库执行安全审计
• 审查身份验证和授权实现（JWT、OAuth2、Passport.js）
• 检查常见漏洞（XSS、注入、CSRF、路径遍历）
• 验证输入校验和清理逻辑
• 审查依赖项安全（npm audit、已知 CVE）
• 检查机密管理和环境变量处理
• 评估 API 安全（速率限制、CORS、安全标头）
• 审查 Express、NestJS 或 Next.js 安全配置
• 部署到生产环境之前，或重大代码变更之后
• 合规性检查（GDPR、HIPAA、SOC2 数据处理要求）

说明

1. 确定审查范围：确定正在审查的文件和模块。优先关注身份验证、授权、数据处理、API 端点和配置文件。使用 grep 查找安全敏感模式（eval、exec、innerHTML、密码处理、JWT 操作）。

   检查点：继续之前，确认至少已识别 3 个安全敏感文件／模块。

2. 检查身份验证与授权：审查 JWT 的实现（签名算法、过期时间、刷新令牌）、OAuth2/OIDC 集成、会话管理、密码哈希（bcrypt/argon2）和多因素身份验证。确认受保护的路由强制要求身份验证。

   检查点：使用 grep 确认所有路由处理程序都应用了身份验证守卫或中间件。

3. 扫描注入漏洞：检查数据库查询中的 SQL/NoSQL 注入、exec/spawn 中的命令注入、模板注入和 LDAP 注入。确认使用参数化查询并验证输入。

   检查点：使用 grep 确认所有数据库查询都使用参数化查询，不存在与用户输入进行字符串拼接的情况。

4. 审查输入验证：检查 API 输入是否使用 Zod、Joi 或 class-validator 进行验证。确认架构完整，包括适当的类型约束、长度限制和格式验证。检查是否存在绕过验证的路径。

   检查点：确认所有公开 API 端点都有对应的验证架构。

5. 评估 XSS 防护：检查 React 组件中是否使用 dangerouslySetInnerHTML，检查内容安全策略标头，并确认对用户生成的内容进行了 HTML 清理。详细模式请参阅 references/xss-prevention.md。

   检查点：使用 grep 确认任何 dangerouslySetInnerHTML 的用法都通过 DOMPurify 或等效工具进行了清理。

6. 检查密钥管理：扫描源代码中的硬编码凭据、API 密钥和密钥。确认 .env 文件已加入 gitignore，并通过适当的管理服务访问密钥。

   检查点：运行 grep -r "password\|secret\|api.*key\|token" --include="*.ts"，以识别代码中可能存在的密钥。

7. 审查依赖项安全性：运行 npm audit，或检查 package-lock.json 中是否存在已知漏洞。找出存在 CVE 的过期依赖项。检查是否存在不必要的依赖项。

   检查点：确认已审查 npm audit 的结果，并已处理严重漏洞。

8. 评估安全标头与配置：检查 helmet.js 或手动配置的安全标头。审查 CORS 策略、速率限制、HTTPS 强制要求、Cookie 安全标志（HttpOnly、Secure、SameSite）以及 CSP。配置示例请参阅 references/security-headers.md。

   检查点：使用 grep 确认全局应用了 helmet 或等效的安全标头。

9. 生成安全报告：生成结构化报告，包含按严重性分类的发现、附带代码示例的修复指导，以及安全态势摘要。

   反馈循环：如果发现严重或高危漏洞，在定稿前重新扫描相关模块，查找类似模式。使用 grep 确认其他位置是否存在相同的漏洞模式。

示例

JWT 安全审查

// ❌ Critical: Weak JWT configuration
import jwt from 'jsonwebtoken';

const SECRET = 'mysecret123'; // Hardcoded weak secret

function generateToken(user: User) {
  return jwt.sign({ id: user.id, role: user.role }, SECRET);
  // Missing expiration, weak secret, no algorithm specification
}

// ✅ Secure: Proper JWT configuration
import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET;
if (!JWT_SECRET || JWT_SECRET.length < 32) {
  throw new Error('JWT_SECRET must be set and at least 32 characters');
}

function generateToken(user: User): string {
  return jwt.sign(
    { sub: user.id }, // Minimal claims, no sensitive data
    JWT_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: '15m',
      issuer: 'my-app',
      audience: 'my-app-client',
    }
  );
}

function verifyToken(token: string): JwtPayload {
  return jwt.verify(token, JWT_SECRET, {
    algorithms: ['HS256'], // Restrict accepted algorithms
    issuer: 'my-app',
    audience: 'my-app-client',
  }) as JwtPayload;
}

SQL 注入防护

// ❌ Critical: SQL injection vulnerability
async function findUser(email: string) {
  const result = await db.query(
    `SELECT * FROM users WHERE email = '${email}'`
  );
  return result.rows[0];
}

// ✅ Secure: Parameterized query
async function findUser(email: string) {
  const result = await db.query(
    'SELECT id, name, email FROM users WHERE email = $1',
    [email]
  );
  return result.rows[0];
}

// ✅ Secure: ORM with type-safe queries (Drizzle example)
async function findUser(email: string) {
  return db.select({
    id: users.id,
    name: users.name,
    email: users.email,
  })
  .from(users)
  .where(eq(users.email, email))
  .limit(1);
}

XSS 模式请参阅 references/xss-prevention.md，安全标头配置请参阅 references/security-headers.md。

审查输出格式

所有安全审查发现均按以下结构组织：

1. 安全态势摘要

总体安全评估评分（1-10），并附上关键观察结果和风险等级。

2. 严重漏洞（立即处理）

可能被利用来攻陷系统、窃取数据或造成未授权访问的问题。

3. 高优先级（30 天内处理）

需要近期修复的安全配置错误、防护措施缺失或漏洞。

4. 中优先级（90 天内处理）

会降低安全态势，但存在缓解因素或可利用性有限的问题。

5. 低优先级（下一周期）

安全改进、加固建议和纵深防御增强措施。

6. 正面的安全观察

值得认可的安全模式和实践。

7. 修复路线图

按优先级排列的行动项，并为最关键的修复提供代码示例。

最佳实践

• 在 API 边界验证所有输入——绝不能只依赖客户端验证
• 使用参数化查询或 ORM——绝不能将用户输入拼接到查询中
• 将密钥存储在环境变量或密钥管理器中——绝不能将其写入源代码
• 对数据库账户、API 密钥和 IAM 角色应用最小权限原则
• 启用安全标头（helmet.js），并将 CORS 限制为已知来源
• 对所有面向公众的端点实施速率限制
• 使用 bcrypt 或 argon2 对密码进行哈希处理——绝不能使用 MD5/SHA 处理密码
• 设置 Cookie 标志：HttpOnly、Secure、SameSite=Strict
• 在 CI 流水线中使用 npm audit，以发现依赖项漏洞
• 记录安全事件（登录失败、权限拒绝），但不要记录敏感数据

约束和警告

• 安全审查不能替代专业的渗透测试
• 重点关注代码级漏洞——基础设施安全不在范围内
• 尊重项目所用的框架——提供针对具体框架的修复指导
• 不要记录、打印或暴露发现的密钥——只报告其位置
• 评估依赖项漏洞时，应判断其是否确实可利用，而不只是确认其存在
• 安全建议必须切实可行——权衡实施成本与风险降低效果

参考资料

详细的安全文档请参见 references/ 目录：

• references/owasp-typescript.md — OWASP Top 10 与 TypeScript/Node.js 模式的对应关系
• references/common-vulnerabilities.md — 常见漏洞模式及其修复方法
• references/dependency-security.md — 依赖扫描和供应链安全
• references/xss-prevention.md — React 和服务端的 XSS 防护模式
• references/security-headers.md — 安全标头和 CORS 配置示例
• references/input-validation.md — 使用 Zod 和 class-validator 的输入验证模式