Audit Notes CLI

Noise-Free Smart Contract Security for Pull Requests

Audit Notes is a CI-first smart contract audit CLI built on top of Slither. It focuses on signal over noise by failing CI only when new HIGH or CRITICAL issues are introduced.

The core scan and CI gating are free forever. Audit Notes PRO adds actionable remediation guidance, not more noise.

Why Audit Notes?

Most security tools are noisy.

Audit Notes is opinionated:

• Catch new risks, not old ones

• Fail CI only on HIGH / CRITICAL regressions

• Generate outputs developers can actually read

• Work locally and in CI

• No dashboards. No accounts. Just files.

Features

#🆓 Free (No license required)

• Static analysis via Slither

• Markdown audit notes

• SARIF output (GitHub Security tab)

• PR diffing against base branch

• CI gating on new HIGH / CRITICAL issues

• Noise suppression profiles

• Stable Finding IDs

💎 PRO (License required)

• Remediation recommendations

• Fix hints and guidance

• audit-note explain

• Designed for solo auditors and teams

• Works locally and in CI

• Offline licence validation ( no phone-home)

Installation

Audit Notes is distributed via npm.

• npm install -g audit-notes-cli

Or run directly with:

• npx audit-notes-cli

Prerequisites

Audit Notes expects a Slither JSON report.

Generate one with:

• slither . --json slither.json || true

Usage

Run a basic audit (Free)

• npx audit-notes run

Generates:

output/AUDIT_NOTES.md output/AUDIT_NOTES.json

Generate SARIF (Free)

• npx audit-notes run --sarif

Generates:

output/audit-notes.sarif

Upload this to GitHub’s Security tab using upload-sarif.

PR diff mode (Free, CI-safe)

• npx audit-notes run --diff --base slither-main.json

Behavior:

• Compares current findings with base

• Fails CI only if new HIGH / CRITICAL issues are introduced

• Safe to run in Github Actions

Finding IDs (Important)

Each finding includes a stable Finding ID.

Example:

Finding ID: 89c733fa72c96b0346f84b896f53f0e79c52bb41

These IDs are used to:

• Link recommendations → findings

• Explain findings

• Track issues across PRs

• Support enterprise CI contracts

PRO Usage

PRO unlocks guidance on how to fix issues, not basic scanning.

Set your license

• export AUDIT_NOTES_LICENSE=AN-PRO-XXXX
• export AUDIT_NOTES_SECRET=your_secret_here

Generate remediation recommendations (PRO)

• npx audit-notes run --recommendations

Generates:

output/recommendations.json

Generate fix hints (PRO)

• npx audit-notes run --fix-hints

Generates:

output/fix-hints.json

• Without a license

Running PRO commands without a license will show:

" This feature requires Audit Notes PRO. Set AUDIT_NOTES_LICENSE to continue."

Explain a Finding (PRO-Enhanced)

audit-notes explain

Outputs:

• Finding description

• Severity

• Detector

• Optional remediation guidance (PRO)

Output Formats

audit-notes run --format=md # Default audit-notes run --format=json audit-notes run --format=summary

Summary format is ideal for PR comments.

Free vs PRO

| Feature | Free | PRO | | --------------------------- | ---- | --- | | Static analysis (Slither) | ✅ | ✅ | | Markdown audit report | ✅ | ✅ | | SARIF (GitHub Security tab) | ✅ | ✅ | | PR diff & CI gating | ✅ | ✅ | | Noise suppression profiles | ✅ | ✅ | | Finding IDs | ✅ | ✅ | | Explain findings | ❌ | ✅ | | Remediation recommendations | ❌ | ✅ | | Fix hints & guidance | ❌ | ✅ | | Solo usage | ✅ | ✅ | | Team / CI usage | ✅ | ✅ | | Priority support | ❌ | ✅ |

GitHub Actions

Audit Notes is designed to run in CI.

Typical workflow:

• Run Slither on base branch

• Run Slither on PR

• Run audit-notes run --diff --base slither-main.json

Optionally upload SARIF

Philosophy

Audit Notes is intentionally minimal:

• No dashboards

• No accounts

• No phone-home

• Files you can review, diff, and commit

Security tools should help you think less, not more.

License & Plans

Audit Notes is free to use for scanning and CI gating.

PRO plans

• PRO Solo — individual auditors

• PRO Team — shared repos and CI

PRO unlocks:

• Remediation recommendations

• Fix hints

Pricing is simple and transparent.

Roadmap

• Improve recommendation quality

• Better PR summaries

• Optional team-level enforcement (later)

• No bloat. No feature creep.

Contributing

Issues and PRs are welcome.

This project prioritizes clarity, signal, and developer trust.

One-line summary

• Free for scanning and CI gating.
• PRO for guidance on how to fix what’s found.

📧 Contact

For support, collaboration, or technical questions:

• GitHub: @cryptosfinders
• Twitter: @cryptos_finders