Code Audit

Code Audit

Perform comprehensive code audits and generate structured markdown reports.

Codex note: This skill references Claude Code subagents (Task(...)). In Codex, run the equivalent steps with tool calls (for example functions.shell_command and multi_tool_use.parallel) or run them sequentially. See ../../COMPATIBILITY.md.

Workflow

1. Scope: Determine target (full repo, specific path, or focused concern)
2. Discovery: List and categorise source files
3. Analysis: Evaluate each category systematically
4. Report: Generate markdown report using template format
5. GitHub Issues: Create issues using scripts/create_issue.sh:
   • First: Create individual issues for each actionable recommendation
   • Then: Create the full audit report with subtasks linking to each issue

Time Estimates

For large projects, consider:

• Auditing by module/package
• Focusing on specific concerns (security-only, performance-only)
• Auditing recently changed files only

Analysis Categories

Severity Levels

Scoring

Rate each applicable category out of 10:

• Architecture, Thread Safety, Error Handling
• DRY Compliance, SOLID Compliance
• Security, Performance, Testability

Overall score: weighted average (bugs and security weighted higher).

Security-Focused Audit

When focusing on security, prioritise:

1. Input Validation

   • User input sanitisation
   • SQL/NoSQL injection vectors
   • Command injection risks
   • Path traversal vulnerabilities

2. Authentication & Authorisation

   • Session management
   • Token handling
   • Permission checks
   • Privilege escalation paths

3. Data Protection

   • Credential storage
   • Sensitive data exposure
   • Encryption usage
   • Logging of sensitive data

4. Dependencies

   • Known vulnerabilities (CVEs)
   • Outdated packages
   • Typosquatting risks

Report Format

See references/report-template.md for the exact output structure.

Key formatting rules:

• Two-column tables for issue metadata (severity, location, impact, recommendation)
• Code blocks with language hints for all code examples
• Horizontal rules between major sections
• ASCII diagrams in code blocks for architecture
• Summary statistics table at the end
• Prioritised recommendations (P0/P1/P2/P3)
• Never use em-dashes

Output

Step 1: Create Individual Recommendation Issues

For each actionable recommendation, create a separate issue using the format in references/issue-template.md. Capture the returned issue URL for each.

bash scripts/create_issue.sh \
  --project "[Project Name]" \
  --title "[Brief issue title]" \
  --label "code-audit,priority:[level],[category]" \
  --body "$ISSUE_BODY"

Priority labels:

• P0/Critical: priority:critical
• P1/High: priority:high
• P2/Medium: priority:medium
• P3/Low: priority:low

Category labels (use as appropriate):

• security, performance, bug, technical-debt
• architecture, observability, testing, documentation

Step 2: Create Full Audit Report with Subtasks

Append a "Related Issues" section to the full report with subtasks linking to each individual issue:

## Related Issues

- [ ] #123 - Fix race condition in data index map
- [ ] #124 - Add thread safety to RedisClient
- [ ] #125 - Extract side validation utility
- [ ] #126 - Add metrics and observability

Then create the main audit issue:

bash scripts/create_issue.sh \
  --project "[Project Name]" \
  --title "Code Audit Report - [Project] - [Date]" \
  --label "code-audit" \
  --body "$FULL_REPORT_WITH_SUBTASKS"

With a specific repository, add --repo "owner/repo".

When to Split Audits

Create separate audit reports when:

• Different parts of the codebase have different owners
• Findings span multiple priority levels with different timelines
• The report exceeds ~500 lines (becomes hard to track)

Confirm all issue URLs with the user after creation.

Subagent Usage

Use subagents to parallelize analysis and reduce main context bloat.

Phase 2: Parallel Analysis

For medium to large codebases, launch up to 4 Explore agents in parallel to analyze different categories simultaneously:

Launch parallel Explore agents:

1. Architecture Agent:
   "Analyze the codebase architecture. Look for:
   - Separation of concerns violations
   - Circular dependencies
   - Component structure issues
   - Coupling problems between modules
   Return: List of findings with file:line references and severity"

2. Security Agent:
   "Perform security analysis. Scan for:
   - Input validation gaps (SQL injection, XSS, command injection)
   - Credential handling issues (hardcoded secrets, improper storage)
   - Authentication/authorization flaws
   - OWASP Top 10 vulnerabilities
   Return: List of findings with file:line references and severity"

3. Performance Agent:
   "Analyze performance issues. Find:
   - O(n²) or worse algorithms
   - Unnecessary object copies or allocations
   - N+1 query patterns
   - Missing caching opportunities
   - Inefficient data structures
   Return: List of findings with file:line references and severity"

4. Code Quality Agent:
   "Check code quality and best practices. Look for:
   - SOLID principle violations (god classes, tight coupling)
   - DRY violations (duplicated logic, copy-paste code)
   - Magic numbers and missing documentation
   - Broad exception handling
   - Resource leaks
   Return: List of findings with file:line references and severity"

Each agent returns structured findings. Main context synthesizes into final report.

Benefits:

• 4x faster analysis on large codebases
• Exploration output stays in subagent context (reduces token usage)
• Main context receives only synthesized findings

Phase 5: Background Issue Creation

After generating the report, create GitHub issues in background:

Launch background agent:
"Create GitHub issues for each audit finding using scripts/create_issue.sh.
Findings to create:
[List of findings with titles, labels, and bodies]

For each finding:
1. Create issue with appropriate labels (priority:X, category)
2. Capture the issue URL
3. Return all created issue URLs when complete"

Main context can continue summarizing results while issues are created.

When to use subagents:

• Codebase > 5,000 LOC: Use parallel analysis agents
• More than 5 issues to create: Use background issue creation
• Time-sensitive audit: Always use parallel agents

When to skip subagents:

• Single file audit
• Focused audit on specific concern (one category only)
• Small codebase < 1,000 LOC

Related Skills

• race-condition-audit: Deep-dive on concurrency issues
• fix-github-issue: Implement fixes from audit recommendations