Reference

Output Format

OpenAudit AI emits structured JSON output designed for both human reading and machine processing. Every field is consistent and versioned.

Full JSON example

Pass --json to any analyze or explain command to get the full structured output:

findings.jsonjson

{
  "meta": {
    "version": "0.1.0",
    "scannedAt": "2024-11-15T14:23:01.442Z",
    "directory": "./contracts",
    "filesScanned": 12,
    "totalFindings": 3
  },
  "findings": [
    {
      "ruleId": "reentrancy-guard",
      "severity": "CRITICAL",
      "file": "contracts/Token.sol",
      "line": 147,
      "column": 12,
      "message": "External call precedes state update",
      "snippet": "  (bool success, ) = msg.sender.call{value: amount}(\"\");",
      "suggestion": "Move all state updates before external calls, or use a reentrancy guard modifier.",
      "explanation": null,
      "docs": "https://github.com/NeuroForgeLabs/openaudit-ai/docs/rules/reentrancy-guard"
    },
    {
      "ruleId": "unchecked-return",
      "severity": "HIGH",
      "file": "contracts/Vault.sol",
      "line": 83,
      "column": 5,
      "message": "Return value of external call not checked",
      "snippet": "  token.transfer(recipient, amount);",
      "suggestion": "Check the return value or use SafeERC20 from OpenZeppelin.",
      "explanation": null,
      "docs": "https://github.com/NeuroForgeLabs/openaudit-ai/docs/rules/unchecked-return"
    },
    {
      "ruleId": "tx-origin-auth",
      "severity": "MEDIUM",
      "file": "contracts/Auth.sol",
      "line": 29,
      "column": 9,
      "message": "tx.origin used for authorization",
      "snippet": "  require(tx.origin == owner, \"Not owner\");",
      "suggestion": "Use msg.sender instead of tx.origin for authorization checks.",
      "explanation": null,
      "docs": "https://github.com/NeuroForgeLabs/openaudit-ai/docs/rules/tx-origin-auth"
    }
  ]
}

Field reference

Meta object

Field	Type	Description
version	string	OpenAudit AI version that produced this output
scannedAt	ISO 8601 string	Timestamp of the scan
directory	string	The path that was analyzed
filesScanned	number	Total number of .sol files analyzed
totalFindings	number	Total number of findings across all files

Finding object

Field	Type	Description
ruleId	string	Unique identifier for the rule that fired
severity	enum	CRITICAL \| HIGH \| MEDIUM \| LOW \| INFO
file	string	Relative path to the Solidity file
line	number	Line number of the finding (1-indexed)
column	number	Column number of the finding (1-indexed)
message	string	Short, rule-level description of the issue
snippet	string	The relevant line of source code
suggestion	string	Rule-provided remediation guidance
explanation	string \| null	AI-generated explanation (null if not requested)
docs	string	URL to the rule documentation page

Output with AI explanations

When using openaudit-ai explain, the explanation field is populated with AI-generated context. All other fields remain identical.

finding with explanationjson

{
  "ruleId": "reentrancy-guard",
  "severity": "CRITICAL",
  "file": "contracts/Token.sol",
  "line": 147,
  "column": 12,
  "message": "External call precedes state update",
  "snippet": "  (bool success, ) = msg.sender.call{value: amount}(\"\");",
  "suggestion": "Move all state updates before external calls.",
  "explanation": "The withdraw() function sends ETH to msg.sender before zeroing the user's balance. A malicious contract can implement a fallback function that re-calls withdraw() before the balance is updated, draining the contract. This is a classic reentrancy attack. Fix by updating balances[msg.sender] = 0 before the external .call(), or adding a ReentrancyGuard modifier.",
  "docs": "https://github.com/NeuroForgeLabs/openaudit-ai/docs/rules/reentrancy-guard"
}

Important: The explanation field is generated by a language model and is informational only. Security decisions are always based on the deterministic ruleId, severity, and message fields.

Severity levels

Level	Meaning
CRITICAL	Exploitable vulnerability with direct fund loss potential
HIGH	Serious issue that should be fixed before deployment
MEDIUM	Issue that can cause problems under specific conditions
LOW	Minor issue or best-practice deviation
INFO	Informational note, no immediate action required

CLI Reference

Philosophy