# audit-report-generator

Generate professional PDF audit reports from markdown findings. Use when converting security audit findings to formal PDF reports, creating audit deliverables, or formatting vulnerability assessments. Triggers on requests to "generate audit report", "create PDF report", "format findings as PDF", or any audit report generation task.

- **Kind:** skill
- **Source:** https://github.com/NewmanXBT/normans-skills
- **Page:** https://forefy.com/skills/74cbc38a-9166-4aaf-9bb4-b30ebd869d0a
- **API (JSON + files):** https://forefy.com/api/skills/74cbc38a-9166-4aaf-9bb4-b30ebd869d0a

---

## SKILL.md

---
name: audit-report-generator
description: Generate professional PDF audit reports from markdown findings. Use when converting security audit findings to formal PDF reports, creating audit deliverables, or formatting vulnerability assessments. Triggers on requests to "generate audit report", "create PDF report", "format findings as PDF", or any audit report generation task.
---

# Audit Report Generator

## Overview

This skill transforms security audit findings written in markdown into professional PDF audit reports using pandoc and the eisvogel LaTeX template. It produces polished, publication-ready deliverables suitable for client delivery.

## Pre-Ask Questions (Required)

**IMPORTANT**: Before generating any report, you MUST ask the user these questions using AskUserQuestion tool:

1. **Company/Firm Name**: What is your company or firm name?
   - First time: Ask and save the answer as default for all future reports
   - Subsequent reports: Use saved default, but allow user to override
   - If no preference: "Independent Security Researcher"

2. **Client/Protocol Name**: What is the name of the protocol being audited?
   - Example: "Uniswap"

3. **Report Title**: What should the report title be?
   - Default: "[Protocol Name] Security Audit Report"

Store the company name preference so it becomes the default option for future audit reports in this project.

## Prerequisites

Before generating reports, ensure these dependencies are installed:

```bash
# Install pandoc (markdown to PDF converter)
brew install pandoc

# Install LaTeX (required for PDF compilation)
brew install --cask mactex-no-gui
# OR for a lighter installation:
brew install basictex

# After installing basictex, you may need:
sudo tlmgr update --self
sudo tlmgr install footnotebackref titling
```

Verify installation:
```bash
pandoc --version
pdflatex --version
```

## Quick Start Workflow

### 1. Prepare Your Markdown Report

Create a markdown file following the report structure (see `references/report-structure.md`). The file must include:

- YAML frontmatter with title, author, and date
- LaTeX title page block
- Standard audit report sections

### 2. Generate the PDF

```bash
# Basic usage (output goes to same directory as input)
bash ~/.claude/skills/audit-report-generator/scripts/make-pdf.sh report.md

# Specify output location
bash ~/.claude/skills/audit-report-generator/scripts/make-pdf.sh report.md --out output/final-report.pdf

# Use custom logo
bash ~/.claude/skills/audit-report-generator/scripts/make-pdf.sh report.md --logo /path/to/client-logo.pdf
```

## Input Format Specification

### YAML Frontmatter

Every report must begin with:

```yaml
---
title: Protocol Audit Report
author: Your Firm Name
date: October 17, 2024
header-includes:
  - \usepackage{titling}
  - \usepackage{graphicx}
---
```

### Title Page

Include the LaTeX title page after the frontmatter:

```latex
\begin{titlepage}
    \centering
    \begin{figure}[h]
        \centering
        \includegraphics[width=0.5\textwidth]{logo.pdf}
    \end{figure}
    \vspace*{2cm}
    {\Huge\bfseries Protocol Audit Report\par}
    \vspace{1cm}
    {\Large Version 1.0\par}
    \vspace{2cm}
    {\Large\itshape Your Firm Name\par}
    \vfill
    {\large \today\par}
\end{titlepage}

\maketitle
```

### Finding Format

Each vulnerability finding should follow the layout in `references/finding-layout.md`:

```markdown
### [M-1] Unchecked return value allows silent transfer failures

**Description**

[Technical description of the vulnerability]

**Impact**

[Consequences if exploited]

**Proof of Concepts**

[Code or steps to reproduce]

**Recommended mitigation**

[How to fix it]
```

Severity prefixes: `C-#` (Critical), `H-#` (High), `M-#` (Medium), `L-#` (Low), `I-#` (Informational), `G-#` (Gas)

## Script Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `<input.md>` | Source markdown file (required) | - |
| `--out <path>` | Output PDF path | `<input>.pdf` |
| `--logo <path>` | Logo PDF for title page | Required if report uses logo |
| `--template <path>` | Custom LaTeX template | Bundled `assets/eisvogel.latex` |

## Useful LaTeX in Markdown

| Command | Purpose |
|---------|---------|
| `\newpage` | Force page break |
| `\vspace{1cm}` | Add vertical space |
| `\textbf{text}` | Bold text |

## Troubleshooting

### "pdflatex not found"
Install LaTeX: `brew install --cask mactex-no-gui`

### "footnotebackref.sty not found"
Install the package: `sudo tlmgr install footnotebackref`

### Logo not appearing
- Ensure logo is PDF format (not PNG/JPG)
- Check the `logo.pdf` path is accessible from the markdown file's directory

## Resources

### scripts/
- `make-pdf.sh` - Main PDF generation script

### assets/
- `eisvogel.latex` - LaTeX template (professional formatting)

### references/
- `finding-layout.md` - Template for individual findings
- `report-structure.md` - Complete report structure guide

## assets

```

```

## assets/eisvogel.latex

```

```

## references

```

```

## references/finding-layout.md

# Finding Layout Template

Use this format for each vulnerability finding in your audit report.

## Format

```markdown
### [S-#] TITLE (Root + Impact)
**Description**

[Detailed description of the vulnerability, including technical context and affected code]

**Impact**

[Explain the consequences if this vulnerability is exploited]

**Proof of Concepts**

[Code snippets, test cases, or step-by-step reproduction instructions]

**Recommended mitigation**

[Specific recommendations to fix the vulnerability]
```

## Severity Prefixes

| Prefix | Severity |
|--------|----------|
| C-#    | Critical |
| H-#    | High     |
| M-#    | Medium   |
| L-#    | Low      |
| I-#    | Informational |
| G-#    | Gas Optimization |

## Example

```markdown
### [M-1] Unchecked return value in token transfer allows silent failures

**Description**

The `withdraw()` function in `Vault.sol:L142` calls `token.transfer()` without checking the return value. Some ERC20 tokens (like USDT) return `false` on failure instead of reverting.

**Impact**

Users may believe their withdrawal succeeded when tokens were not actually transferred, leading to accounting discrepancies and potential loss of funds.

**Proof of Concepts**

```solidity
function testUncheckedTransfer() public {
    // Setup: use a token that returns false on failure
    MockFailingToken token = new MockFailingToken();
    vault.withdraw(100);
    // Balance unchanged but no revert
    assertEq(token.balanceOf(user), 0);
}
```

**Recommended mitigation**

Use OpenZeppelin's `SafeERC20` library:

```solidity
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
using SafeERC20 for IERC20;

// Replace: token.transfer(to, amount);
// With:
token.safeTransfer(to, amount);
```
```

## references/report-structure.md

# Audit Report Structure Template

This template defines the complete structure for a professional security audit report.

## YAML Frontmatter

```yaml
---
title: Protocol Audit Report
author: Your Firm Name
date: October 17, 2024
header-includes:
  - \usepackage{titling}
  - \usepackage{graphicx}
---
```

## Title Page (LaTeX)

```latex
\begin{titlepage}
    \centering
    \begin{figure}[h]
        \centering
        \includegraphics[width=0.5\textwidth]{logo.pdf}
    \end{figure}
    \vspace*{2cm}
    {\Huge\bfseries Protocol Audit Report\par}
    \vspace{1cm}
    {\Large Version 1.0\par}
    \vspace{2cm}
    {\Large\itshape Your Firm Name\par}
    \vfill
    {\large \today\par}
\end{titlepage}

\maketitle
```

## Required Sections

### 1. Table of Contents

```markdown
# Table of Contents
- [Table of Contents](#table-of-contents)
- [About Your Firm](#about-your-firm)
- [Disclaimer](#disclaimer)
- [Risk Classification](#risk-classification)
- [Protocol Overview](#protocol-overview)
- [Audit Scope](#audit-scope)
- [Executive Summary](#executive-summary)
    - [Summary](#summary)
    - [Issues Found](#issues-found)
    - [Summary of Findings](#summary-of-findings)
- [Findings](#findings)
  - [Critical](#critical)
  - [High](#high)
  - [Medium](#medium)
  - [Low](#low)
  - [Informational](#informational)
  - [Gas](#gas)
```

### 2. About Section

Describe your firm's expertise and track record.

### 3. Disclaimer

Standard legal disclaimer about audit scope and limitations.

### 4. Risk Classification Matrix

```markdown
|                | Impact: High | Impact: Medium | Impact: Low |
|----------------|--------------|----------------|-------------|
| Likelihood: High   | Critical     | High           | Medium      |
| Likelihood: Medium | High         | Medium         | Low         |
| Likelihood: Low    | Medium       | Low            | Low         |
```

### 5. Protocol Overview

Describe the protocol's purpose, key features, and architecture.

### 6. Audit Scope

List the files and commit hash included in the audit.

### 7. Executive Summary

#### Summary Table

```markdown
| Project Name  | [Protocol Name]                 |
|---------------|---------------------------------|
| Repository    | [Link to repo](#)               |
| Commit        | [Commit hash](#)                |
| Audit Timeline| [Date range]                    |
| Methods       | Manual Review, Stateful Fuzzing |
```

#### Issues Found Table

```markdown
|               | Count |
|---------------|-------|
| Critical Risk | 0     |
| High Risk     | 0     |
| Medium Risk   | 0     |
| Low Risk      | 0     |
| Informational | 0     |
| Gas Optimizations | 0 |
| **Total Issues** | **0** |
```

#### Summary of Findings Table

```markdown
| ID   | Description                      | Status     |
|------|----------------------------------|------------|
| [M-1](#m-1) | Brief description      | Resolved   |
| [I-1](#i-1) | Brief description      | Acknowledged |
```

### 8. Findings Sections

Each severity level gets its own section:

```markdown
\newpage

# Findings
## Critical
## High
## Medium
## Low
## Informational
## Gas
```

Use `\newpage` for page breaks between major sections.

## Useful LaTeX Commands

| Command | Purpose |
|---------|---------|
| `\newpage` | Force page break |
| `\vspace{1cm}` | Add vertical space |
| `\textbf{text}` | Bold text |
| `\textit{text}` | Italic text |
| `\begin{itemize}...\end{itemize}` | Bullet list |

## Complete Example

See the skill's test files for a complete working example.

## scripts

```

```

## scripts/make-pdf.sh

```bash

```