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.

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

1. Check Available Tools

Start by checking what tools you have available:

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.

2. Detect Project Type and Run Audits

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 or 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.

3. Detect Tech Stack and Understand Project

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.

4. Critical Issues (Show Details Immediately)

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

5. High-Level Findings (Summary Only)

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.

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

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.

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

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

codebase-audit