codebase-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Audit

代码库审计

Audit the codebase like you're inheriting someone else's mess - be thorough and honest. No diplomacy, no softening. Focus on what actually matters: security holes, bugs, maintainability problems, and tech debt. If something is broken or badly done, say it.

审计代码库时要像接手别人的烂摊子一样——彻底且诚实。不要委婉，不要含糊。聚焦真正重要的问题：安全漏洞、bug、可维护性问题和技术债务。如果有东西坏了或者做得很差，直接指出来。

Audit Process

审计流程

Copy this checklist to track your progress:

Codebase Audit Progress:
- [ ] Step 1: Check available tools
- [ ] Step 2: Detect project type and run audits
- [ ] Step 3: Detect tech stack and framework patterns
- [ ] Step 4: Identify and document critical issues
- [ ] Step 5: Generate high-level findings summary

复制此清单以跟踪进度：

Codebase Audit Progress:
- [ ] Step 1: Check available tools
- [ ] Step 2: Detect project type and run audits
- [ ] Step 3: Detect tech stack and framework patterns
- [ ] Step 4: Identify and document critical issues
- [ ] Step 5: Generate high-level findings summary

1. Check Available Tools

1. 检查可用工具

Start by checking what tools you have available:

bash

command -v trufflehog
command -v npm # or pnpm, yarn, pip, cargo, etc.

If any expected tools are missing, list them in your output and ask the user if they want to continue without them. Don't let missing tools block the entire audit.

首先检查你拥有的可用工具：

bash

command -v trufflehog
command -v npm # or pnpm, yarn, pip, cargo, etc.

如果缺少任何预期的工具，请在输出中列出它们，并询问用户是否要在没有这些工具的情况下继续。不要让缺失的工具阻碍整个审计。

2. Detect Project Type and Run Audits

2. 检测项目类型并运行审计

Figure out the package manager and run the right audit:

```
package-lock.json
```
→
```
npm audit --json
```
```
pnpm-lock.yaml
```
→
```
pnpm audit --json
```
```
yarn.lock
```
→
```
yarn audit --json
```

requirements.txt

poetry.lock

→

pip-audit --format json

safety check --json

```
Cargo.toml
```
→
```
cargo audit --json
```

go.mod

→

go list -json -m all | nancy sleuth

*.csproj

→

dotnet list package --vulnerable --include-transitive

Secret scanning: Need help with TruffleHog? Check references/secret-scanning.md for scanning both current files and git history.

Parse the JSON output from these tools and integrate what you find into the audit report.

TypeScript projects (if tsconfig.json exists):

Check if
```
strict
```
mode is enabled (critical issue if it's false or missing)
Count how many times
```
any
```
is used explicitly (this defeats type safety)
Count type assertions using
```
as
```
or
```
<Type>
```
(suggest using type narrowing instead)

OWASP Top 10 checks: See references/owasp-top-10.md for vulnerability patterns and detection commands. Report findings as critical with file:line, what the risk is, and how to fix it.

Accessibility checks: Check references/accessibility-checklist.md for a11y detection commands and testing procedures. Report these as important because they exclude real users from using the app.

Monitoring/Observability: Look for error tracking tools (Sentry, DataDog, NewRelic), structured logging libraries (winston, pino), health check endpoints, and watch out for console.logs making it to production. Report missing observability as important for production systems.

确定包管理器并运行相应的审计：

```
package-lock.json
```
→
```
npm audit --json
```
```
pnpm-lock.yaml
```
→
```
pnpm audit --json
```
```
yarn.lock
```
→
```
yarn audit --json
```

requirements.txt

poetry.lock

→

pip-audit --format json

或

safety check --json

```
Cargo.toml
```
→
```
cargo audit --json
```

go.mod

→

go list -json -m all | nancy sleuth

*.csproj

→

dotnet list package --vulnerable --include-transitive

密钥扫描： 需要TruffleHog的使用帮助？查看 [references/secret-scanning.md] 获取扫描当前文件和Git历史记录的指南。

解析这些工具的JSON输出，并将发现的问题整合到审计报告中。

TypeScript项目（如果存在tsconfig.json）：

检查是否启用了
```
strict
```
模式（如果为false或缺失则属于严重问题）
统计显式使用
```
any
```
的次数（这会破坏类型安全性）
统计使用
```
as
```
或
```
<Type>
```
进行类型断言的次数（建议使用类型收窄替代）

OWASP Top 10检查： 查看 [references/owasp-top-10.md] 获取漏洞模式和检测命令。将发现的问题标记为严重，并注明文件:行号、风险内容以及修复方法。

可访问性检查： 查看 [references/accessibility-checklist.md] 获取可访问性检测命令和测试流程。将这些问题标记为重要，因为它们会导致部分用户无法正常使用应用。

监控/可观测性： 查找错误跟踪工具（Sentry、DataDog、NewRelic）、结构化日志库（winston、pino）、健康检查端点，并注意是否有console.log进入生产环境。对于生产系统，缺失可观测性属于重要问题。

3. Detect Tech Stack and Understand Project

3. 检测技术栈并了解项目

Figure out the tech stack: Need help identifying package managers, frameworks, cloud platforms, or IaC tools? See references/tech-stack-detection.md for the complete detection guide.

Build a summary that covers: language(s), framework, build tools, testing framework, cloud platform, IaC tools, and CI/CD platform.

Framework best practices:

Once you know what framework they're using, check the relevant patterns guide:

Next.js/React → references/framework-patterns-nextjs.md
Nuxt/Vue → references/framework-patterns-nuxt.md
ASP.NET Core / .NET → references/framework-patterns-dotnet.md
Entity Framework → references/entity-framework.md
Other frameworks → Use WebSearch to look up current best practices and common mistakes

Performance testing (if Chrome MCP is available):

If this is a web app and you have access to chrome-devtools MCP:

Ask the user: "Want me to run performance tests? Provide a URL or say skip."
If they give you a URL, use Chrome MCP to run a Lighthouse-style audit
Report Core Web Vitals (LCP, FID, CLS), bundle size, unoptimized images, and render-blocking resources

Don't forget to also check the project structure, documentation quality, and CI/CD setup.

确定技术栈： 需要帮助识别包管理器、框架、云平台或IaC工具？查看 [references/tech-stack-detection.md] 获取完整的检测指南。

构建包含以下内容的摘要：语言、框架、构建工具、测试框架、云平台、IaC工具和CI/CD平台。

框架最佳实践：

确定使用的框架后，查看相应的模式指南：

Next.js/React → [references/framework-patterns-nextjs.md]
Nuxt/Vue → [references/framework-patterns-nuxt.md]
ASP.NET Core / .NET → [references/framework-patterns-dotnet.md]
Entity Framework → [references/entity-framework.md]
其他框架 → 使用WebSearch查找当前最佳实践和常见错误

性能测试（如果Chrome MCP可用）：

如果这是一个Web应用且你有权访问chrome-devtools MCP：

询问用户："是否需要我运行性能测试？请提供URL或输入跳过。"
如果用户提供URL，使用Chrome MCP运行类似Lighthouse的审计
报告核心Web指标（LCP、FID、CLS）、包大小、未优化的图片和阻塞渲染的资源

不要忘记检查项目结构、文档质量和CI/CD配置。

4. Critical Issues (Show Details Immediately)

4. 严重问题（立即显示详情）

Surface these issues with full context right away - don't bury them:

Security (from tools + manual review)

Secrets found by trufflehog - show file:line, what type of secret, and severity
Vulnerable dependencies from npm/pip/cargo/dotnet audit - package name, CVE, severity
Hardcoded credentials or API keys sitting in the code
Missing authentication or authorization checks
Unsafe ways of handling data
Sensitive endpoints that are exposed
.NET projects: see auth, data, crypto

TypeScript Configuration (if it's a TypeScript project)

strict mode is disabled or missing from tsconfig.json
explicit
```
any
```
types being used (this defeats the whole point of TypeScript)
type casting/assertions (suggest type narrowing instead)

Breaking Problems

Build failures or broken configuration
Missing dependencies that are critical
Incompatible version requirements
Database migrations that can't be rolled back
Entity Framework projects: see references/entity-framework.md

Data Loss Risks

Operations running without validation
Missing error handling in paths that matter
Race conditions in how data is handled

立即全面展示这些问题的上下文——不要隐藏它们：

安全问题（来自工具+手动评审）

TruffleHog发现的密钥——显示文件:行号、密钥类型和严重程度
npm/pip/cargo/dotnet审计发现的易受攻击依赖项——包名称、CVE编号、严重程度
代码中硬编码的凭据或API密钥
缺失身份验证或授权检查
不安全的数据处理方式
暴露的敏感端点
.NET项目：查看 auth、data、crypto

TypeScript配置（如果是TypeScript项目）

tsconfig.json中strict模式被禁用或缺失
显式使用
```
any
```
类型（这完全违背了TypeScript的设计初衷）
类型转换/断言（建议使用类型收窄替代）

破坏性问题

构建失败或配置损坏
缺失关键依赖项
版本要求不兼容
无法回滚的数据库迁移
Entity Framework项目：查看 [references/entity-framework.md]

数据丢失风险

未验证就运行的操作
关键路径中缺失错误处理
数据处理中的竞争条件

5. High-Level Findings (Summary Only)

5. 高级发现（仅摘要）

Organize what you found into categories with counts and brief summaries. Need help with the full category breakdown? Check references/report-template.md.

Categories to cover:

Architecture & Structure
Tech Debt
Testing
Documentation
Dependencies
Performance
Developer Experience
Best Practices

For each one: give a brief assessment, count the major issues, and summarize the patterns you're seeing. Don't list every single detail here - that's what "Areas to Investigate" is for.

将发现的问题按类别组织，包含数量和简要摘要。需要完整的类别划分帮助？查看 [references/report-template.md]。

涵盖的类别：

架构与结构
技术债务
测试
文档
依赖项
性能
开发者体验
最佳实践

对于每个类别：给出简要评估、统计主要问题的数量，并总结你发现的模式。不要在这里列出每个细节——这些内容放在"需深入调查的领域"部分。

Output Format

输出格式

Structure your audit report like this (see references/report-template.md for examples):

Tool Check - What tools are available, what's missing
Tech Stack - Languages, frameworks, cloud platform, CI/CD
Security Scan Results - What trufflehog, npm audit, and OWASP checks found
TypeScript Check - Strict mode status, any usage, type casting
Accessibility Check - Missing alt text, ARIA labels, keyboard support
Monitoring/Observability - Error tracking, logging, health endpoints
Performance - If Chrome MCP is available and user provided a URL
Critical Issues 🚨 - Detailed breakdown with file:line, what the risk is, how to fix it
Audit Summary - Overall health rating plus brief assessment for each category
Areas to Investigate - Offer to dive deeper into specific areas with file:line details

按以下结构组织审计报告（查看 [references/report-template.md] 获取示例）：

工具检查 - 可用工具和缺失工具
技术栈 - 语言、框架、云平台、CI/CD
安全扫描结果 - TruffleHog、npm审计和OWASP检查的发现
TypeScript检查 - Strict模式状态、any类型使用情况、类型转换
可访问性检查 - 缺失替代文本、ARIA标签、键盘支持
监控/可观测性 - 错误跟踪、日志记录、健康端点
性能 - 如果Chrome MCP可用且用户提供了URL
严重问题 🚨 - 详细分解，包含文件:行号、风险内容和修复方法
审计摘要 - 整体健康评级以及每个类别的简要评估
需深入调查的领域 - 提供对特定领域进行深入分析的选项，并给出文件:行号细节

Investigation Process

调查流程

When the user asks you to investigate a specific area:

Search for relevant patterns in the code
Give them file:line references so they can jump right to it
Show specific examples of what you found
Suggest concrete fixes they can implement
Prioritize by what will have the most impact

当用户要求你调查特定领域时：

在代码中搜索相关模式
提供文件:行号引用，方便用户直接定位
展示你发现的具体示例
建议可实施的具体修复方案
按影响优先级排序

Tool Output Handling

工具输出处理

Parse the JSON output from security tools and work the findings into your report:

Group them by severity (critical → low)
Show which package or file, what the vulnerability is, and how to fix it
Link to the CVE or advisory when you can
For trufflehog results, make it clear if the secret is in git history vs current files

If a tool fails to run, note it and keep going - don't let one tool failure block the entire audit.

解析安全工具的JSON输出并将发现的问题整合到报告中：

按严重程度分组（严重→低）
显示涉及的包或文件、漏洞内容以及修复方法
尽可能链接到CVE或咨询页面
对于TruffleHog的结果，明确说明密钥是在Git历史记录中还是当前文件中

如果工具运行失败，记录下来并继续——不要让单个工具的故障阻碍整个审计。

Guidelines

指南

Be brutally honest:

Call out bad code. Don't soften it.
If something is a mess, say it's a mess
No hedging with "might", "could", or "possibly"
Don't say "consider fixing" - say "fix this" or "this is wrong"
If strict mode is off in TypeScript, that's a critical issue, not a suggestion
Explicit
```
any
```
defeats the whole point of TypeScript - call it out as breaking type safety
Tech debt is tech debt, not "areas for improvement"

Focus and priority:

Only report findings they can actually act on, not theoretical problems
Prioritize by real impact on security, stability, and maintainability
Skip nitpicks that linters should catch
Tool findings are facts - just report them straight

Context matters:

Startup MVPs can have some shortcuts, but still call them out
Enterprise systems need to meet higher standards
Personal projects can be looser, but point out what's missing
Don't excuse bad practices just because "it works right now"

Tone:

Be direct and clear, not diplomatic
If tests are missing, say "no tests" not "test coverage could be improved"
If docs are bad, say "documentation is inadequate" not "could benefit from more documentation"
Be specific about what's wrong and why it matters
Acknowledge what's good, but keep it brief - don't pad with praise

绝对诚实：

指出糟糕的代码。不要委婉。
如果某个部分一团糟，直接说它一团糟
不要使用"可能"、"也许"或"大概"这类模糊词汇
不要说"考虑修复"——要说"修复这个"或"这是错误的"
如果TypeScript的strict模式关闭，这是严重问题，不是建议
显式使用
```
any
```
完全违背了TypeScript的初衷——指出这会破坏类型安全性
技术债务就是技术债务，不是"改进领域"

聚焦与优先级：

只报告用户可以实际采取行动的发现，而非理论问题
按对安全性、稳定性和可维护性的实际影响排序
跳过应该由代码检查器捕获的小问题
工具的发现是事实——直接报告

上下文很重要：

初创公司的MVP可以有一些捷径，但仍然要指出来
企业系统需要满足更高的标准
个人项目可以更宽松，但要指出缺失的部分
不要因为"现在能用"就为糟糕的实践找借口

语气：

直接且清晰，不要委婉
如果没有测试，就说"没有测试"，而不是"测试覆盖率可以提高"
如果文档很差，就说"文档不足"，而不是"可以补充更多文档"
明确说明哪里错了以及为什么重要
简要认可做得好的部分——不要用赞美凑篇幅

References

参考资料

Need more detailed guidance? Check these references:

Tech Stack Detection - How to figure out what package managers, frameworks, cloud platforms, and IaC tools they're using
Secret Scanning Reference - Complete guide to running TruffleHog on both current files and git history, plus common patterns and how to fix them
OWASP Top 10 Reference - Detection patterns and grep commands for finding all OWASP Top 10 vulnerabilities, with severity guidelines
Accessibility Checklist - Practical commands for finding a11y issues and testing for WCAG compliance
Report Template - What the final report should look like, with example critical issues

Framework-specific patterns:

Next.js / React Patterns - Best practices, common anti-patterns, and what to check in Next.js/React projects
Nuxt / Vue Patterns - Best practices, common anti-patterns, and what to check in Nuxt/Vue projects
.NET Framework Patterns - ASP.NET Core, async patterns, DI, testing, and code quality anti-patterns for .NET 6+
Entity Framework Patterns - Performance, security, and correctness issues in Entity Framework Core
.NET Security: Auth - Authentication, authorization, CSRF, and redirect validation for ASP.NET Core
.NET Security: Data - SQL injection, deserialization, mass assignment, input validation, and XXE
.NET Security: Crypto - Secrets management, cryptographic failures, and security headers

需要更详细的指导？查看这些参考资料：

Tech Stack Detection - 如何识别包管理器、框架、云平台和IaC工具
Secret Scanning Reference - 在当前文件和Git历史记录上运行TruffleHog的完整指南，以及常见模式和修复方法
OWASP Top 10 Reference - 查找所有OWASP Top 10漏洞的检测模式和grep命令，以及严重程度指南
Accessibility Checklist - 查找可访问性问题的实用命令和WCAG合规性测试
Report Template - 最终报告的示例，包含严重问题示例

框架特定模式：

Next.js / React Patterns - Next.js/React项目的最佳实践、常见反模式和检查要点
Nuxt / Vue Patterns - Nuxt/Vue项目的最佳实践、常见反模式和检查要点
.NET Framework Patterns - ASP.NET Core、异步模式、DI、测试和.NET 6+的代码质量反模式
Entity Framework Patterns - Entity Framework Core中的性能、安全和正确性问题
.NET Security: Auth - ASP.NET Core的身份验证、授权、CSRF和重定向验证
.NET Security: Data - SQL注入、反序列化、批量赋值、输入验证和XXE
.NET Security: Crypto - 密钥管理、加密失败和安全头