solidity-argus 0.3.5 → 0.3.6

package/src/hooks/tool-tracking-hook.ts

@@ -12,7 +12,14 @@ import type { FindingStore } from "../state/finding-store"
 import { createFindingStore } from "../state/finding-store"
 import type { AuditEvent } from "../state/schemas"
 import { SCHEMA_VERSION } from "../state/schemas"
-import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
+import type {
+  ArgusAgentName,
+  AuditState,
+  Finding,
+  FindingSeverity,
+  FuzzCounterexample,
+  SoloditResult,
+} from "../state/types"
 
 const logger = createLogger()
 
@@ -30,6 +37,7 @@ type ToolExecutionMetadata = {
 export type ToolTrackingOptions = {
   getEventSink?: () => EventSink | null
   getSessionId?: () => string
+  getAgentName?: () => ArgusAgentName | undefined
   dropPolicy?: DropPolicy
   onChildSessionDetected?: (parentSessionId: string, childSessionId: string) => void
 }
@@ -77,13 +85,35 @@ function toRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined
 }
 
-async function emitToSink(sink: EventSink, event: AuditEvent): Promise<void> {
+function toFindingSource(value: unknown): Finding["source"] {
+  if (
+    value === "slither" ||
+    value === "manual" ||
+    value === "pattern" ||
+    value === "scvd" ||
+    value === "solodit" ||
+    value === "fuzz"
+  ) {
+    return value
+  }
+
+  return "manual"
+}
+
+async function emitToSink(
+  sink: EventSink,
+  event: AuditEvent,
+  options?: { failFast?: boolean },
+): Promise<void> {
   try {
     await sink.append(event)
   } catch (error) {
-    logger.error(
-      `Failed to emit ${event.type} event to sink: ${error instanceof Error ? error.message : String(error)}`,
-    )
+    const message = `Failed to emit ${event.type} event to sink: ${error instanceof Error ? error.message : String(error)}`
+    logger.error(message)
+
+    if (options?.failFast) {
+      throw new Error(message)
+    }
   }
 }
 
@@ -155,11 +185,13 @@ function identifyMissingFields(
 
 const SLITHER_REQUIRED = ["check", "description", "file", "lines"] as const
 const PATTERN_REQUIRED = ["pattern", "description", "file", "lines"] as const
+const MANUAL_REQUIRED = ["check", "description", "file", "lines"] as const
 
 function processSlitherResult(
   parsed: Record<string, unknown>,
   store: FindingStore,
   diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
 ): number {
   const findings = parsed.findings
   if (!Array.isArray(findings)) return 0
@@ -197,6 +229,8 @@ function processSlitherResult(
       file,
       lines,
       source: "slither",
+      reported_by_agent: metadata.reportedByAgent,
+      reported_by_session_id: metadata.reportedBySessionId,
     })
     count++
   }
@@ -208,6 +242,7 @@ function processPatternResult(
   parsed: Record<string, unknown>,
   store: FindingStore,
   diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
 ): number {
   const sources = parsed.sources
   if (!Array.isArray(sources)) return 0
@@ -252,6 +287,8 @@ function processPatternResult(
         file,
         lines,
         source: "pattern",
+        reported_by_agent: metadata.reportedByAgent,
+        reported_by_session_id: metadata.reportedBySessionId,
       })
       count++
     }
@@ -260,6 +297,89 @@ function processPatternResult(
   return count
 }
 
+function processRecordedFindingResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore,
+  diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
+): number {
+  const findings = parsed.findings
+  if (!Array.isArray(findings)) {
+    diag.error(
+      "MISSING_REQUIRED_FIELD",
+      "argus_record_finding result missing findings array",
+      "findings",
+    )
+    return 0
+  }
+
+  let count = 0
+  for (const raw of findings) {
+    const finding = toRecord(raw)
+    if (!finding) continue
+
+    const check = finding.check
+    const description = finding.description
+    const file = finding.file
+    const lines = toLines(finding.lines)
+
+    if (
+      typeof check !== "string" ||
+      typeof description !== "string" ||
+      typeof file !== "string" ||
+      !lines
+    ) {
+      const missing = identifyMissingFields(finding, MANUAL_REQUIRED)
+      diag.error(
+        "MISSING_REQUIRED_FIELD",
+        `Recorded finding skipped: missing ${missing.join(", ")}`,
+        missing[0],
+      )
+      continue
+    }
+
+    const reportedByAgentRaw = finding.reported_by_agent
+    const reportedByAgent =
+      reportedByAgentRaw === "argus" ||
+      reportedByAgentRaw === "sentinel" ||
+      reportedByAgentRaw === "pythia" ||
+      reportedByAgentRaw === "scribe" ||
+      reportedByAgentRaw === "unknown"
+        ? (reportedByAgentRaw as ArgusAgentName)
+        : metadata.reportedByAgent
+
+    store.addFinding({
+      check,
+      severity: toSeverity(finding.severity),
+      confidence: toConfidence(finding.confidence),
+      description,
+      file,
+      lines,
+      source: toFindingSource(finding.source),
+      remediation: typeof finding.remediation === "string" ? finding.remediation : undefined,
+      exploitReference:
+        typeof finding.exploitReference === "string" ? finding.exploitReference : undefined,
+      reported_by_agent: reportedByAgent,
+      reported_by_session_id:
+        typeof finding.reported_by_session_id === "string" &&
+        finding.reported_by_session_id.length > 0
+          ? finding.reported_by_session_id
+          : metadata.reportedBySessionId,
+      issue_fingerprint:
+        typeof finding.issue_fingerprint === "string" ? finding.issue_fingerprint : undefined,
+      observation_fingerprint:
+        typeof finding.observation_fingerprint === "string"
+          ? finding.observation_fingerprint
+          : undefined,
+      observation_id:
+        typeof finding.observation_id === "string" ? finding.observation_id : undefined,
+    })
+    count++
+  }
+
+  return count
+}
+
 function processContractAnalyzerResult(parsed: Record<string, unknown>, state: AuditState): void {
   if (typeof parsed.filePath === "string") {
     if (!state.contractsReviewed.includes(parsed.filePath)) {
@@ -427,6 +547,10 @@ export function createToolTrackingHook(
 
     const resolved = resolveStateAndStore()
     if (!resolved) {
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding requires active audit state")
+      }
+
       const sinkForNoState = options?.getEventSink?.()
       if (sinkForNoState) {
         const toolCallId = randomUUID()
@@ -453,6 +577,11 @@ export function createToolTrackingHook(
     const sink = options?.getEventSink?.()
     const runId = auditState.sessionId
     const sessionId = options?.getSessionId?.() ?? ""
+    const reportedByAgent = options?.getAgentName?.() ?? "unknown"
+    const findingMetadata = {
+      reportedByAgent,
+      reportedBySessionId: sessionId,
+    }
     const toolCallId = randomUUID()
     const policy = options?.dropPolicy ?? "warn"
     const diag = createDropDiagnosticsCollector(policy, "tool-tracking-hook", input.tool)
@@ -464,6 +593,7 @@ export function createToolTrackingHook(
           tool: input.tool,
           args: input.args,
         }),
+        { failFast: input.tool === "argus_record_finding" },
       )
     }
 
@@ -502,6 +632,9 @@ export function createToolTrackingHook(
     } catch {
       diag.error("MALFORMED_JSON", `Failed to parse JSON result from ${input.tool}`)
       lastDiagnostics = diag.getDiagnostics()
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding returned malformed JSON")
+      }
       diag.throwIfStrict()
       return
     }
@@ -509,6 +642,9 @@ export function createToolTrackingHook(
     const record = toRecord(parsed)
     if (!record) {
       lastDiagnostics = diag.getDiagnostics()
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding response must be a JSON object")
+      }
       return
     }
 
@@ -516,10 +652,13 @@ export function createToolTrackingHook(
 
     switch (input.tool) {
       case "argus_slither_analyze":
-        findingsCount = processSlitherResult(record, store, diag)
+        findingsCount = processSlitherResult(record, store, diag, findingMetadata)
         break
       case "argus_check_patterns":
-        findingsCount = processPatternResult(record, store, diag)
+        findingsCount = processPatternResult(record, store, diag, findingMetadata)
+        break
+      case "argus_record_finding":
+        findingsCount = processRecordedFindingResult(record, store, diag, findingMetadata)
         break
       case "argus_analyze_contract":
         processContractAnalyzerResult(record, auditState)
@@ -595,14 +734,32 @@ export function createToolTrackingHook(
     lastDiagnostics = diag.getDiagnostics()
     diag.throwIfStrict()
 
+    if (input.tool === "argus_record_finding" && findingsCount === 0) {
+      throw new Error("argus_record_finding did not persist any findings")
+    }
+
     recordToolExecution(auditState, input.tool, findingsCount)
     onStateChanged?.({ tool: input.tool, findingsCount })
 
+    if (input.tool === "argus_record_finding" && !sink) {
+      throw new Error("argus_record_finding requires an active event sink for durable persistence")
+    }
+
     if (sink) {
+      const failFast = input.tool === "argus_record_finding"
       const newFindings = auditState.findings.slice(findingsCountBefore)
-      for (const finding of newFindings) {
-        const { data: canonical } = normalizeToCanonicalFinding(finding, runId, 0)
-        await emitToSink(sink, buildEvent("finding.added", runId, sessionId, toolCallId, canonical))
+      for (const [index, finding] of newFindings.entries()) {
+        const { data: canonical } = normalizeToCanonicalFinding(finding, runId, 0, {
+          reportedByAgent,
+          reportedBySessionId: sessionId,
+          toolCallId,
+          observationId: `${toolCallId}:${index + 1}`,
+        })
+        await emitToSink(
+          sink,
+          buildEvent("finding.added", runId, sessionId, toolCallId, canonical),
+          { failFast },
+        )
       }
 
       await emitToSink(
@@ -612,6 +769,7 @@ export function createToolTrackingHook(
           findingsCount,
           success: true,
         }),
+        { failFast },
       )
     }
   }

package/src/shared/plugin-metadata.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+function resolvePluginVersion(): string {
+  try {
+    const currentDir = dirname(fileURLToPath(import.meta.url))
+    const packageJsonPath = resolve(currentDir, "../../package.json")
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      version?: unknown
+    }
+
+    if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
+      return packageJson.version
+    }
+  } catch (_error) {
+    return "unknown"
+  }
+
+  return "unknown"
+}
+
+export const ARGUS_PLUGIN_VERSION = resolvePluginVersion()

package/src/state/adapters.ts

@@ -1,10 +1,11 @@
+import { computeIssueFingerprint, computeObservationFingerprint } from "./finding-fingerprint"
 import {
   type CanonicalFinding,
   SCHEMA_VERSION,
   type ValidationError,
   validateCanonicalFinding,
 } from "./schemas"
-import type { AuditPhase, Finding, FindingSeverity } from "./types"
+import type { ArgusAgentName, AuditPhase, Finding, FindingSeverity } from "./types"
 
 export interface Diagnostic {
   level: "warn" | "error"
@@ -35,6 +36,13 @@ const VALID_SOURCES: ReadonlySet<CanonicalFinding["source"]> = new Set([
   "solodit",
   "fuzz",
 ])
+const VALID_REPORTED_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
+  "argus",
+  "sentinel",
+  "pythia",
+  "scribe",
+  "unknown",
+])
 
 const KNOWN_INPUT_FIELDS = new Set([
   "id",
@@ -59,9 +67,26 @@ const KNOWN_INPUT_FIELDS = new Set([
   "session_id",
   "tool_call_id",
   "schema_version",
+  "observation_id",
+  "observation_fingerprint",
+  "issue_fingerprint",
+  "reported_by_agent",
+  "reported_by_session_id",
+  "reportedByAgent",
+  "reportedBySessionId",
+  "observationId",
+  "observationFingerprint",
+  "issueFingerprint",
   "elements",
 ])
 
+export interface NormalizeFindingOptions {
+  reportedByAgent?: ArgusAgentName
+  reportedBySessionId?: string
+  toolCallId?: string
+  observationId?: string
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
@@ -143,6 +168,7 @@ export function normalizeToCanonicalFinding(
   raw: Finding | Record<string, unknown>,
   runId: string,
   seq: number,
+  options: NormalizeFindingOptions = {},
 ): AdapterResult<CanonicalFinding> {
   const diagnostics: Diagnostic[] = []
   const input = isRecord(raw) ? raw : {}
@@ -189,11 +215,74 @@ export function normalizeToCanonicalFinding(
       ? (input.source as CanonicalFinding["source"])
       : "manual"
 
+  const reportedByAgentRaw =
+    (typeof input.reported_by_agent === "string" ? input.reported_by_agent : undefined) ??
+    (typeof input.reportedByAgent === "string" ? input.reportedByAgent : undefined) ??
+    options.reportedByAgent ??
+    "unknown"
+  const reportedByAgent: ArgusAgentName = VALID_REPORTED_AGENTS.has(
+    reportedByAgentRaw as ArgusAgentName,
+  )
+    ? (reportedByAgentRaw as ArgusAgentName)
+    : "unknown"
+
+  const reportedBySessionId =
+    (typeof input.reported_by_session_id === "string" && input.reported_by_session_id.length > 0
+      ? input.reported_by_session_id
+      : undefined) ??
+    (typeof input.reportedBySessionId === "string" && input.reportedBySessionId.length > 0
+      ? input.reportedBySessionId
+      : undefined) ??
+    options.reportedBySessionId
+
+  const issueFingerprint =
+    (typeof input.issue_fingerprint === "string" && input.issue_fingerprint.length > 0
+      ? input.issue_fingerprint
+      : undefined) ??
+    (typeof input.issueFingerprint === "string" && input.issueFingerprint.length > 0
+      ? input.issueFingerprint
+      : undefined) ??
+    computeIssueFingerprint({
+      check,
+      file,
+      lines: lines ?? [0, 0],
+      severity: VALID_SEVERITIES.has(severity) ? severity : "Informational",
+    })
+
+  const observationId =
+    (typeof input.observation_id === "string" && input.observation_id.length > 0
+      ? input.observation_id
+      : undefined) ??
+    (typeof input.observationId === "string" && input.observationId.length > 0
+      ? input.observationId
+      : undefined) ??
+    options.observationId ??
+    `${runId}:${seq}:${computeObservationFingerprint({
+      issueFingerprint,
+      source,
+      reportedByAgent,
+      toolCallId: options.toolCallId,
+      sessionId: reportedBySessionId,
+    })}`
+
+  const observationFingerprint =
+    (typeof input.observation_fingerprint === "string" && input.observation_fingerprint.length > 0
+      ? input.observation_fingerprint
+      : undefined) ??
+    (typeof input.observationFingerprint === "string" && input.observationFingerprint.length > 0
+      ? input.observationFingerprint
+      : undefined) ??
+    computeObservationFingerprint({
+      issueFingerprint,
+      source,
+      reportedByAgent,
+      toolCallId: options.toolCallId,
+      sessionId: reportedBySessionId,
+      observationId,
+    })
+
   const canonical: CanonicalFinding = {
-    id:
-      typeof input.id === "string" && input.id.length > 0
-        ? input.id
-        : `${check}:${file}:${lines?.[0] ?? 0}`,
+    id: observationId,
     check,
     severity: VALID_SEVERITIES.has(severity) ? severity : "Informational",
     confidence: VALID_CONFIDENCES.has(confidence) ? confidence : "Low",
@@ -201,6 +290,11 @@ export function normalizeToCanonicalFinding(
     file,
     lines: lines ?? [0, 0],
     source,
+    reported_by_agent: reportedByAgent,
+    reported_by_session_id: reportedBySessionId,
+    issue_fingerprint: issueFingerprint,
+    observation_fingerprint: observationFingerprint,
+    observation_id: observationId,
     remediation: typeof input.remediation === "string" ? input.remediation : undefined,
     exploitReference:
       typeof input.exploitReference === "string" ? input.exploitReference : undefined,

package/src/state/finding-aggregation.ts

@@ -0,0 +1,100 @@
+import type { CanonicalFinding } from "./schemas"
+
+const SEVERITY_RANK: Record<CanonicalFinding["severity"], number> = {
+  Critical: 0,
+  High: 1,
+  Medium: 2,
+  Low: 3,
+  Informational: 4,
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right))
+}
+
+function compareObservations(left: CanonicalFinding, right: CanonicalFinding): number {
+  if (left.seq !== right.seq) return left.seq - right.seq
+  return left.observation_id.localeCompare(right.observation_id)
+}
+
+function compareFinalFindings(left: CanonicalFinding, right: CanonicalFinding): number {
+  const bySeverity = SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity]
+  if (bySeverity !== 0) return bySeverity
+
+  const byFile = left.file.localeCompare(right.file)
+  if (byFile !== 0) return byFile
+
+  const byLine = left.lines[0] - right.lines[0]
+  if (byLine !== 0) return byLine
+
+  return left.issue_fingerprint.localeCompare(right.issue_fingerprint)
+}
+
+export function dedupeFindingsForFinalOutput(findings: CanonicalFinding[]): CanonicalFinding[] {
+  const byIssue = new Map<string, CanonicalFinding[]>()
+  for (const finding of findings) {
+    const group = byIssue.get(finding.issue_fingerprint)
+    if (group) {
+      group.push(finding)
+    } else {
+      byIssue.set(finding.issue_fingerprint, [finding])
+    }
+  }
+
+  const merged: CanonicalFinding[] = []
+
+  for (const [issueFingerprint, observations] of byIssue.entries()) {
+    const sortedObservations = observations.slice().sort(compareObservations)
+    const base = sortedObservations[0]
+    if (!base) continue
+
+    const reportedByAgents = uniqueSorted(
+      sortedObservations.map((finding) => finding.reported_by_agent),
+    )
+    const sources = uniqueSorted(sortedObservations.map((finding) => finding.source))
+    const observationIds = sortedObservations
+      .map((finding) => finding.observation_id)
+      .sort((left, right) => left.localeCompare(right))
+
+    merged.push({
+      ...base,
+      id: issueFingerprint,
+      sources,
+      reported_by_agents: reportedByAgents,
+      observation_ids: observationIds,
+      observation_count: sortedObservations.length,
+    })
+  }
+
+  return merged.sort(compareFinalFindings)
+}
+
+export function issueFingerprintSet(findings: CanonicalFinding[]): Set<string> {
+  const set = new Set<string>()
+  for (const finding of findings) {
+    set.add(finding.issue_fingerprint)
+  }
+  return set
+}
+
+export function compareIssueFingerprintSets(
+  expected: CanonicalFinding[],
+  actual: CanonicalFinding[],
+): { missing: string[]; extra: string[]; matches: boolean } {
+  const expectedSet = issueFingerprintSet(expected)
+  const actualSet = issueFingerprintSet(actual)
+
+  const missing = Array.from(expectedSet)
+    .filter((fingerprint) => !actualSet.has(fingerprint))
+    .sort((left, right) => left.localeCompare(right))
+
+  const extra = Array.from(actualSet)
+    .filter((fingerprint) => !expectedSet.has(fingerprint))
+    .sort((left, right) => left.localeCompare(right))
+
+  return {
+    missing,
+    extra,
+    matches: missing.length === 0 && extra.length === 0,
+  }
+}

package/src/state/finding-fingerprint.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto"
+import type { ArgusAgentName, FindingSeverity } from "./types"
+
+type IssueFingerprintInput = {
+  check: string
+  file: string
+  lines: [number, number]
+  severity: FindingSeverity
+}
+
+type ObservationFingerprintInput = {
+  issueFingerprint: string
+  source: string
+  reportedByAgent: ArgusAgentName
+  toolCallId?: string
+  sessionId?: string
+  observationId?: string
+}
+
+function hash(parts: string[]): string {
+  return createHash("sha256").update(parts.join("|"), "utf8").digest("hex")
+}
+
+function normalizeText(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+export function computeIssueFingerprint(input: IssueFingerprintInput): string {
+  return hash([
+    normalizeText(input.check),
+    normalizeText(input.file),
+    String(input.lines[0]),
+    String(input.lines[1]),
+    input.severity,
+  ])
+}
+
+export function computeObservationFingerprint(input: ObservationFingerprintInput): string {
+  return hash([
+    input.issueFingerprint,
+    normalizeText(input.source),
+    input.reportedByAgent,
+    input.toolCallId ?? "",
+    input.sessionId ?? "",
+    input.observationId ?? "",
+  ])
+}