solidity-argus 0.1.0

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

@@ -0,0 +1,234 @@
+import type { AuditState, FindingSeverity } from "../state/types"
+import type { FindingStore } from "../state/finding-store"
+
+type ToolHookInput = {
+  tool: string
+  args: unknown
+  result: string
+}
+
+const VALID_SEVERITIES: ReadonlySet<string> = new Set([
+  "Critical",
+  "High",
+  "Medium",
+  "Low",
+  "Informational",
+])
+
+const VALID_CONFIDENCES: ReadonlySet<string> = new Set([
+  "High",
+  "Medium",
+  "Low",
+])
+
+function toSeverity(value: unknown): FindingSeverity {
+  if (typeof value === "string" && VALID_SEVERITIES.has(value)) {
+    return value as FindingSeverity
+  }
+  return "Informational"
+}
+
+function toConfidence(value: unknown): "High" | "Medium" | "Low" {
+  if (typeof value === "string" && VALID_CONFIDENCES.has(value)) {
+    return value as "High" | "Medium" | "Low"
+  }
+  return "Low"
+}
+
+function toLines(value: unknown): [number, number] | undefined {
+  if (
+    Array.isArray(value) &&
+    value.length >= 2 &&
+    typeof value[0] === "number" &&
+    typeof value[1] === "number"
+  ) {
+    return [value[0], value[1]]
+  }
+  return undefined
+}
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return undefined
+}
+
+function processSlitherResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore
+): number {
+  const findings = parsed.findings
+  if (!Array.isArray(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
+    ) {
+      continue
+    }
+
+    store.addFinding({
+      check,
+      severity: toSeverity(finding.severity),
+      confidence: toConfidence(finding.confidence),
+      description,
+      file,
+      lines,
+      source: "slither",
+    })
+    count++
+  }
+
+  return count
+}
+
+function processPatternResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore
+): number {
+  const sources = parsed.sources
+  if (!Array.isArray(sources)) return 0
+
+  let count = 0
+  for (const rawSource of sources) {
+    const source = toRecord(rawSource)
+    if (!source) continue
+
+    const matches = source.matches
+    if (!Array.isArray(matches)) continue
+
+    for (const rawMatch of matches) {
+      const match = toRecord(rawMatch)
+      if (!match) continue
+
+      const pattern = match.pattern
+      const description = match.description
+      const file = match.file
+      const lines = toLines(match.lines)
+
+      if (
+        typeof pattern !== "string" ||
+        typeof description !== "string" ||
+        typeof file !== "string" ||
+        !lines
+      ) {
+        continue
+      }
+
+      store.addFinding({
+        check: pattern,
+        severity: toSeverity(match.severity),
+        confidence: "Medium",
+        description,
+        file,
+        lines,
+        source: "pattern",
+      })
+      count++
+    }
+  }
+
+  return count
+}
+
+function processContractAnalyzerResult(
+  parsed: Record<string, unknown>,
+  state: AuditState
+): void {
+  // Handle direct ContractProfile format (actual tool output)
+  if (typeof parsed.filePath === "string") {
+    if (!state.contractsReviewed.includes(parsed.filePath)) {
+      state.contractsReviewed.push(parsed.filePath)
+    }
+    return
+  }
+
+  // Handle wrapped { contractProfile: { filePath } } format
+  const profile = toRecord(parsed.contractProfile)
+  if (profile && typeof profile.filePath === "string") {
+    if (!state.contractsReviewed.includes(profile.filePath)) {
+      state.contractsReviewed.push(profile.filePath)
+    }
+  }
+}
+
+function recordToolExecution(
+  state: AuditState,
+  toolName: string,
+  findingsCount: number
+): void {
+  const alreadyRecorded = state.toolsExecuted.some(
+    (execution) => execution.tool === toolName
+  )
+  if (alreadyRecorded) return
+
+  const now = Date.now()
+  state.toolsExecuted.push({
+    tool: toolName,
+    startTime: now,
+    endTime: now,
+    success: true,
+    findingsCount,
+  })
+}
+
+/**
+ * Creates a tool tracking hook that intercepts argus_* tool results
+ * and updates audit state with extracted findings.
+ *
+ * Non-argus tools are ignored. Malformed JSON results are silently skipped.
+ * Findings are deduplicated via the FindingStore (by check+file+lines).
+ */
+export function createToolTrackingHook(
+  auditState: AuditState,
+  store: FindingStore
+): (input: ToolHookInput) => Promise<void> {
+  return async (input: ToolHookInput): Promise<void> => {
+    if (!input.tool.startsWith("argus_")) {
+      return
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(input.result)
+    } catch {
+      return // non-JSON tool output — nothing to track
+    }
+
+    const record = toRecord(parsed)
+    if (!record) return
+
+    let findingsCount = 0
+
+    switch (input.tool) {
+      case "argus_slither_analyze":
+        findingsCount = processSlitherResult(record, store)
+        break
+      case "argus_check_patterns":
+        findingsCount = processPatternResult(record, store)
+        break
+      case "argus_analyze_contract":
+        processContractAnalyzerResult(record, auditState)
+        break
+      case "argus_forge_test":
+      case "argus_forge_fuzz":
+        // No findings to extract — counterexamples are informational
+        break
+    }
+
+    recordToolExecution(auditState, input.tool, findingsCount)
+  }
+}

package/src/hooks/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Hook system types
+ * Defines all available hook names in the Argus plugin
+ */
+
+export type HookName =
+  | "system-prompt"
+  | "compaction"
+  | "tool-tracking"
+  | "event"
+  | "knowledge-sync"
+  | "session-recovery"
+  | "tool-error-recovery"
+  | "context-window-monitor"
+  | "tool-output-truncator"
+  | "audit-continuation";

package/src/index.ts

@@ -0,0 +1,36 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { spawn } from "node:child_process"
+import { loadArgusConfig } from "./config/loader"
+import { createHookGuard } from "./hooks/hook-system"
+import { createTools } from "./create-tools"
+import { createHooks } from "./create-hooks"
+import { createManagers } from "./create-managers"
+import { createPluginInterface } from "./plugin-interface"
+
+function startSoloditMcp(port: number): void {
+  const child = spawn("npx", ["-y", "@lyuboslavlyubenov/solodit-mcp"], {
+    stdio: "ignore",
+    detached: false,
+    env: { ...process.env, PORT: String(port) },
+  })
+  child.unref()
+  child.on("error", () => {})
+}
+
+const ArgusPlugin: Plugin = async (ctx) => {
+  const projectDir = ctx.directory ?? process.cwd()
+  const config = loadArgusConfig(projectDir)
+
+  if (config.solodit?.enabled !== false) {
+    startSoloditMcp(config.solodit?.port ?? 3000)
+  }
+
+  const isHookEnabled = createHookGuard(config.disabled_hooks)
+  const managers = createManagers({ projectDir, config })
+  const tools = createTools(config)
+  const hooks = createHooks({ config, managers, projectDir, isHookEnabled })
+
+  return createPluginInterface({ tools, hooks })
+}
+
+export default ArgusPlugin

package/src/knowledge/scvd-client.ts

@@ -0,0 +1,242 @@
+export interface ScvdFinding {
+  scvd_id: string;
+  doc_id: string;
+  title: string;
+  description_md: string;
+  severity: "Critical" | "High" | "Medium" | "Low" | "Informational";
+  taxonomy: { swc: string[]; cwe: string[] };
+  repo: { url: string; commit?: string; lines?: [number, number] };
+  sections: { recommendation_md?: string; poc_md?: string };
+}
+
+export interface ScvdStats {
+  total: number;
+  by_severity: Record<string, number>;
+  last_updated: string;
+}
+
+const DEFAULT_PAGE_SIZE = 100;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function toNumberRecord(value: unknown): Record<string, number> {
+  if (!isRecord(value)) {
+    return {};
+  }
+
+  const output: Record<string, number> = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (typeof rawValue === "number" && Number.isFinite(rawValue)) {
+      output[key] = rawValue;
+    }
+  }
+
+  return output;
+}
+
+function parseLines(value: unknown): [number, number] | undefined {
+  if (!Array.isArray(value) || value.length !== 2) {
+    return undefined;
+  }
+
+  const start = value[0];
+  const end = value[1];
+
+  if (typeof start !== "number" || typeof end !== "number") {
+    return undefined;
+  }
+
+  return [start, end];
+}
+
+function parseFinding(raw: unknown): ScvdFinding | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+
+  const taxonomyRaw = isRecord(raw.taxonomy) ? raw.taxonomy : {};
+  const repoRaw = isRecord(raw.repo) ? raw.repo : {};
+  const sectionsRaw = isRecord(raw.sections) ? raw.sections : {};
+
+  const scvdId = raw.scvd_id;
+  const docId = raw.doc_id;
+  const title = raw.title;
+  const description = raw.description_md;
+  const severity = raw.severity;
+  const repoUrl = repoRaw.url;
+
+  if (
+    typeof scvdId !== "string" ||
+    typeof docId !== "string" ||
+    typeof title !== "string" ||
+    typeof description !== "string" ||
+    typeof repoUrl !== "string"
+  ) {
+    return null;
+  }
+
+  if (
+    severity !== "Critical" &&
+    severity !== "High" &&
+    severity !== "Medium" &&
+    severity !== "Low" &&
+    severity !== "Informational"
+  ) {
+    return null;
+  }
+
+  return {
+    scvd_id: scvdId,
+    doc_id: docId,
+    title,
+    description_md: description,
+    severity,
+    taxonomy: {
+      swc: toStringArray(taxonomyRaw.swc),
+      cwe: toStringArray(taxonomyRaw.cwe),
+    },
+    repo: {
+      url: repoUrl,
+      commit: typeof repoRaw.commit === "string" ? repoRaw.commit : undefined,
+      lines: parseLines(repoRaw.lines),
+    },
+    sections: {
+      recommendation_md:
+        typeof sectionsRaw.recommendation_md === "string"
+          ? sectionsRaw.recommendation_md
+          : undefined,
+      poc_md: typeof sectionsRaw.poc_md === "string" ? sectionsRaw.poc_md : undefined,
+    },
+  };
+}
+
+function parseFindings(raw: unknown): ScvdFinding[] {
+  if (!Array.isArray(raw)) {
+    if (isRecord(raw) && Array.isArray(raw.data)) {
+      return raw.data.map(parseFinding).filter((value): value is ScvdFinding => value !== null);
+    }
+    return [];
+  }
+
+  return raw.map(parseFinding).filter((value): value is ScvdFinding => value !== null);
+}
+
+function parseStats(raw: unknown): ScvdStats {
+  if (!isRecord(raw)) {
+    throw new Error("Invalid SCVD stats response payload");
+  }
+
+  const total = raw.total;
+  const lastUpdated = raw.last_updated;
+
+  if (typeof total !== "number" || typeof lastUpdated !== "string") {
+    throw new Error("Invalid SCVD stats fields in response");
+  }
+
+  return {
+    total,
+    by_severity: toNumberRecord(raw.by_severity),
+    last_updated: lastUpdated,
+  };
+}
+
+export class ScvdClient {
+  private readonly baseUrl: string;
+  private readonly signal?: AbortSignal;
+
+  constructor(apiUrl: string, signal?: AbortSignal) {
+    this.baseUrl = apiUrl.replace(/\/$/, "");
+    this.signal = signal;
+  }
+
+  async fetchStats(): Promise<ScvdStats> {
+    const url = `${this.baseUrl}/stats`;
+
+    let response: Response;
+    try {
+      response = await fetch(url, { signal: this.signal });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown network error";
+      throw new Error(`Failed to fetch SCVD stats from ${url}: ${message}`);
+    }
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`);
+    }
+
+    const body = (await response.json()) as unknown;
+    return parseStats(body);
+  }
+
+  async fetchFindings(params: {
+    severity?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<ScvdFinding[]> {
+    const searchParams = new URLSearchParams();
+
+    if (params.severity) {
+      searchParams.set("severity", params.severity);
+    }
+    if (typeof params.limit === "number") {
+      searchParams.set("limit", String(params.limit));
+    }
+    if (typeof params.offset === "number") {
+      searchParams.set("offset", String(params.offset));
+    }
+
+    const query = searchParams.toString();
+    const url = `${this.baseUrl}/findings${query.length > 0 ? `?${query}` : ""}`;
+
+    try {
+      const response = await fetch(url, { signal: this.signal });
+      if (!response.ok) {
+        return [];
+      }
+
+      const body = (await response.json()) as unknown;
+      return parseFindings(body);
+    } catch {
+      return []; // network error — treat as empty page
+    }
+  }
+
+  async fetchAllFindings(onProgress?: (count: number) => void): Promise<ScvdFinding[]> {
+    const results: ScvdFinding[] = [];
+    let offset = 0;
+
+    while (true) {
+      const page = await this.fetchFindings({
+        limit: DEFAULT_PAGE_SIZE,
+        offset,
+      });
+
+      if (page.length === 0) {
+        break;
+      }
+
+      results.push(...page);
+      offset += page.length;
+
+      if (onProgress) {
+        onProgress(results.length);
+      }
+
+      if (page.length < DEFAULT_PAGE_SIZE) {
+        break;
+      }
+    }
+
+    return results;
+  }
+}

package/src/knowledge/scvd-index.ts

@@ -0,0 +1,183 @@
+import type { ScvdFinding } from "./scvd-client";
+
+export interface ScvdIndexEntry {
+  id: string;
+  title: string;
+  severity: string;
+  swc: string[];
+  cwe: string[];
+  keywords: string[];
+  repoUrl: string;
+}
+
+export interface ScvdIndex {
+  version: number;
+  lastSync: string;
+  totalFindings: number;
+  entries: ScvdIndexEntry[];
+}
+
+const INDEX_VERSION = 1;
+const DEFAULT_LIMIT = 10;
+
+function normalizeKeywordInput(value: string): string[] {
+  return value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/g)
+    .map((word) => word.trim())
+    .filter((word) => word.length > 1);
+}
+
+function uniqueWords(words: string[]): string[] {
+  return Array.from(new Set(words));
+}
+
+function findingToEntry(finding: ScvdFinding): ScvdIndexEntry {
+  const keywordSource = `${finding.title} ${finding.description_md}`;
+
+  return {
+    id: finding.scvd_id,
+    title: finding.title,
+    severity: finding.severity,
+    swc: finding.taxonomy.swc,
+    cwe: finding.taxonomy.cwe,
+    keywords: uniqueWords(normalizeKeywordInput(keywordSource)),
+    repoUrl: finding.repo.url,
+  };
+}
+
+export function buildIndex(findings: ScvdFinding[]): ScvdIndex {
+  const now = new Date().toISOString();
+  const entries = findings.map(findingToEntry);
+
+  return {
+    version: INDEX_VERSION,
+    lastSync: now,
+    totalFindings: entries.length,
+    entries,
+  };
+}
+
+export function searchIndex(
+  index: ScvdIndex,
+  query: {
+    swc?: string;
+    severity?: string;
+    keyword?: string;
+    limit?: number;
+  }
+): ScvdIndexEntry[] {
+  const normalizedKeyword = query.keyword?.toLowerCase().trim();
+  const limit = query.limit ?? DEFAULT_LIMIT;
+
+  const filtered = index.entries.filter((entry) => {
+    if (query.swc && !entry.swc.includes(query.swc)) {
+      return false;
+    }
+
+    if (query.severity && entry.severity !== query.severity) {
+      return false;
+    }
+
+    if (normalizedKeyword && normalizedKeyword.length > 0) {
+      const matchesKeyword = entry.keywords.some((keyword) =>
+        keyword.includes(normalizedKeyword)
+      );
+
+      if (!matchesKeyword) {
+        return false;
+      }
+    }
+
+    return true;
+  });
+
+  return filtered.slice(0, limit);
+}
+
+export async function saveIndex(index: ScvdIndex, filePath: string): Promise<void> {
+  const json = JSON.stringify(index, null, 2);
+  await Bun.write(filePath, json);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function parseStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function parseEntry(value: unknown): ScvdIndexEntry | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const id = value.id;
+  const title = value.title;
+  const severity = value.severity;
+  const repoUrl = value.repoUrl;
+
+  if (
+    typeof id !== "string" ||
+    typeof title !== "string" ||
+    typeof severity !== "string" ||
+    typeof repoUrl !== "string"
+  ) {
+    return null;
+  }
+
+  return {
+    id,
+    title,
+    severity,
+    swc: parseStringArray(value.swc),
+    cwe: parseStringArray(value.cwe),
+    keywords: parseStringArray(value.keywords),
+    repoUrl,
+  };
+}
+
+export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
+  const file = Bun.file(filePath);
+  const exists = await file.exists();
+
+  if (!exists) {
+    return null;
+  }
+
+  const raw = (await file.json()) as unknown;
+
+  if (!isRecord(raw)) {
+    return null;
+  }
+
+  const version = raw.version;
+  const lastSync = raw.lastSync;
+  const totalFindings = raw.totalFindings;
+  const rawEntries = raw.entries;
+
+  if (
+    typeof version !== "number" ||
+    typeof lastSync !== "string" ||
+    typeof totalFindings !== "number" ||
+    !Array.isArray(rawEntries)
+  ) {
+    return null;
+  }
+
+  const entries = rawEntries
+    .map(parseEntry)
+    .filter((entry): entry is ScvdIndexEntry => entry !== null);
+
+  return {
+    version,
+    lastSync,
+    totalFindings,
+    entries,
+  };
+}