audit-notes-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crypto Finder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# AI-Assisted Audit 
+
+Professional **security pre-review tooling** for smart contracts.
+
+This is NOT:
+- an AI auditor
+- a vulnerability scanner
+- severity scoring software
+
+This IS:
+- a thinking assistant for auditors
+- deterministic security analysis
+- structured audit context before full audits
+
+---
+
+## What it generates
+- Privileged role map
+- External call & reentrancy surfaces
+- State mutation & invariant hints
+- Upgradeability risks
+- Critical audit questions
+
+Output: `AUDIT_NOTES.md`
+
+---
+
+## Why this exists
+Most audit issues are missed due to **lost context**, not missing tools.
+
+This tool extracts structure so humans reason better.
+
+---
+
+## Usage (CLI)
+
+```bash
+slither . --json slither.json
+export AUDIT_NOTES_LICENSE=AN-XXXX
+export OPENAI_API_KEY=sk-...
+audit-notes .

package/dist/analyzer/accessControl.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRoles = extractRoles;
+function extractRoles(slither) {
+    const roles = new Map();
+    for (const [, rawContract] of Object.entries(slither.contracts)) {
+        const contract = rawContract;
+        for (const func of contract.functions || []) {
+            for (const mod of func.modifiers || []) {
+                if (mod.includes("onlyOwner")) {
+                    addFn(roles, "OWNER", func.name);
+                }
+                if (mod.includes("onlyRole")) {
+                    addFn(roles, "ROLE_BASED", func.name);
+                }
+            }
+        }
+    }
+    return Object.fromEntries([...roles.entries()].map(([k, v]) => [k, [...v]]));
+}
+function addFn(map, role, fn) {
+    if (!map.has(role))
+        map.set(role, new Set());
+    map.get(role).add(fn);
+}

package/dist/analyzer/detectors.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeDetectors = analyzeDetectors;
+function analyzeDetectors(detectors) {
+    return detectors.map(d => ({
+        check: d.check,
+        impact: d.impact,
+        confidence: d.confidence,
+        description: d.description,
+        locations: (d.elements || []).map((e) => ({
+            contract: e.contract,
+            function: e.name,
+            lines: e.source_mapping?.lines
+        }))
+    }));
+}

package/dist/analyzer/externalCalls.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExternalCalls = extractExternalCalls;
+function extractExternalCalls(slither) {
+    const calls = [];
+    for (const [, rawContract] of Object.entries(slither.contracts)) {
+        const contract = rawContract;
+        for (const func of contract.functions || []) {
+            for (const call of func.external_calls || []) {
+                calls.push({
+                    function: func.name,
+                    target: call.contract_name,
+                    type: call.type,
+                    stateUpdatedAfter: (func.state_variables_written || []).length > 0
+                });
+            }
+        }
+    }
+    return calls;
+}

package/dist/analyzer/slither.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSlither = loadSlither;
+const fs_1 = __importDefault(require("fs"));
+function loadSlither(filePath) {
+    const raw = fs_1.default.readFileSync(filePath, "utf8");
+    const json = JSON.parse(raw);
+    if (!json?.results?.detectors) {
+        throw new Error("Invalid Slither JSON: detectors not found");
+    }
+    return {
+        detectors: json.results.detectors
+    };
+}

package/dist/analyzer/stateGraph.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractStateWrites = extractStateWrites;
+function extractStateWrites(slither) {
+    const state = new Map();
+    for (const [, rawContract] of Object.entries(slither.contracts)) {
+        const contract = rawContract;
+        for (const func of contract.functions || []) {
+            for (const v of func.state_variables_written || []) {
+                if (!state.has(v))
+                    state.set(v, new Set());
+                state.get(v).add(func.name);
+            }
+        }
+    }
+    return Object.fromEntries([...state.entries()].map(([k, v]) => [k, [...v]]));
+}

package/dist/analyzer/upgradeability.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectUpgradeability = detectUpgradeability;
+function detectUpgradeability(slither) {
+    const patterns = {
+        uups: false,
+        transparent: false,
+        beacon: false
+    };
+    for (const [, rawContract] of Object.entries(slither.contracts)) {
+        const contract = rawContract;
+        const inherit = contract.inheritance || [];
+        if (inherit.includes("UUPSUpgradeable"))
+            patterns.uups = true;
+        if (inherit.includes("TransparentUpgradeableProxy"))
+            patterns.transparent = true;
+        if (inherit.includes("BeaconProxy"))
+            patterns.beacon = true;
+    }
+    return patterns;
+}

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const license_1 = require("./license");
+const slither_1 = require("./analyzer/slither");
+const detectors_1 = require("./analyzer/detectors");
+const markdown_1 = require("./report/markdown");
+const prompt_1 = require("./llm/prompt");
+const client_1 = require("./llm/client");
+const rules_schema_json_1 = __importDefault(require("./rules/rules.schema.json"));
+const cmd = process.argv[2] ?? "run";
+async function run() {
+    (0, license_1.validateLicense)();
+    const slitherPath = path_1.default.resolve("slither.json");
+    if (!fs_1.default.existsSync(slitherPath)) {
+        throw new Error("slither.json not found. Run `slither <path> --json slither.json` first.");
+    }
+    const slither = (0, slither_1.loadSlither)(slitherPath);
+    const findings = (0, detectors_1.analyzeDetectors)(slither.detectors);
+    let report;
+    if (process.env.OPENAI_API_KEY) {
+        const prompt = (0, prompt_1.buildPrompt)({ findings }, rules_schema_json_1.default);
+        report = await (0, client_1.generateAuditNotes)(prompt);
+    }
+    else {
+        report = (0, markdown_1.generateMarkdown)({ findings });
+    }
+    fs_1.default.mkdirSync("output", { recursive: true });
+    fs_1.default.writeFileSync("output/AUDIT_NOTES.md", report);
+    console.log("✅ Audit notes generated → output/AUDIT_NOTES.md");
+}
+async function main() {
+    try {
+        if (cmd === "run") {
+            await run();
+        }
+        else if (cmd === "check") {
+            (0, license_1.validateLicense)();
+            console.log("✅ License valid");
+        }
+        else if (cmd === "version") {
+            console.log("audit-notes v0.1.0");
+        }
+        else {
+            console.log(`
+Usage:
+  audit-notes run
+  audit-notes check
+  audit-notes version
+`);
+        }
+    }
+    catch (err) {
+        console.error("❌", err.message);
+        process.exit(1);
+    }
+}
+main();

package/dist/invariants/generator.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateInvariantHints = generateInvariantHints;
+function generateInvariantHints(state) {
+    const invariants = [];
+    for (const [variable, writers] of Object.entries(state)) {
+        if (writers.length >= 2) {
+            invariants.push({
+                variable,
+                type: "consistency",
+                hint: `${variable} should remain internally consistent across ${writers.join(", ")}`
+            });
+        }
+        if (variable.toLowerCase().includes("total")) {
+            invariants.push({
+                variable,
+                type: "accounting",
+                hint: `${variable} should equal or exceed sum of dependent balances`
+            });
+        }
+    }
+    return invariants;
+}

package/dist/license.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateLicense = validateLicense;
+function validateLicense() {
+    const key = process.env.AUDIT_NOTES_LICENSE;
+    if (!key) {
+        throw new Error("Missing license key. Set AUDIT_NOTES_LICENSE environment variable.");
+    }
+    if (key.length < 20 || !key.startsWith("AN-")) {
+        throw new Error("Invalid license key format.");
+    }
+    return true;
+}

package/dist/llm/client.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAuditNotes = generateAuditNotes;
+const openai_1 = __importDefault(require("openai"));
+let client = null;
+function getClient() {
+    if (!process.env.OPENAI_API_KEY) {
+        throw new Error("OPENAI_API_KEY not set");
+    }
+    if (!client) {
+        client = new openai_1.default({
+            apiKey: process.env.OPENAI_API_KEY
+        });
+    }
+    return client;
+}
+async function generateAuditNotes(prompt) {
+    const openai = getClient();
+    const res = await openai.chat.completions.create({
+        model: "gpt-4o-mini",
+        temperature: 0,
+        messages: [
+            {
+                role: "system",
+                content: `
+You assist a professional smart contract auditor.
+
+STRICT RULES:
+- Use ONLY provided data
+- Do NOT invent vulnerabilities
+- Do NOT assign severity
+- Do NOT suggest fixes
+- Output structured audit notes and questions only
+        `.trim()
+            },
+            { role: "user", content: prompt }
+        ]
+    });
+    return res.choices[0].message.content ?? "";
+}

package/dist/llm/prompt.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPrompt = buildPrompt;
+function buildPrompt(analysis, rules) {
+    return `
+Produce audit notes with:
+
+1. Privileged roles & risks
+2. External call surfaces
+3. Reentrancy attention areas
+4. State mutation summary & invariants
+5. Upgradeability risks
+6. Critical audit questions (NO conclusions)
+
+DATA:
+${JSON.stringify(analysis, null, 2)}
+
+RULES:
+${JSON.stringify(rules, null, 2)}
+`;
+}

package/dist/report/markdown.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMarkdown = generateMarkdown;
+function generateMarkdown(input) {
+    const byImpact = {};
+    for (const f of input.findings) {
+        const key = f.impact ?? "Unknown";
+        byImpact[key] ?? (byImpact[key] = []);
+        byImpact[key].push(f);
+    }
+    let md = `# Smart Contract Audit Notes\n\n`;
+    md += `## Overview\n`;
+    md += `This document contains **automated audit notes** generated using static analysis tools.\n`;
+    md += `It is intended to **assist auditors and developers** during manual review.\n\n`;
+    md += `> ⚠️ **Disclaimer**\n`;
+    md += `> This report does **not** constitute a full security audit.\n`;
+    md += `> Findings represent **potential risk indicators**, not confirmed vulnerabilities.\n\n`;
+    md += `---\n\n`;
+    md += `## Scope\n`;
+    md += `- Target: Solidity smart contracts in the repository\n`;
+    md += `- Tooling: Slither (static analysis)\n`;
+    md += `- Coverage:\n`;
+    md += `  - Reentrancy patterns\n`;
+    md += `  - Low-level calls\n`;
+    md += `  - Compiler configuration issues\n`;
+    md += `  - Best-practice violations\n`;
+    md += `- Exclusions:\n`;
+    md += `  - Business logic correctness\n`;
+    md += `  - Economic & governance attacks\n`;
+    md += `  - Cross-protocol integrations\n\n`;
+    md += `---\n\n`;
+    md += `## Severity Interpretation\n`;
+    md += `- **High**: Likely exploitable patterns or critical misconfigurations\n`;
+    md += `- **Medium**: Context-dependent risks requiring review\n`;
+    md += `- **Low**: Best-practice or hygiene issues\n`;
+    md += `- **Informational**: Awareness items\n\n`;
+    md += `---\n\n`;
+    md += `## Summary\n`;
+    md += `Total findings identified: **${input.findings.length}**\n\n`;
+    for (const impact of Object.keys(byImpact)) {
+        md += `## ${impact} Severity Findings\n\n`;
+        for (const f of byImpact[impact]) {
+            md += `### ${f.check}\n\n`;
+            md += `${f.description.trim()}\n\n`;
+            if (f.locations.length > 0) {
+                md += `**Relevant Locations:**\n`;
+                for (const l of f.locations) {
+                    md += `- \`${l.contract ?? "?"}::${l.function ?? "?"}\``;
+                    if (l.lines)
+                        md += ` (lines ${l.lines.join(", ")})`;
+                    md += `\n`;
+                }
+                md += `\n`;
+            }
+            md += `---\n\n`;
+        }
+    }
+    md += `## Auditor Review Checklist\n`;
+    md += `- Validate exploitability of reentrancy paths\n`;
+    md += `- Review trust assumptions around low-level calls\n`;
+    md += `- Confirm compiler version risks are acceptable\n`;
+    md += `- Ensure findings align with protocol design intent\n\n`;
+    md += `---\n\n`;
+    md += `*Generated automatically. Manual review is strongly recommended.*\n`;
+    return md;
+}

package/dist/risk/reentrancy.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreReentrancy = scoreReentrancy;
+function scoreReentrancy(calls) {
+    return calls.map(call => {
+        let score = 0;
+        if (call.type === "call")
+            score += 2;
+        if (call.type === "delegatecall")
+            score += 5;
+        if (call.stateUpdatedAfter)
+            score += 3;
+        if (call.target?.includes("ERC777"))
+            score += 4;
+        let level = "LOW ATTENTION";
+        if (score >= 7)
+            level = "HIGH ATTENTION";
+        else if (score >= 4)
+            level = "MEDIUM ATTENTION";
+        return {
+            function: call.function,
+            target: call.target,
+            score,
+            level
+        };
+    });
+}

package/dist/rules/rules.schema.json

@@ -0,0 +1,30 @@
+{
+    "access_control": {
+        "risk": "Privilege concentration",
+        "questions": [
+            "What happens if this role is compromised?",
+            "Can privileged roles modify core logic or funds?"
+        ]
+    },
+    "external_calls": {
+        "risk": "Reentrancy and execution hijack",
+        "questions": [
+            "Is state updated before external calls?",
+            "Can a malicious token reenter?"
+        ]
+    },
+    "state": {
+        "risk": "Invariant violations",
+        "questions": [
+            "What must always remain true?",
+            "Are invariants broken during flash loans?"
+        ]
+    },
+    "upgradeability": {
+        "risk": "Logic replacement",
+        "questions": [
+            "Who authorizes upgrades?",
+            "Can upgrades happen mid-operation?"
+        ]
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "audit-notes-cli",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "bin": {
+    "audit-notes": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "openai": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "smart-contract",
+    "security",
+    "audit",
+    "slither",
+    "web3"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}