Setup

Quickstart

Run your first smart contract analysis in under five minutes.

Step 1 — Install OpenAudit AI

Clone the repository and build locally. This is the recommended setup while the npm package is pending release.

setup

# Local dev setup — recommended until npm release

$git clone https://github.com/NeuroForgeLabs/openaudit-ai.git

$cd openaudit-ai && npm install && npm run build && npm link

Note: Once the npm package is published, you can install with npm install -g openaudit-ai instead.

Step 2 — Analyze a contracts directory

Point the analyzer at any directory containing .sol files. OpenAudit AI will recursively scan all Solidity files it finds.

output

$openaudit-ai analyze ./contracts

OpenAudit AI v0.1.0

Scanning 12 Solidity files...

CRITICAL [reentrancy-guard] Token.sol:147:12

↳ External call before state update

HIGH [unchecked-return] Vault.sol:83:5

↳ Return value of external call not checked

MEDIUM [tx-origin-auth] Auth.sol:29:9

↳ Use of tx.origin for authorization

3 findings · 1 critical · 1 high · 1 medium

Each finding shows the rule ID, severity level, file location, and a short description. Severity levels are: CRITICAL, HIGH, MEDIUM, LOW, and INFO.

Step 3 — Export JSON output

Use the --json flag to get machine-readable output. This is ideal for CI/CD integration or custom tooling.

output

$openaudit-ai analyze ./contracts --json > findings.json

Wrote 3 findings to findings.json

The exported JSON looks like this:

findings.jsonjson

{
  "meta": {
    "version": "0.1.0",
    "scannedAt": "2024-11-15T14:23:01Z",
    "files": 12,
    "findings": 3
  },
  "findings": [
    {
      "ruleId": "reentrancy-guard",
      "severity": "CRITICAL",
      "file": "contracts/Token.sol",
      "line": 147,
      "column": 12,
      "message": "External call precedes state update",
      "suggestion": "Move state updates before external calls or use a reentrancy guard.",
      "explanation": null
    }
  ]
}

Step 4 — Enable AI explanations (optional)

The AI explanation layer is completely optional. It translates structured findings into developer-readable plain language. The AI does not make security decisions — it only explains what the rule engine found.

optional

# Requires OPENAI_API_KEY env variable

$OPENAI_API_KEY=sk-... openaudit-ai explain ./contracts

reentrancy-guard @ Token.sol:147

Explanation: The withdraw() function makes an external call to

msg.sender before updating the user's balance. This allows a

malicious contract to re-enter withdraw() before balance is zero.

Fix: Update balances[msg.sender] = 0 before the .call().

Tip: AI explanations require an OpenAI-compatible API key set via the OPENAI_API_KEY environment variable or a config file.

Step 5 — List available rules

See all rules in the engine, including their IDs, descriptions, and severity levels.

rules

$openaudit-ai rules list

ID SEVERITY DESCRIPTION

reentrancy-guard CRITICAL External call before state update

unchecked-return HIGH Unchecked external call return value

tx-origin-auth MEDIUM tx.origin used for authorization

integer-overflow HIGH Unchecked arithmetic (pre-0.8.x)

selfdestruct-usage HIGH Use of selfdestruct

Next steps

Read the CLI Reference for all available commands and flags.
Learn about the Output Format for CI/CD integration.
Explore the CI/CD Usage guide for GitHub Actions setup.

Installation

CLI Reference