solidity-argus 0.3.7 → 0.5.7

package/src/state/projectors.ts

@@ -1,4 +1,6 @@
 import { createHash } from "node:crypto"
+import { isRecord } from "../shared/type-guards"
+import { SEVERITY_RANK } from "../shared/validation-constants"
 import {
   type AuditEvent,
   type CanonicalFinding,
@@ -32,36 +34,39 @@ export class ProjectorError extends Error {
   }
 }
 
-export const SEVERITY_RANK: Record<CanonicalFinding["severity"], number> = {
-  Critical: 0,
-  High: 1,
-  Medium: 2,
-  Low: 3,
-  Informational: 4,
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
 function extractScope(payload: unknown): string[] {
   if (!isRecord(payload) || !Array.isArray(payload.scope)) return []
   return payload.scope.filter((entry): entry is string => typeof entry === "string")
 }
 
+const VALID_PHASES = new Set<string>([
+  "reconnaissance",
+  "scanning",
+  "manual-review",
+  "attack-surface",
+  "research",
+  "testing",
+  "reporting",
+  "complete",
+])
+
+function isAuditPhase(value: string): value is AuditPhase {
+  return VALID_PHASES.has(value)
+}
+
 function extractPhase(payload: unknown): AuditPhase | undefined {
   if (typeof payload === "string") {
-    return payload as AuditPhase
+    return isAuditPhase(payload) ? payload : undefined
   }
 
   if (!isRecord(payload)) return undefined
 
-  if (typeof payload.phase === "string") {
-    return payload.phase as AuditPhase
+  if (typeof payload.phase === "string" && isAuditPhase(payload.phase)) {
+    return payload.phase
   }
 
-  if (typeof payload.currentPhase === "string") {
-    return payload.currentPhase as AuditPhase
+  if (typeof payload.currentPhase === "string" && isAuditPhase(payload.currentPhase)) {
+    return payload.currentPhase
   }
 
   return undefined
@@ -86,7 +91,8 @@ function resolveToolName(event: AuditEvent, payload: Record<string, unknown>): s
 }
 
 function resolveFindingsCount(payload: Record<string, unknown>): number {
-  return typeof payload.findingsCount === "number" ? payload.findingsCount : 0
+  const count = typeof payload.findingsCount === "number" ? payload.findingsCount : 0
+  return Number.isFinite(count) ? Math.max(0, count) : 0
 }
 
 function resolveToolSuccess(payload: Record<string, unknown>): boolean {
@@ -406,12 +412,13 @@ export function projectReportInput(
   const proxyContracts = extractLatestFromPayload(events, "proxyContracts", asProxyContracts)
   const patternVersion = extractLatestFromPayload(events, "patternVersion", asString)
   const skillsLoaded = extractLatestFromPayload(events, "skillsLoaded", asStringArray)
+  const unavailableTools = extractLatestFromPayload(events, "unavailableTools", asStringArray)
 
   return {
     run_id: runId,
     seq: events.at(-1)?.seq ?? 0,
     session_id: sessionCreated?.session_id ?? events[0]?.session_id ?? "",
-    tool_call_id: latestFinalized?.tool_call_id ?? "",
+    tool_call_id: latestFinalized?.tool_call_id ?? "pending-finalization",
     source: latestFinalized?.source ?? events[0]?.source ?? "projector",
     schema_version: latestFinalized?.schema_version ?? events[0]?.schema_version ?? SCHEMA_VERSION,
     projectDir,
@@ -425,6 +432,7 @@ export function projectReportInput(
     proxyContracts,
     patternVersion,
     skillsLoaded,
+    unavailableTools,
   }
 }
 

package/src/state/schemas.ts

@@ -1,3 +1,10 @@
+import { isRecord } from "../shared/type-guards"
+import {
+  VALID_AGENTS,
+  VALID_CONFIDENCES,
+  VALID_SEVERITIES,
+  VALID_SOURCES,
+} from "../shared/validation-constants"
 import type {
   ArgusAgentName,
   AuditPhase,
@@ -112,6 +119,7 @@ export interface ReportInput {
   proxyContracts?: ProxyContract[]
   patternVersion?: string
   skillsLoaded?: string[]
+  unavailableTools?: string[]
 }
 
 function pushRequiredRootStringError(
@@ -142,38 +150,6 @@ function pushRequiredRootNumberError(
   }
 }
 
-const VALID_SEVERITIES: ReadonlySet<FindingSeverity> = new Set([
-  "Critical",
-  "High",
-  "Medium",
-  "Low",
-  "Informational",
-])
-const VALID_CONFIDENCES: ReadonlySet<CanonicalFinding["confidence"]> = new Set([
-  "High",
-  "Medium",
-  "Low",
-])
-const VALID_SOURCES: ReadonlySet<CanonicalFinding["source"]> = new Set([
-  "slither",
-  "manual",
-  "pattern",
-  "scvd",
-  "solodit",
-  "fuzz",
-])
-const VALID_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
-  "argus",
-  "sentinel",
-  "pythia",
-  "scribe",
-  "unknown",
-])
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
 function pushRequiredStringError(
   errors: ValidationError[],
   obj: Record<string, unknown>,

package/src/state/types.ts

@@ -28,6 +28,9 @@ export interface Finding {
   reported_by_agents?: string[]
   sources?: string[]
   observation_count?: number
+  impact?: string
+  recommendation?: string
+  proofOfConcept?: string
   remediation?: string
   exploitReference?: string
   provenance?: {

package/src/tools/contract-analyzer-tool.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs"
 import { basename } from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { FOUNDRY_NOT_FOUND_MESSAGE } from "../shared/forge-errors"
 import { findFoundryProjectDir } from "../shared/project-utils"
 import type { ContractProfile } from "../state/types"
 import { extractContractInfo, parseExternalCalls } from "../utils/solidity-parser"
@@ -39,7 +40,8 @@ function createFailureProfile(
 }
 
 function addIndicator(indicators: Set<string>, source: string, indicator: string): void {
-  if (source.includes(indicator.split("uses-")[1] ?? "")) {
+  const keyword = indicator.split("uses-")[1]
+  if (keyword && source.includes(keyword)) {
     indicators.add(indicator)
   }
 }
@@ -224,11 +226,7 @@ export async function executeContractAnalyzer(
 
     const maybeError = error as Error & { code?: string }
     if (maybeError.code === "ENOENT") {
-      return createFailureProfile(
-        contractName,
-        filePath,
-        "Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash",
-      )
+      return createFailureProfile(contractName, filePath, FOUNDRY_NOT_FOUND_MESSAGE)
     }
 
     const message = maybeError.message || "contract analysis failed"

package/src/tools/forge-coverage-tool.ts

@@ -1,4 +1,6 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { classifyForgeError } from "../shared/forge-errors"
+import { runForgeCommand } from "../shared/forge-runner"
 import { resolveProjectDir } from "../shared/project-utils"
 
 type ForgeCoverageArgs = {
@@ -38,8 +40,7 @@ type ForgeCoverageResult = {
 
 export type ForgeCommandRunner = (
   command: string[],
-  signal: AbortSignal,
-  cwd: string,
+  options: { signal?: AbortSignal; cwd?: string; env?: Record<string, string> },
 ) => Promise<{ stdout: string; stderr: string; exitCode: number }>
 
 const EMPTY_SUMMARY: ForgeCoverageSummary = {
@@ -138,27 +139,6 @@ function parseCoverageReport(output: string): ForgeCoverageReport {
   return { files, summary }
 }
 
-const runForgeCommand: ForgeCommandRunner = async (command, signal, cwd) => {
-  const child = Bun.spawn(command, {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    signal,
-  })
-
-  const [exitCode, stdout, stderr] = await Promise.all([
-    child.exited,
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-  ])
-
-  return {
-    stdout,
-    stderr,
-    exitCode,
-  }
-}
-
 export async function executeForgeCoverage(
   args: ForgeCoverageArgs,
   context: ToolContext,
@@ -176,7 +156,10 @@ export async function executeForgeCoverage(
   })
 
   try {
-    const runResult = await runCommand(["forge", "coverage"], context.abort, normalizedArgs.target)
+    const runResult = await runCommand(["forge", "coverage"], {
+      signal: context.abort,
+      cwd: normalizedArgs.target,
+    })
 
     if (runResult.exitCode !== 0) {
       return fail(
@@ -197,18 +180,10 @@ export async function executeForgeCoverage(
       executionTime: Date.now() - startedAt,
     }
   } catch (error) {
-    if (context.abort.aborted || (error instanceof DOMException && error.name === "AbortError")) {
-      return fail("forge coverage aborted")
-    }
-
-    const maybeError = error as Error & { code?: string }
-    if (maybeError.code === "ENOENT") {
-      return fail("Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash")
-    }
-    if (maybeError.code === "ETIMEDOUT" || maybeError.message.toLowerCase().includes("timed out")) {
-      return fail("forge coverage timed out")
-    }
+    const classified = classifyForgeError(error, context, "forge coverage")
+    if (classified) return fail(classified)
 
+    const maybeError = error as Error
     return fail(maybeError.message || "forge coverage failed")
   }
 }

package/src/tools/forge-fuzz-tool.ts

@@ -1,4 +1,7 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { classifyForgeError } from "../shared/forge-errors"
+import { runForgeCommand } from "../shared/forge-runner"
+import { assertContained, validateUrlScheme } from "../shared/path-containment"
 import { resolveProjectDir } from "../shared/project-utils"
 
 type ForgeFuzzArgs = {
@@ -47,16 +50,20 @@ export type ForgeFuzzCommandResult = {
 
 type RunForgeFuzzCommand = (
   command: string[],
-  signal: AbortSignal,
-  cwd: string,
-  env: Record<string, string>,
+  options: { signal?: AbortSignal; cwd?: string; env?: Record<string, string> },
 ) => Promise<ForgeFuzzCommandResult>
 
 function normalizeArgs(args: ForgeFuzzArgs, context: ToolContext): NormalizedForgeFuzzArgs {
   const requestedRuns =
     typeof args.runs === "number" && Number.isFinite(args.runs) ? args.runs : 256
   const clampedRuns = Math.max(1, Math.min(10000, Math.floor(requestedRuns)))
-  const target = args.target && args.target !== "." ? args.target : resolveProjectDir(context)
+  const projectRoot = resolveProjectDir(context)
+  const target =
+    args.target && args.target !== "." ? assertContained(args.target, projectRoot) : projectRoot
+
+  if (args.fork_url && !validateUrlScheme(args.fork_url)) {
+    throw new Error(`fork_url must use http:// or https:// scheme, got: "${args.fork_url}"`)
+  }
 
   return {
     target,
@@ -177,36 +184,12 @@ function parseCounterexampleLine(line: string):
   }
 }
 
-const runForgeFuzzCommand: RunForgeFuzzCommand = async (command, signal, cwd, env) => {
-  const child = Bun.spawn(command, {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    signal,
-    env,
-  })
-
-  const [exitCode, stdout, stderr] = await Promise.all([
-    child.exited,
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-  ])
-
-  return {
-    stdout,
-    stderr,
-    exitCode,
-  }
-}
-
 export async function executeForgeFuzz(
   args: ForgeFuzzArgs,
   context: ToolContext,
-  runCommand: RunForgeFuzzCommand = runForgeFuzzCommand,
+  runCommand: RunForgeFuzzCommand = runForgeCommand,
 ): Promise<ForgeFuzzResult> {
   const startedAt = Date.now()
-  const normalized = normalizeArgs(args, context)
-  context.metadata({ title: `Run forge fuzz: ${normalized.target}` })
 
   const fail = (error: string): ForgeFuzzResult => ({
     success: false,
@@ -218,17 +201,12 @@ export async function executeForgeFuzz(
   })
 
   try {
-    const env = {
-      ...Bun.env,
-      FOUNDRY_FUZZ_RUNS: String(normalized.runs),
-    }
-
-    const runResult = await runCommand(
-      buildForgeFuzzCommand(normalized),
-      context.abort,
-      normalized.target,
-      env,
-    )
+    const normalized = normalizeArgs(args, context)
+    context.metadata({ title: `Run forge fuzz: ${normalized.target}` })
+    const runResult = await runCommand(buildForgeFuzzCommand(normalized), {
+      signal: context.abort,
+      cwd: normalized.target,
+    })
 
     const lines = `${runResult.stdout}\n${runResult.stderr}`
       .split(/\r?\n/)
@@ -278,18 +256,10 @@ export async function executeForgeFuzz(
 
     return output
   } catch (error) {
-    if (context.abort.aborted || (error instanceof DOMException && error.name === "AbortError")) {
-      return fail("forge fuzz aborted")
-    }
-
-    const maybeError = error as Error & { code?: string }
-    if (maybeError.code === "ENOENT") {
-      return fail("Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash")
-    }
-    if (maybeError.code === "ETIMEDOUT" || maybeError.message.toLowerCase().includes("timed out")) {
-      return fail("forge fuzz timed out")
-    }
+    const classified = classifyForgeError(error, context, "forge fuzz")
+    if (classified) return fail(classified)
 
+    const maybeError = error as Error
     return fail(maybeError.message || "forge fuzz failed")
   }
 }

package/src/tools/forge-test-tool.ts

@@ -1,4 +1,7 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { classifyForgeError } from "../shared/forge-errors"
+import { runForgeCommand } from "../shared/forge-runner"
+import { assertContained, validateUrlScheme } from "../shared/path-containment"
 import { resolveProjectDir } from "../shared/project-utils"
 import { extractJson } from "../utils/solidity-parser"
 
@@ -62,8 +65,7 @@ export type ForgeCommandResult = {
 
 type RunForgeCommand = (
   command: string[],
-  signal: AbortSignal,
-  cwd: string,
+  options: { signal?: AbortSignal; cwd?: string; env?: Record<string, string> },
 ) => Promise<ForgeCommandResult>
 
 type ForgeTestPayload = {
@@ -277,7 +279,14 @@ function parseCoverage(payload: CoveragePayload): { files: ForgeCoverageFile[] }
 }
 
 function normalizeArgs(args: ForgeTestArgs, context: ToolContext): NormalizedForgeTestArgs {
-  const target = args.target && args.target !== "." ? args.target : resolveProjectDir(context)
+  const projectRoot = resolveProjectDir(context)
+  const target =
+    args.target && args.target !== "." ? assertContained(args.target, projectRoot) : projectRoot
+
+  if (args.fork_url && !validateUrlScheme(args.fork_url)) {
+    throw new Error(`fork_url must use http:// or https:// scheme, got: "${args.fork_url}"`)
+  }
+
   return {
     target,
     match_test: args.match_test,
@@ -311,35 +320,12 @@ function buildForgeTestCommand(args: NormalizedForgeTestArgs): string[] {
   return command
 }
 
-const runForgeCommand: RunForgeCommand = async (command, signal, cwd) => {
-  const child = Bun.spawn(command, {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    signal,
-  })
-
-  const [exitCode, stdout, stderr] = await Promise.all([
-    child.exited,
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-  ])
-
-  return {
-    stdout,
-    stderr,
-    exitCode,
-  }
-}
-
 export async function executeForgeTest(
   args: ForgeTestArgs,
   context: ToolContext,
   runCommand: RunForgeCommand = runForgeCommand,
 ): Promise<ForgeTestResult> {
   const startedAt = Date.now()
-  const normalizedArgs = normalizeArgs(args, context)
-  context.metadata({ title: `Run forge test: ${normalizedArgs.target}` })
 
   const fail = (error: string): ForgeTestResult => ({
     success: false,
@@ -350,11 +336,12 @@ export async function executeForgeTest(
   })
 
   try {
-    const testResult = await runCommand(
-      buildForgeTestCommand(normalizedArgs),
-      context.abort,
-      normalizedArgs.target,
-    )
+    const normalizedArgs = normalizeArgs(args, context)
+    context.metadata({ title: `Run forge test: ${normalizedArgs.target}` })
+    const testResult = await runCommand(buildForgeTestCommand(normalizedArgs), {
+      signal: context.abort,
+      cwd: normalizedArgs.target,
+    })
 
     let payload: ForgeTestPayload
     try {
@@ -380,11 +367,10 @@ export async function executeForgeTest(
     }
 
     if (normalizedArgs.coverage) {
-      const coverageResult = await runCommand(
-        ["forge", "coverage", "--report", "json"],
-        context.abort,
-        normalizedArgs.target,
-      )
+      const coverageResult = await runCommand(["forge", "coverage", "--report", "json"], {
+        signal: context.abort,
+        cwd: normalizedArgs.target,
+      })
       if (coverageResult.exitCode !== 0) {
         output.error = coverageResult.stderr.trim() || "forge coverage failed"
         output.success = false
@@ -406,18 +392,10 @@ export async function executeForgeTest(
 
     return output
   } catch (error) {
-    if (context.abort.aborted || (error instanceof DOMException && error.name === "AbortError")) {
-      return fail("forge test aborted")
-    }
-
-    const maybeError = error as Error & { code?: string }
-    if (maybeError.code === "ENOENT") {
-      return fail("Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash")
-    }
-    if (maybeError.code === "ETIMEDOUT" || maybeError.message.toLowerCase().includes("timed out")) {
-      return fail("forge test timed out")
-    }
+    const classified = classifyForgeError(error, context, "forge test")
+    if (classified) return fail(classified)
 
+    const maybeError = error as Error
     return fail(maybeError.message || "forge test failed")
   }
 }

package/src/tools/gas-analysis-tool.ts

@@ -1,4 +1,6 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { classifyForgeError } from "../shared/forge-errors"
+import { runForgeCommand } from "../shared/forge-runner"
 import { resolveProjectDir } from "../shared/project-utils"
 
 type GasAnalysisArgs = {
@@ -43,8 +45,7 @@ type GasAnalysisResult = {
 
 export type ForgeCommandRunner = (
   command: string[],
-  signal: AbortSignal,
-  cwd: string,
+  options: { signal?: AbortSignal; cwd?: string; env?: Record<string, string> },
 ) => Promise<{ stdout: string; stderr: string; exitCode: number }>
 
 function toNumber(value: string): number {
@@ -58,7 +59,7 @@ function toNumber(value: string): number {
 
 function parseCells(line: string): string[] {
   return line
-    .split(/[│┆]/)
+    .split(/[│┆|]/)
     .map((cell) => cell.trim())
     .filter((cell) => cell.length > 0)
 }
@@ -75,7 +76,7 @@ function parseGasReport(stdout: string): ContractGasReport[] {
   let inFunctionSection = false
 
   for (const line of lines) {
-    if (!line.includes("│") && !line.includes("┆")) {
+    if (!line.includes("│") && !line.includes("┆") && !line.includes("|")) {
       continue
     }
 
@@ -161,27 +162,6 @@ function normalizeArgs(args: GasAnalysisArgs, context: ToolContext): NormalizedG
   }
 }
 
-const runForgeCommand: ForgeCommandRunner = async (command, signal, cwd) => {
-  const child = Bun.spawn(command, {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    signal,
-  })
-
-  const [exitCode, stdout, stderr] = await Promise.all([
-    child.exited,
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-  ])
-
-  return {
-    stdout,
-    stderr,
-    exitCode,
-  }
-}
-
 export async function executeGasAnalysis(
   args: GasAnalysisArgs,
   context: ToolContext,
@@ -200,11 +180,10 @@ export async function executeGasAnalysis(
   })
 
   try {
-    const forgeResult = await runCommand(
-      ["forge", "test", "--gas-report"],
-      context.abort,
-      normalizedArgs.target,
-    )
+    const forgeResult = await runCommand(["forge", "test", "--gas-report"], {
+      signal: context.abort,
+      cwd: normalizedArgs.target,
+    })
 
     const contracts = parseGasReport(forgeResult.stdout)
     const hotspots = contracts
@@ -234,18 +213,10 @@ export async function executeGasAnalysis(
 
     return output
   } catch (error) {
-    if (context.abort.aborted || (error instanceof DOMException && error.name === "AbortError")) {
-      return fail("forge gas analysis aborted")
-    }
-
-    const maybeError = error as Error & { code?: string }
-    if (maybeError.code === "ENOENT") {
-      return fail("Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash")
-    }
-    if (maybeError.code === "ETIMEDOUT" || maybeError.message.toLowerCase().includes("timed out")) {
-      return fail("forge gas analysis timed out")
-    }
+    const classified = classifyForgeError(error, context, "forge gas analysis")
+    if (classified) return fail(classified)
 
+    const maybeError = error as Error
     return fail(maybeError.message || "forge gas analysis failed")
   }
 }