solaudit 0.1.2 → 0.2.0

package/README.md

@@ -1,16 +1,30 @@
 # SolAudit
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![npm version](https://img.shields.io/badge/npm-v0.1.0-blue.svg)](https://www.npmjs.com/package/solaudit)
+[![npm version](https://img.shields.io/badge/npm-v0.2.0-blue.svg)](https://www.npmjs.com/package/solaudit)
 [![build](https://img.shields.io/badge/build-passing-brightgreen.svg)](./.github/workflows/ci.yml)
 
-**A zero-dependency, static-analysis CLI that scans Anchor/Solana Rust programs for the vulnerability patterns behind the most common on-chain exploits.**
+**A zero-dependency static-analysis engine that scans Anchor/Solana Rust programs for the vulnerability patterns behind the most common on-chain exploits — available as a CLI and as a free web app.**
 
-SolAudit reads your `.rs` source files, applies a set of pattern-matching security rules (missing signer checks, arbitrary CPIs, unchecked deserialization, integer overflow, and more), and gives you an actionable report in seconds — with no external dependencies, no RPC calls, and no build step required to run it.
+SolAudit reads `.rs` source files, applies a set of pattern-matching security rules (missing signer checks, arbitrary CPIs, unchecked deserialization, integer overflow, and more), and gives you an actionable report in seconds — no RPC calls, no wallet, no build step required to run it.
+
+- **CLI** — `npx solaudit ./program`, for local development and CI.
+- **Web app** — [solaudit-web.vercel.app](https://solaudit-web.vercel.app/) — paste a public GitHub repo URL or upload a single `.rs` file, no install required.
 
 ---
 
-## Install
+## Repository layout
+
+This is a Bun workspaces monorepo. The CLI and the web app share one scanning engine, so there is a single source of truth for every rule — no drift between the two.
+
+```
+packages/core/    Shared engine: rules, scanner, output formatters (published nowhere; workspace-only)
+cli/              npm package "solaudit" — the command-line tool
+web/              Next.js app deployed to Vercel — the web version
+examples/         Intentionally vulnerable sample Anchor program, used by both the CLI and web tests
+```
+
+## CLI
 
 ```bash
 # Run instantly with npx (no install)
@@ -19,15 +33,8 @@ npx solaudit ./program
 # Or install globally with Bun
 bun add -g solaudit
 solaudit ./program
-
-# Or clone and run from source
-git clone https://github.com/blueeyez425-art/solaudit.git
-cd solaudit
-bun run solaudit ./examples
 ```
 
-## Usage
-
 ```bash
 solaudit [path] [options]
 ```
@@ -46,8 +53,8 @@ $ solaudit ./examples
 ```
 
 ```
-SolAudit v0.1.0 — static analysis for Anchor/Solana programs
-Scanned 1 file(s) at 2026-08-22T18:32:37.205Z
+SolAudit v0.2.0 — static analysis for Anchor/Solana programs
+Scanned 1 file(s) at 2026-08-27T06:00:00.000Z
 ──────────────────────────────────────────────────────────────────────
 
 CRITICAL (2)
@@ -57,26 +64,6 @@ CRITICAL (2)
     └─ Verify the authority/owner account is a Signer or explicitly
        check `.is_signer` before transferring or minting tokens.
 
-HIGH (3)
-   HIGH      SOL-003 Arbitrary CPI (Cross-Program Invocation)
-    examples/vulnerable.rs:68
-    │ invoke(&ix, &[ctx.accounts.target_program.to_account_info()])?;
-    └─ Validate the target program ID against a known constant or type
-       the account as `Program<'info, T>` before invoking it.
-
-  HIGH      SOL-004 Missing Bump Seed Canonicalization
-    examples/vulnerable.rs:76
-    │ let signer_pda = Pubkey::create_program_address(seeds, ctx.program_id)
-    └─ Use `Pubkey::find_program_address` to derive the canonical bump
-       instead of calling `create_program_address` directly.
-
-MEDIUM (3)
-  MEDIUM    SOL-005 Integer Overflow Risk
-    examples/vulnerable.rs:27
-    │ vault.total_staked = vault.total_staked - amount;
-    └─ Replace raw arithmetic with `.checked_sub()` / `.checked_add()`
-       or `saturating_*` equivalents.
-
 ──────────────────────────────────────────────────────────────────────
 Summary
   CRITICAL 2   HIGH 3   MEDIUM 3   LOW 6   INFO 0
@@ -85,6 +72,24 @@ Summary
 
 Exit code is `1` when any `CRITICAL` or `HIGH` finding is present — making SolAudit a natural CI gate.
 
+## Web app
+
+**Live at [solaudit-web.vercel.app](https://solaudit-web.vercel.app/)** — no CLI, no local Anchor toolchain, no wallet required:
+
+1. Paste a public GitHub repo URL **or** upload a single `.rs` file.
+2. The server fetches `.rs` files via GitHub's API (no `git clone`) and scans them with the exact same engine as the CLI.
+3. Get a report grouped by severity, right in the browser.
+
+Optional: set `GITHUB_TOKEN` (see `web/.env.example`) to raise the GitHub API rate limit from 60 to 5,000 requests/hour. No special token scopes are needed for public repos.
+
+### Running the web app locally
+
+```bash
+bun install          # from the repo root — links the workspace packages
+cd web
+bun run dev
+```
+
 ## Rules
 
 | ID | Severity | Name | What it catches |
@@ -97,79 +102,82 @@ Exit code is `1` when any `CRITICAL` or `HIGH` finding is present — making Sol
 | `SOL-006` | HIGH | Type Cosplay / Missing Discriminator Check | Manual `try_from_slice` deserialization with no discriminator validation or `Account<'info, T>` wrapper |
 | `SOL-007` | MEDIUM | Insecure Account Initialization | `#[account(init, ...)]` constraints missing `payer` and/or `space` |
 | `SOL-008` | LOW | Missing Owner Check | Raw `AccountInfo` fields used without a nearby `.owner` comparison |
+| `SOL-009` | HIGH | Insecure Manual Account Closure | An account's lamports manually drained to zero without discriminator zeroing or owner reassignment (unlike Anchor's `close = destination`), enabling closed-account revival |
+| `SOL-011` | MEDIUM | Missing Rent-Exemption Check | A partial lamport withdrawal with no nearby `Rent::get()?.minimum_balance(...)` check, risking runtime garbage-collection of the account |
 
-Each rule is implemented as real regex/line-scanning logic in [`src/rules/index.ts`](./src/rules/index.ts) — see that file (and its accompanying [tests](./src/rules/index.test.ts)) for the exact matching heuristics and false-positive guards.
+Each rule is implemented as real regex/line-scanning logic in [`packages/core/src/rules/index.ts`](./packages/core/src/rules/index.ts) — see that file (and its accompanying [tests](./packages/core/src/rules/index.test.ts)) for the exact matching heuristics and false-positive guards.
 
-## Output formats
+## Accuracy
 
-SolAudit supports three output modes, so it fits into a terminal, a script, or a CI pipeline:
+On the committed labeled suite in [`benchmark/`](./benchmark), the deterministic engine scores **93.8% precision, 100% recall, 96.8% F1** on rule-covered categories.
 
-- **Human** (default) — colorized terminal report grouped by severity, for local development.
-- **JSON** (`--json`) — the full `ScanResult` object (`scannedFiles`, `findings[]`, `summary`), for piping into other tooling.
-- **SARIF** (`--sarif`) — [SARIF 2.1.0](https://sarifweb.azurewebsites.net/) output compatible with GitHub Code Scanning, so findings show up as annotations directly on your pull requests.
+One known gap remains: **duplicate mutable accounts**. A regex “distinctness” heuristic produced false positives on common legitimate patterns (for example a deposit instruction’s user/vault token accounts of the same type), so that rule was not shipped. These numbers describe this suite, not general security effectiveness.
 
-```bash
-solaudit ./programs --sarif > results.sarif
-```
+## Output formats (CLI)
+
+- **Human** (default) — colorized terminal report grouped by severity.
+- **JSON** (`--json`) — the full `ScanResult` object (`scannedFiles`, `findings[]`, `summary`).
+- **SARIF** (`--sarif`) — [SARIF 2.1.0](https://sarifweb.azurewebsites.net/) output compatible with GitHub Code Scanning.
 
 ## GitHub Actions
 
-Add SolAudit to your CI so every push and PR is scanned automatically:
+SolAudit ships as a ready-to-use [GitHub Action](./action.yml). Drop this into `.github/workflows/solaudit.yml` in your own repo and every push/PR gets scanned automatically, with results uploaded straight to your repo's Security tab:
 
 ```yaml
 name: SolAudit
 
 on: [push, pull_request]
 
+permissions:
+  contents: read
+  security-events: write   # required to upload SARIF results
+
 jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-      - run: bun install
-      - run: bun src/cli.ts ./programs --sarif > results.sarif
-      - uses: github/codeql-action/upload-sarif@v3
+      - uses: blueeyez425-art/solaudit@main
         with:
-          sarif_file: results.sarif
+          path: ./programs        # file or directory to scan (default: .)
+          min-severity: INFO      # lowest severity to report (default: INFO)
+          fail-on-findings: true  # fail the build on any CRITICAL/HIGH finding (default: true)
+          upload-sarif: true      # upload results to code scanning (default: true)
 ```
 
-This repository's own [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) runs SolAudit against [`examples/vulnerable.rs`](./examples/vulnerable.rs) on every push.
+No `security-events: write` permission in your workflow? Set `upload-sarif: false` and the action will still run the scan and fail the build on CRITICAL/HIGH findings — it just won't publish to the Security tab.
 
-## Project layout
+Prefer to wire it up manually instead of using the packaged action:
 
+```yaml
+- uses: actions/checkout@v4
+- run: npx solaudit ./programs --sarif > results.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
 ```
-src/
-  types.ts             # Finding, Rule, ScanResult types
-  rules/index.ts        # The 8 vulnerability rules (pattern-matching logic)
-  scanner.ts            # File/directory walking + aggregation
-  output/report.ts       # Colored terminal report
-  output/sarif.ts        # SARIF 2.1.0 conversion
-  cli.ts                # Argument parsing + entrypoint
-examples/vulnerable.rs   # Intentionally vulnerable sample Anchor program
-```
+
+This repository's own [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) runs the full test suite, builds the CLI and web app, and uses this repo's own action against `examples/` on every push.
 
 ## Development
 
 ```bash
-bun install
-bun test              # run the unit test suite
-bun run start ./examples   # run the CLI against the bundled example
-bun run build         # bundle src/cli.ts -> dist/cli.js
+bun install                    # installs and links all workspaces
+cd packages/core && bun test   # run the engine's unit test suite
+cd cli && bun run build        # bundle cli/src/cli.ts -> cli/dist/cli.js
+cd web && bun run build        # production-build the web app
 ```
 
 ## Contributing
 
-Contributions are very welcome — new rules, false-positive fixes, additional output formats, or better heuristics are all in scope.
+Contributions are very welcome — new rules, false-positive fixes, additional output formats, or web UI improvements are all in scope.
 
 1. Fork the repo and create a branch from `main`.
-2. Add or update a rule in `src/rules/index.ts` (each rule is a self-contained `Rule` object).
-3. Add unit tests covering both a triggering and a non-triggering case (`src/rules/index.test.ts`).
-4. Run `bun test` and `bun run build` before opening a PR.
+2. Add or update a rule in `packages/core/src/rules/index.ts` (each rule is a self-contained `Rule` object).
+3. Add unit tests covering both a triggering and a non-triggering case (`packages/core/src/rules/index.test.ts`).
+4. Run `bun test` (from `packages/core`) before opening a PR.
 
-Please open an issue first for larger changes (e.g. new output formats or a plugin system) so we can discuss the approach.
+Please open an issue first for larger changes so we can discuss the approach.
 
 ## License
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// src/rules/index.ts
+// ../packages/core/src/rules/index.ts
 function makeFinding(rule, filePath, line, snippet, description) {
   return {
     ruleId: rule.id,
@@ -15,6 +15,10 @@ function makeFinding(rule, filePath, line, snippet, description) {
 function splitLines(fileContent) {
   return fileContent.split(/\r\n|\r|\n/);
 }
+function stripLineComments(text) {
+  return text.split(/\r\n|\r|\n/).map((line) => line.replace(/\/\/.*$/, "")).join(`
+`);
+}
 var missingSignerCheck = {
   id: "SOL-001",
   name: "Missing Signer Check",
@@ -215,6 +219,56 @@ var missingOwnerCheck = {
     return findings;
   }
 };
+var insecureAccountClosure = {
+  id: "SOL-009",
+  name: "Insecure Manual Account Closure",
+  severity: "HIGH",
+  description: "An account's lamports were manually drained to zero without zeroing its data/discriminator or reassigning ownership to the System Program, unlike Anchor's `close = destination` constraint (which does both automatically). A 'closed' account that still carries its original discriminator and data can be revived/reused within the same or a later transaction before garbage collection, letting an attacker re-claim already-withdrawn funds or reopen closed state. Use `#[account(mut, close = destination)]` instead of manual lamport-draining, or manually zero the account's discriminator/data and reassign owner to the System Program.",
+  check(fileContent, filePath) {
+    const findings = [];
+    const lines = splitLines(fileContent);
+    const zeroLamportsPattern = /\.lamports\.borrow_mut\(\)\s*=\s*0\s*;/;
+    lines.forEach((line, idx) => {
+      if (!zeroLamportsPattern.test(line))
+        return;
+      const windowStart = Math.max(0, idx - 15);
+      const windowEnd = Math.min(lines.length, idx + 15);
+      const window = stripLineComments(lines.slice(windowStart, windowEnd).join(`
+`));
+      const hasSafeClosure = /close\s*=/.test(window) || /discriminator/i.test(window) || /CLOSED_ACCOUNT_DISCRIMINATOR/.test(window) || /\.data\.borrow_mut\(\)/.test(window);
+      if (!hasSafeClosure) {
+        findings.push(makeFinding(insecureAccountClosure, filePath, idx + 1, line, "Use Anchor's `#[account(mut, close = destination)]` constraint, or manually zero the account's 8-byte discriminator and reassign its owner to the System Program, before treating this account as closed."));
+      }
+    });
+    return findings;
+  }
+};
+var missingRentExemptCheck = {
+  id: "SOL-011",
+  name: "Missing Rent-Exemption Check on Partial Withdrawal",
+  severity: "MEDIUM",
+  description: "Lamports are subtracted from an account's balance (a partial withdrawal) with no nearby check against `Rent::get()?.minimum_balance(...)`. If the withdrawal can drop the account below the rent-exempt threshold, the runtime may purge the account on the next epoch boundary, destroying any remaining state and potentially enabling accounting-drift or re-initialization bugs. Compare the post-withdrawal balance against the account's rent-exempt minimum before allowing a partial (non-zeroing) withdrawal.",
+  check(fileContent, filePath) {
+    const findings = [];
+    const lines = splitLines(fileContent);
+    const partialWithdrawPattern = /\.lamports\.borrow_mut\(\)\s*=\s*[\w.]+\.lamports\(\)\.checked_sub\(/;
+    lines.forEach((line, idx) => {
+      if (!partialWithdrawPattern.test(line))
+        return;
+      if (/=\s*0\s*;/.test(line))
+        return;
+      const windowStart = Math.max(0, idx - 15);
+      const windowEnd = Math.min(lines.length, idx + 15);
+      const window = stripLineComments(lines.slice(windowStart, windowEnd).join(`
+`));
+      const hasRentCheck = /Rent::get\(\)|minimum_balance/.test(window);
+      if (!hasRentCheck) {
+        findings.push(makeFinding(missingRentExemptCheck, filePath, idx + 1, line, "Check the resulting balance against `Rent::get()?.minimum_balance(account.data_len())` before allowing a partial lamport withdrawal, or require the withdrawal to fully close the account via `close = destination`."));
+      }
+    });
+    return findings;
+  }
+};
 var rules = [
   missingSignerCheck,
   uncheckedDeserialization,
@@ -223,16 +277,16 @@ var rules = [
   integerOverflowRisk,
   typeCosplay,
   insecureInit,
-  missingOwnerCheck
+  missingOwnerCheck,
+  insecureAccountClosure,
+  missingRentExemptCheck
 ];
-
-// src/scanner.ts
+// ../packages/core/src/scanner.ts
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-function scanFile(filePath, rules2) {
-  const content = readFileSync(filePath, "utf8");
+function scanContent(content, filePath, rules) {
   const findings = [];
-  for (const rule of rules2) {
+  for (const rule of rules) {
     try {
       const ruleFindings = rule.check(content, filePath);
       findings.push(...ruleFindings);
@@ -242,6 +296,10 @@ function scanFile(filePath, rules2) {
   }
   return findings.sort((a, b) => a.line - b.line);
 }
+function scanFile(filePath, rules) {
+  const content = readFileSync(filePath, "utf8");
+  return scanContent(content, filePath, rules);
+}
 function walk(dirPath, files = []) {
   const entries = readdirSync(dirPath);
   for (const entry of entries) {
@@ -283,13 +341,7 @@ function tallySummary(findings) {
   }
   return summary;
 }
-async function scanDirectory(targetPath, rules2) {
-  const stat = statSync(targetPath);
-  const rsFiles = stat.isDirectory() ? walk(targetPath) : targetPath.endsWith(".rs") ? [targetPath] : [];
-  const allFindings = [];
-  for (const file of rsFiles) {
-    allFindings.push(...scanFile(file, rules2));
-  }
+function sortAndSummarize(rsFileCount, allFindings) {
   const severityOrder = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3, INFO: 4 };
   allFindings.sort((a, b) => {
     const sev = severityOrder[a.severity] - severityOrder[b.severity];
@@ -300,13 +352,21 @@ async function scanDirectory(targetPath, rules2) {
     return a.line - b.line;
   });
   return {
-    scannedFiles: rsFiles.length,
+    scannedFiles: rsFileCount,
     findings: allFindings,
     summary: tallySummary(allFindings)
   };
 }
-
-// src/output/report.ts
+async function scanDirectory(targetPath, rules) {
+  const stat = statSync(targetPath);
+  const rsFiles = stat.isDirectory() ? walk(targetPath) : targetPath.endsWith(".rs") ? [targetPath] : [];
+  const allFindings = [];
+  for (const file of rsFiles) {
+    allFindings.push(...scanFile(file, rules));
+  }
+  return sortAndSummarize(rsFiles.length, allFindings);
+}
+// ../packages/core/src/output/report.ts
 var RESET = "\x1B[0m";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
@@ -338,7 +398,7 @@ function badge(severity) {
 var SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"];
 function printReport(result) {
   const timestamp = new Date().toISOString();
-  console.log(`${BOLD}${CYAN}SolAudit${RESET} ${DIM}v0.1.0 — static analysis for Anchor/Solana programs${RESET}`);
+  console.log(`${BOLD}${CYAN}SolAudit${RESET} ${DIM}v0.2.0 — static analysis for Anchor/Solana programs${RESET}`);
   console.log(`${DIM}Scanned ${result.scannedFiles} file(s) at ${timestamp}${RESET}`);
   console.log(`${GRAY}${"─".repeat(70)}${RESET}`);
   if (result.findings.length === 0) {
@@ -371,10 +431,9 @@ function printReport(result) {
   console.log(`  ${DIM}Total findings: ${result.findings.length} across ${result.scannedFiles} file(s)${RESET}`);
   console.log("");
 }
-
-// src/output/sarif.ts
+// ../packages/core/src/output/sarif.ts
 var SARIF_VERSION = "2.1.0";
-var TOOL_VERSION = "0.1.0";
+var TOOL_VERSION = "0.2.0";
 function severityToSarifLevel(severity) {
   switch (severity) {
     case "CRITICAL":
@@ -429,7 +488,6 @@ function toSarif(result) {
     ]
   };
 }
-
 // src/cli.ts
 var SEVERITY_RANK = {
   CRITICAL: 0,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "solaudit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Open-source static analysis CLI for Anchor/Solana programs",
   "type": "module",
   "bin": {
     "solaudit": "dist/cli.js"
   },
-  "main": "./dist/index.js",
+  "main": "./dist/cli.js",
   "files": [
     "dist",
     "examples",
@@ -18,9 +18,8 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts --outdir dist --target node --sourcemap=none",
-    "prepublishOnly": "npm run build",
-    "start": "bun src/cli.ts",
-    "test": "bun test"
+    "prepublishOnly": "bun run build && cp -r ../examples . && cp ../README.md ../LICENSE .",
+    "start": "bun src/cli.ts"
   },
   "keywords": [
     "solana",
@@ -35,7 +34,9 @@
     "type": "git",
     "url": "git+https://github.com/blueeyez425-art/solaudit.git"
   },
+  "dependencies": {},
   "devDependencies": {
+    "@solaudit/core": "workspace:*",
     "bun-types": "latest"
   }
 }