hex-audit 0.4.0

package/dist/skills/validate-issue.md

@@ -0,0 +1,149 @@
+---
+description: "Validate any potential issue on the board (manual / auditagent / conformance / github) and promote it to Verified or Invalid"
+---
+
+# Skill: Validate Issue
+
+**Recommended model:** Opus
+
+## What this skill does
+
+Takes a single potential issue from the dashboard's Issues board and runs an independent validation pass on it. Source-agnostic — the issue can come from any of:
+
+- **Manual** (`/write-finding`) — `source: "manual"`, `status: "pending_validation"`.
+- **Auditagent** (`/ingest-aa-report`) — `source: "auditagent"`, `status: "unverified"`.
+- **Conformance** (materialized by `/init-audit`) — `source: "conformance"`, `status: "pending_validation"`.
+- **GitHub** (teammate findings via `/sync-issues`) — `source: "github"`, `status: "pending_validation"`.
+
+The skill writes a validation memo (always), optionally generates a PoC, and updates the tracking entry to `verified` or `rejected`. Card moves on the board.
+
+## Invocation
+
+The auditor invokes by id or by free-text reference:
+
+```
+/validate-issue F003
+/validate-issue SC-007
+/validate-issue AA-N002
+/validate-issue for the rounding issue in Vault.sol
+```
+
+Resolve to a single tracking entry by:
+1. Exact id match in `<output_dir>/tracking.json`, or
+2. Title / description substring match (if multiple, ask the auditor to disambiguate).
+
+## Context Assembly
+
+Once the issue is resolved, read:
+
+- `<output_dir>/tracking.json` — the entry being validated.
+- Source-specific raw data:
+  - `manual` → `<output_dir>/findings.json` (the full finding record).
+  - `auditagent` → `<output_dir>/ai-results/auditagent/findings.json` (the matching `findings[*]` entry).
+  - `conformance` → `<output_dir>/spec-conformance.json` (the matching `items[*]` entry).
+  - `github` → `<output_dir>/external/github/findings.json` (the matching entry).
+- `<output_dir>/state-vars.json`, `<output_dir>/access-control.json`, `<output_dir>/external-calls.json` for cross-referenced facts.
+- The affected contract source via `npx hex context --target <affected_contract>`.
+
+## Validation pass
+
+### 1. Understand the claim
+
+Extract from the source-specific record:
+- The vulnerability being claimed (one sentence).
+- The affected contract/function.
+- The claimed attack path or spec violation.
+- The claimed impact.
+
+For conformance items, the "claim" is `spec_text` + the finding paragraph — i.e., "the spec says X, the code does Y".
+
+### 2. Trace it in the code
+
+- Follow the claimed path step by step in the actual code.
+- Check each precondition.
+- Verify the state changes actually occur.
+- Check existing protections (modifiers, reentrancy guards, input validation, economic constraints).
+- For conformance items: re-read the cited spec section, compare to the implementation.
+
+### 3. Verdict
+
+**Valid:**
+
+1. Use **AskUserQuestion** to ask:
+   > The issue appears **VALID**. How would you like to proceed?
+   >
+   > 1. Generate a full PoC test, then promote to Verified.
+   > 2. Accept with rational verification only — validation memo, no PoC.
+   >
+   > Reply **1** or **2**.
+
+2. **If PoC chosen:** invoke the `generate-poc` skill flow (read the project test setup, write the PoC, run and iterate until it passes). Set `poc.status = "passing"`, `poc.file = "test/hex-pocs/<id>_<name>.t.sol"`.
+
+3. **If memo-only chosen:** leave `poc.status = "not_started"`, `poc.file = null`.
+
+4. If the issue source is **conformance**, **auditagent**, or **github** (no manual finding record yet), invoke the `write-finding` skill flow to materialize a structured finding into `<output_dir>/findings.json` — reusing the existing tracking id. If `source = "manual"`, the finding already exists; update its `poc` block in place.
+
+5. Update the tracking entry: `status = "verified"`, `poc_status` per choice above, `poc_file` per choice above.
+
+6. For source files in `root_cause.locations[]`, replace any `// @audit-issue F<NNN>` annotation with `// @audit-issue-verified F<NNN> <short title>` (matching indentation).
+
+7. Use **AskUserQuestion** to ask:
+   > Issue verified as **\<id\>** with severity **\<current severity\>**.
+   >
+   > Would you like to change the severity? Reply with the new severity (Critical / High / Medium / Low / Info), or **no** to keep it.
+
+8. If the user provides a new severity, update both `findings.json` and `tracking.json`.
+
+**Invalid:**
+
+1. Explain why:
+   - Is the attack path blocked? By what specifically (modifier, require, state check)?
+   - Are the preconditions impossible? Why?
+   - Is the impact assessment wrong? What actually happens?
+2. Update tracking: `status = "rejected"`.
+3. Do NOT write a finding to `findings.json`. The memo alone records the reasoning.
+
+**Uncertain:**
+
+1. List specific questions that need manual investigation.
+2. State what would confirm or deny the issue.
+3. Leave tracking `status` as-is. Append findings to the `notes` field describing the open questions.
+
+## Output: validation memo
+
+Write `<output_dir>/validations/<id>_memo.md` (always — for valid, invalid, and uncertain verdicts):
+
+```markdown
+# Issue Validation: <ID> — <Title>
+
+**Source:** <manual | auditagent | conformance | github>
+**Original record:** <pointer to the specific record being validated — e.g., findings.json#F003, ai-results/auditagent/findings.json#AA-014>
+**Verdict:** Valid / Invalid / Uncertain
+**Date:** <YYYY-MM-DD>
+
+## Claim being validated
+[One- to two-sentence summary of the issue under review]
+
+## Analysis
+[Step-by-step trace through the code, or spec-vs-code comparison for conformance items]
+
+## Protections evaluated
+[Access control, reentrancy guards, input validation, economic constraints, etc.]
+
+## Verdict reasoning
+[Why valid / invalid / uncertain]
+
+## Action taken
+[If valid + PoC: PoC at <path>, test passing, finding F<NNN> updated/created]
+[If valid + memo-only: finding F<NNN> updated/created, no PoC]
+[If invalid: tracking entry rejected, no finding written]
+[If uncertain: open questions listed; tracking status unchanged]
+```
+
+## After validation
+
+The board reflects the new state automatically (the dashboard watches `tracking.json` and `findings.json`). The auditor can:
+
+- Move on to the next Potential card.
+- Run `/sync-issues` to push the newly Verified finding to GitHub if `settings.github.repo` is configured.
+- Run `/generate-overleaf` once all verifications are done, to produce the LaTeX report sections.

package/dist/skills/write-finding.md

@@ -0,0 +1,142 @@
+---
+description: "Write a manual issue as a Potential card on the board (pending validation)"
+---
+
+# Skill: Write Finding
+
+**Recommended model:** Sonnet
+
+This skill records a manual issue that the auditor has spotted during review. The issue lands on the dashboard's Issues board as a **Potential** card with `status: "pending_validation"` and `source: "manual"`. The auditor promotes it to Verified later (via drag-drop on the board, or by running `/validate-issue <id>` which produces a validation memo and optional PoC).
+
+## Context Assembly
+
+Read:
+- The issue description provided by the auditor.
+- The relevant source code.
+- `<output_dir>/findings.json` and `<output_dir>/tracking.json` — to determine the next finding ID. Use the highest existing `F<NNN>` ID across both files and increment by 1. Rejected and invalid findings keep their IDs reserved.
+
+## Step 0: Duplicate gate
+
+Scan `findings.json` and `tracking.json` for any existing entry that covers the same vulnerability (same affected contract/function, same or overlapping root cause). If a match is found, warn the auditor:
+
+> "This appears to duplicate `F<NNN>`: \<title\>. Proceed anyway?"
+
+Only continue if confirmed.
+
+## Severity Guide
+
+Assess severity directly based on impact and exploitability:
+
+- **Critical** — Direct fund loss or permanent protocol-breaking impact that anyone can trigger with no special conditions.
+- **High** — Significant fund loss, privilege escalation, or severe DoS that requires specific but realistic conditions.
+- **Medium** — Temporary DoS, griefing with economic cost, or incorrect accounting that compounds over time.
+- **Low** — Minor issues with limited economic impact, requires unlikely conditions to exploit.
+- **Info** — Gas inefficiency, cosmetic issues, best-practice deviations with no direct security impact.
+
+### Likelihood × Impact Matrix
+
+Cross-reference both before assigning a severity.
+
+| | Low Impact | Medium Impact | High Impact |
+|---|---|---|---|
+| **High Likelihood** | Medium | High | Critical |
+| **Medium Likelihood** | Low | Medium | High |
+| **Low Likelihood** | Info | Low | Medium |
+
+**Impact:** High = direct fund loss / permanent state corruption / full bypass of critical access control. Medium = temporary DoS, griefing with cost, incorrect accounting that compounds, or partial access bypass. Low = minor inefficiency, cosmetic, best-practice deviation.
+
+**Likelihood:** High = anyone can trigger with no preconditions; common conditions; profitable. Medium = specific but realistic conditions; moderate setup/timing; economically viable. Low = unlikely conditions; complex multi-step; unprofitable.
+
+## Template
+
+Write the finding following this structure:
+
+```json
+{
+  "id": "F<NNN>",
+  "title": "<concise, descriptive title>",
+  "severity": "Critical|High|Medium|Low|Info",
+  "category": "<e.g., Math / Rounding, Access Control, Reentrancy, Oracle Manipulation>",
+  "description": "<clear, self-contained description covering what the vulnerability is, why it exists, and what the impact would be if exploited>",
+  "root_cause": {
+    "locations": [
+      { "file": "<path>", "snippet": "<relevant code>" }
+    ]
+  },
+  "poc": {
+    "status": "not_started",
+    "file": null,
+    "validation_memo": null
+  },
+  "recommendation": "<a suggested direction phrased as 'Consider...', not a prescriptive fix>",
+  "references": {
+    "external_links": []
+  },
+  "created_at": "<ISO timestamp>"
+}
+```
+
+### Recommendation tone
+
+Phrase recommendations as suggestions, not commands. The auditor proposes direction; the protocol team owns the implementation:
+
+- Start with `Consider...`, `One option is...`, `The team may want to...`, `It would be worth...`.
+- Avoid `Replace X with Y`, `You must...`, `Always do...`, `Never do...`.
+- Keep under three sentences when possible. Detailed analysis belongs in the description.
+
+**Recommendation must be prose only.** No code snippets in the `recommendation` field. Code belongs in `root_cause.locations[].snippet`.
+
+## Code Block Formatting Rules (STRICT)
+
+When including code snippets in the finding:
+
+### Never modify original code
+Only allowed modifications: `@audit` / `@audit-issue` comments and `// ....` to indicate omitted lines.
+
+### Comment placement
+Add comments on a **separate line above** the affected line. Never inline.
+
+**CORRECT:**
+```solidity
+// ....
+// @audit-issue This calculation is vulnerable to rounding errors.
+uint256 shares = assets.mulDiv(totalSupply, totalAssets, Math.Rounding.Down);
+```
+
+### Comment style
+All inserted audit comments must be full sentences starting with a capital letter and ending with a period.
+
+## Actions
+
+1. **Append the finding** to the `findings` array inside `<output_dir>/findings.json`. File structure is `{ "findings": [...] }` — create with this wrapper if missing.
+2. **Add a tracking entry** to `<output_dir>/tracking.json` with:
+   ```json
+   {
+     "id": "F<NNN>",
+     "title": "<same as finding>",
+     "severity": "<same as finding>",
+     "source": "manual",
+     "status": "pending_validation",
+     "poc_status": "not_started",
+     "poc_file": null,
+     "duplicates": [],
+     "notes": ""
+   }
+   ```
+3. **Annotate source files.** For each entry in `root_cause.locations[]`:
+   - Open the source file at `file`.
+   - Find the first significant line of the `snippet` (skip blank lines and `// ....`).
+   - If an existing `// @audit-issue ...` comment is directly above, replace it with `// @audit-issue F<NNN> <short title>`.
+   - Otherwise insert `// @audit-issue F<NNN> <short title>` directly above, matching indentation.
+
+(The `@audit-issue-verified` annotation comes later, via `/validate-issue` once the issue is promoted to Verified.)
+
+## After writing
+
+The finding now appears on the dashboard's `/issues` board as a Potential card. The auditor can:
+
+- Run `/validate-issue F<NNN>` to write a validation memo and optionally generate a PoC; on success the card moves to Verified.
+- Drag the card directly from Potential → Verified on the board if they're confident no PoC is needed (e.g., trivial Info-level issues).
+- Run `/sync-issues` if `settings.github.repo` is configured, to push verified findings to the team's GitHub repo.
+
+Do NOT run `/validate-issue` or `/sync-issues` automatically — those are auditor-driven decisions.

package/dist/types/index.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { ConfigSchema, StatsSchema, DepsSchema, AccessControlSchema, StateVarsSchema, ExternalCallsSchema, FindingsSchema, TrackingSchema, ComparisonSchema, SpecConformanceSchema, EvidenceSchema, ConfidenceSchema, DerivedFromSchema, PerContractStatsSchema, TestCoverageSchema, GraphNodeSchema, ClusterSchema, AccessFunctionSchema, RoleFunctionRefSchema, RoleSchema, StateVariableSchema, ExternalCallSchema, FindingSchema, TrackingEntrySchema, TrackingSourceSchema, ResolutionSchema, SpecItemSchema } from '../core/schema.js';
+export type Config = z.infer<typeof ConfigSchema>;
+export type Stats = z.infer<typeof StatsSchema>;
+export type Deps = z.infer<typeof DepsSchema>;
+export type AccessControl = z.infer<typeof AccessControlSchema>;
+export type StateVars = z.infer<typeof StateVarsSchema>;
+export type ExternalCalls = z.infer<typeof ExternalCallsSchema>;
+export type Findings = z.infer<typeof FindingsSchema>;
+export type Tracking = z.infer<typeof TrackingSchema>;
+export type Comparison = z.infer<typeof ComparisonSchema>;
+export type SpecConformance = z.infer<typeof SpecConformanceSchema>;
+export type Evidence = z.infer<typeof EvidenceSchema>;
+export type Confidence = z.infer<typeof ConfidenceSchema>;
+export type DerivedFrom = z.infer<typeof DerivedFromSchema>;
+export type PerContractStats = z.infer<typeof PerContractStatsSchema>;
+export type TestCoverage = z.infer<typeof TestCoverageSchema>;
+export type GraphNode = z.infer<typeof GraphNodeSchema>;
+export type Cluster = z.infer<typeof ClusterSchema>;
+export type AccessFunction = z.infer<typeof AccessFunctionSchema>;
+export type RoleFunctionRef = z.infer<typeof RoleFunctionRefSchema>;
+export type Role = z.infer<typeof RoleSchema>;
+export type StateVariable = z.infer<typeof StateVariableSchema>;
+export type ExternalCall = z.infer<typeof ExternalCallSchema>;
+export type Finding = z.infer<typeof FindingSchema>;
+export type TrackingEntry = z.infer<typeof TrackingEntrySchema>;
+export type TrackingSource = z.infer<typeof TrackingSourceSchema>;
+export type Resolution = z.infer<typeof ResolutionSchema>;
+export type SpecItem = z.infer<typeof SpecItemSchema>;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "hex-audit",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "CLI toolkit for Solidity smart contract auditors",
+  "bin": {
+    "hex": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc && npm run copy-skills && npm run build:dashboard",
+    "build:cli": "tsc && npm run copy-skills",
+    "build:dashboard": "next build dashboard",
+    "copy-skills": "node -e \"const fs=require('fs');const p=require('path');fs.cpSync(p.join('src','skills'),p.join('dist','skills'),{recursive:true})\"",
+    "dev:cli": "tsc --watch",
+    "dev:dashboard": "next dev dashboard",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "prettier --check .",
+    "format": "prettier --write ."
+  },
+  "files": [
+    "dist",
+    "dashboard/.next",
+    "dashboard/app",
+    "dashboard/components",
+    "dashboard/lib",
+    "dashboard/public",
+    "dashboard/next.config.mjs",
+    "dashboard/next-env.d.ts",
+    "dashboard/postcss.config.cjs",
+    "dashboard/tailwind.config.ts",
+    "dashboard/tsconfig.json",
+    "README.md",
+    "CLAUDE.md",
+    "DEMO.md"
+  ],
+  "keywords": [
+    "solidity",
+    "audit",
+    "smart-contracts",
+    "security"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.1.0",
+    "@solidity-parser/parser": "^0.18.0",
+    "@tanstack/react-table": "^8.17.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "glob": "^10.3.10",
+    "mermaid": "^11.4.0",
+    "next": "14.2.5",
+    "next-themes": "^0.4.6",
+    "ora": "^8.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^9.0.1",
+    "rehype-highlight": "^7.0.0",
+    "remark-gfm": "^4.0.0",
+    "tiktoken": "^1.0.15",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.13",
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.38",
+    "prettier": "^3.3.3",
+    "tailwindcss": "^3.4.4",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}