solidity-argus 0.1.7 → 0.2.0

package/src/skills/argus-skill-resolver.ts

@@ -0,0 +1,226 @@
+import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs"
+import { homedir } from "node:os"
+import { basename, extname, join, resolve } from "node:path"
+import type { ArgusConfig } from "../config/types"
+import { createLogger } from "../shared/logger"
+import { parseFrontmatter, validateSkillFrontmatter } from "./skill-schema"
+
+export type ResolvedSkill = {
+  name: string
+  description: string
+  filePath: string
+  source: "bundled" | "custom" | "trailofbits" | "opencode" | "claude"
+  content: string
+  source_url?: string
+  source_license?: string
+  imported_at?: string
+  source_hash?: string
+}
+
+const OMO_PROJECT_SKILLS_DIR = [".opencode", "skills"]
+const OMO_GLOBAL_SKILLS_DIR = [".config", "opencode", "skills"]
+const CLAUDE_PROJECT_SKILLS_DIR = [".claude", "skills"]
+const CLAUDE_GLOBAL_SKILLS_DIR = [".claude", "skills"]
+const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills")
+
+const SKILL_NAME_ALIASES: Record<string, string> = {
+  "vulnerability-patterns/reentrancy": "reentrancy",
+  "vulnerability-patterns/oracle-manipulation": "oracle-manipulation",
+  "vulnerability-patterns/access-control": "access-control",
+  "protocol-patterns/amm-dex": "amm-dex",
+  "protocol-patterns/lending-borrowing": "lending-borrowing",
+  "checklists/cyfrin-best-practices-upgrades": "cyfrin-best-practices-upgrades",
+  "references/exploit-reference": "exploit-reference",
+  "building-secure-contracts/token-integration-analyzer": "token-integration-analyzer",
+}
+
+function inferSkillNameFromPath(filePath: string): string {
+  if (basename(filePath) === "SKILL.md") {
+    return basename(resolve(filePath, ".."))
+  }
+  return basename(filePath, extname(filePath))
+}
+
+function parseSkillNameFromFrontmatter(content: string): string | null {
+  const match = content.match(/^name:\s*(.+)$/m)
+  if (!match) return null
+  return match[1]?.trim().replace(/^"|"$/g, "") ?? null
+}
+
+function parseSkillDescriptionFromFrontmatter(content: string): string {
+  const match = content.match(/^description:\s*(.+)$/m)
+  if (!match) return ""
+  const raw = match[1]?.trim() ?? ""
+  if (raw === ">" || raw === ">-") return ""
+  return raw.replace(/^"|"$/g, "")
+}
+
+function collectMarkdownFiles(root: string, maxDepth = 8): string[] {
+  if (!existsSync(root)) return []
+
+  const files: string[] = []
+  const stack: Array<{ dir: string; depth: number }> = [{ dir: root, depth: 0 }]
+
+  while (stack.length > 0) {
+    const current = stack.pop()
+    if (!current) continue
+    const { dir, depth } = current
+
+    let entries: Dirent[]
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (depth < maxDepth) stack.push({ dir: fullPath, depth: depth + 1 })
+        continue
+      }
+
+      if (!entry.isFile()) continue
+      if (extname(entry.name).toLowerCase() !== ".md") continue
+      files.push(fullPath)
+    }
+  }
+
+  return files
+}
+
+function getTrailOfBitsRoots(): string[] {
+  const pluginsDir = join(TOB_CACHE_DIR, "plugins")
+  if (!existsSync(pluginsDir)) return []
+
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(pluginsDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const roots: string[] = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const skillsDir = join(pluginsDir, entry.name, "skills")
+    if (existsSync(skillsDir)) roots.push(skillsDir)
+  }
+  return roots
+}
+
+export function normalizeSkillName(input: string): string {
+  const trimmed = input.trim()
+  const alias = SKILL_NAME_ALIASES[trimmed]
+  if (alias) return alias
+  if (trimmed.includes("/")) {
+    const last = trimmed.split("/").at(-1)
+    if (last) return last
+  }
+  return trimmed
+}
+
+type SkillRoot = {
+  path: string
+  source: ResolvedSkill["source"]
+}
+
+function resolveCustomSkillsRoot(projectDir: string, argusConfig?: ArgusConfig): string | null {
+  const customSkillsDir = argusConfig?.knowledge?.customSkillsDir
+  if (!customSkillsDir) return null
+  const resolvedCustom = customSkillsDir.startsWith("/")
+    ? customSkillsDir
+    : resolve(projectDir, customSkillsDir)
+  return existsSync(resolvedCustom) ? resolvedCustom : null
+}
+
+export function resolveSkillRoots(projectDir: string, argusConfig?: ArgusConfig): SkillRoot[] {
+  const precedence = argusConfig?.knowledge?.skillPrecedence ?? "bundled-first"
+
+  const bundledRoot: SkillRoot = { path: resolve(import.meta.dir, "../../skills"), source: "bundled" }
+  const customRoot = resolveCustomSkillsRoot(projectDir, argusConfig)
+  const customSkillRoot: SkillRoot | null = customRoot ? { path: customRoot, source: "custom" } : null
+
+  const roots: SkillRoot[] = []
+
+  if (precedence === "custom-first") {
+    if (customSkillRoot) roots.push(customSkillRoot)
+    roots.push(bundledRoot)
+  } else {
+    roots.push(bundledRoot)
+    if (customSkillRoot) roots.push(customSkillRoot)
+  }
+
+  for (const tobRoot of getTrailOfBitsRoots()) {
+    roots.push({ path: tobRoot, source: "trailofbits" })
+  }
+
+  roots.push({ path: join(projectDir, ...OMO_PROJECT_SKILLS_DIR), source: "opencode" })
+  roots.push({ path: join(homedir(), ...OMO_GLOBAL_SKILLS_DIR), source: "opencode" })
+  roots.push({ path: join(projectDir, ...CLAUDE_PROJECT_SKILLS_DIR), source: "claude" })
+  roots.push({ path: join(homedir(), ...CLAUDE_GLOBAL_SKILLS_DIR), source: "claude" })
+
+  const seen = new Set<string>()
+  return roots.filter((root) => {
+    if (!existsSync(root.path)) return false
+    if (seen.has(root.path)) return false
+    seen.add(root.path)
+    return true
+  })
+}
+
+export function resolveArgusSkills(projectDir: string, argusConfig?: ArgusConfig): Map<string, ResolvedSkill> {
+  const resolved = new Map<string, ResolvedSkill>()
+  const roots = resolveSkillRoots(projectDir, argusConfig)
+  const logger = createLogger()
+
+  for (const root of roots) {
+    const markdownFiles = collectMarkdownFiles(root.path)
+    for (const markdownFile of markdownFiles) {
+      let content: string
+      try {
+        content = readFileSync(markdownFile, "utf8")
+      } catch {
+        continue
+      }
+
+      const frontmatter = parseFrontmatter(content)
+      if (frontmatter) {
+        const validation = validateSkillFrontmatter(frontmatter)
+        if (!validation.success) {
+          logger.warn(`Skipping skill with invalid frontmatter: ${markdownFile} — ${validation.errors.join(", ")}`)
+          continue
+        }
+      }
+
+      const parsedName = parseSkillNameFromFrontmatter(content)
+      const rawName = parsedName || inferSkillNameFromPath(markdownFile)
+      const normalizedName = normalizeSkillName(rawName)
+      if (!normalizedName) continue
+      if (resolved.has(normalizedName)) continue
+
+      const skill: ResolvedSkill = {
+        name: normalizedName,
+        description: parseSkillDescriptionFromFrontmatter(content),
+        filePath: markdownFile,
+        source: root.source,
+        content,
+      }
+
+      if (frontmatter) {
+        if (typeof frontmatter.source_url === "string") skill.source_url = frontmatter.source_url
+        if (typeof frontmatter.source_license === "string") skill.source_license = frontmatter.source_license
+        if (typeof frontmatter.imported_at === "string") skill.imported_at = frontmatter.imported_at
+        if (typeof frontmatter.source_hash === "string") skill.source_hash = frontmatter.source_hash
+      }
+
+      resolved.set(normalizedName, skill)
+    }
+  }
+
+  return resolved
+}
+
+export function getRequiredAuditSkills(): string[] {
+  return ["reentrancy", "oracle-manipulation", "amm-dex"]
+}

package/src/skills/skill-schema.ts

@@ -0,0 +1,98 @@
+import { z } from "zod"
+import { parse as parseYaml } from "yaml"
+
+export const DetectionRuleSchema = z.object({
+  regex: z.string(),
+  severity: z.enum(["Critical", "High", "Medium", "Low", "Informational"]),
+  confidence: z.enum(["High", "Medium", "Low"]).optional(),
+  swc: z.string().optional(),
+  description: z.string().optional(),
+})
+
+export const SkillFrontmatterSchema = z.object({
+  name: z
+    .string()
+    .min(1, "Skill name is required")
+    .max(128, "Skill name must be 128 characters or fewer")
+    .regex(/^[a-z0-9-]+$/, "Must be lowercase slug format (a-z, 0-9, hyphens only)"),
+  description: z.string().max(1024).default(""),
+  version: z
+    .string()
+    .regex(/^\d+\.\d+(\.\d+)?$/, "Must be semver format (e.g. 1.0.0)")
+    .optional(),
+  deprecated: z.boolean().optional(),
+  replacement: z.string().optional(),
+  category: z
+    .enum([
+      "vulnerability-pattern",
+      "methodology",
+      "protocol-pattern",
+      "checklist",
+      "reference",
+    ])
+    .optional(),
+  source_url: z.string().url().optional(),
+  source_license: z.string().optional(),
+  imported_at: z.string().optional(),
+  source_hash: z.string().optional(),
+  detection_rules: z.array(DetectionRuleSchema).optional(),
+})
+
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>
+
+export function validateSkillFrontmatter(
+  frontmatter: Record<string, unknown>,
+): { success: true; data: SkillFrontmatter } | { success: false; errors: string[] } {
+  const result = SkillFrontmatterSchema.safeParse(frontmatter)
+  if (result.success) {
+    return { success: true, data: result.data }
+  }
+  return {
+    success: false,
+    errors: result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "root"
+      return `${path}: ${issue.message}`
+    }),
+  }
+}
+
+export function parseFrontmatter(content: string): Record<string, unknown> | null {
+  const fenceMatch = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---/)
+  if (!fenceMatch?.[1]) return null
+
+  const raw = fenceMatch[1]
+
+  if (raw.includes("detection_rules:")) {
+    try {
+      const parsed = parseYaml(raw)
+      if (typeof parsed === "object" && parsed !== null) {
+        return parsed as Record<string, unknown>
+      }
+    } catch {}
+  }
+
+  const lines = raw.split(/\r?\n/)
+  const result: Record<string, unknown> = {}
+
+  for (const line of lines) {
+    const kvMatch = line.match(/^([\w][\w-]*):\s*(.*)$/)
+    if (!kvMatch) continue
+
+    const key = kvMatch[1]!
+    let raw = kvMatch[2]?.trim() ?? ""
+
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      raw = raw.slice(1, -1)
+    }
+
+    if (raw === "true") {
+      result[key] = true
+    } else if (raw === "false") {
+      result[key] = false
+    } else {
+      result[key] = raw
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}

package/src/state/audit-state.ts

@@ -19,6 +19,8 @@ export function createAuditState(projectDir: string): {
     currentPhase: "reconnaissance",
     scope: [],
     startTime: Date.now(),
+    soloditResults: [],
+    fuzzCounterexamples: [],
   };
 
   const store = createFindingStore(state);

package/src/state/types.ts

@@ -9,9 +9,35 @@ export interface Finding {
   description: string;
   file: string; // relative file path
   lines: [number, number]; // [start, end]
-  source: "slither" | "manual" | "pattern" | "scvd";
+  source: "slither" | "manual" | "pattern" | "scvd" | "solodit" | "fuzz";
   remediation?: string;
   exploitReference?: string;
+  provenance?: {
+    timestamp: number;
+    toolVersion?: string;
+    phase?: AuditPhase;
+  };
+}
+
+export interface SoloditResult {
+  query: string;
+  timestamp: number;
+  resultCount: number;
+  topResults: Array<{
+    title: string;
+    severity: string;
+    url: string;
+    protocol: string;
+  }>;
+}
+
+export interface FuzzCounterexample {
+  testName: string;
+  inputs: string[];
+  revertReason?: string;
+  runs: number;
+  seed?: number;
+  timestamp: number;
 }
 
 export interface ContractProfile {
@@ -52,6 +78,11 @@ export interface AuditState {
   currentPhase: AuditPhase;
   scope: string[];
   startTime: number;
+  soloditResults?: SoloditResult[];
+  fuzzCounterexamples?: FuzzCounterexample[];
+  patternVersion?: string;
+  skillsLoaded?: string[];
+  unavailableTools?: string[];
 }
 
 export interface PersistentAuditState extends AuditState {

package/src/tools/argus-skill-load-tool.ts

@@ -0,0 +1,73 @@
+import { tool, type ToolContext } from "@opencode-ai/plugin"
+import { loadArgusConfig } from "../config/loader"
+import type { ArgusConfig } from "../config/types"
+import { normalizeSkillName, resolveArgusSkills } from "../skills/argus-skill-resolver"
+
+type ArgusSkillLoadArgs = {
+  name: string
+}
+
+type ArgusSkillLoadDependencies = {
+  loadConfig?: typeof loadArgusConfig
+  resolveSkills?: typeof resolveArgusSkills
+}
+
+export async function executeArgusSkillLoad(
+  args: ArgusSkillLoadArgs,
+  context: ToolContext,
+  deps: ArgusSkillLoadDependencies = {}
+): Promise<string> {
+  const projectDir = context.directory ?? context.worktree ?? process.cwd()
+  const loadConfig = deps.loadConfig ?? loadArgusConfig
+  const resolveSkills = deps.resolveSkills ?? resolveArgusSkills
+
+  let config: ArgusConfig | undefined
+  try {
+    config = loadConfig(projectDir)
+  } catch {
+    config = undefined
+  }
+
+  const normalizedName = normalizeSkillName(args.name)
+  const skills = resolveSkills(projectDir, config)
+  const skill = skills.get(normalizedName)
+
+  if (!skill) {
+    const available = Array.from(skills.keys()).sort().join(", ")
+    throw new Error(
+      `Argus skill "${args.name}" not found (normalized: "${normalizedName}"). Available Argus skills: ${available || "none"}`
+    )
+  }
+
+  const provenanceParts: string[] = []
+  if (skill.source_license) provenanceParts.push(skill.source_license)
+  if (skill.source_url) provenanceParts.push(skill.source_url)
+  if (skill.imported_at) provenanceParts.push(`Imported: ${skill.imported_at}`)
+
+  const provenanceLine = provenanceParts.length > 0 ? `[Provenance: ${provenanceParts.join(" | ")}]` : ""
+
+  return [
+    `## Argus Skill: ${skill.name} [Source: ${skill.source}]`,
+    "",
+    `**Source**: ${skill.source}`,
+    `**Path**: ${skill.filePath}`,
+    skill.description ? `**Description**: ${skill.description}` : "",
+    provenanceLine,
+    "",
+    skill.content,
+  ]
+    .filter(Boolean)
+    .join("\n")
+}
+
+export const argusSkillLoadTool = tool({
+  description: "Load Argus security skill content with OMO-compatible discovery and native fallback.",
+  args: {
+    name: tool.schema
+      .string()
+      .describe("Skill name (e.g., reentrancy, oracle-manipulation, or vulnerability-patterns/reentrancy)."),
+  },
+  async execute(args, context) {
+    return executeArgusSkillLoad(args, context)
+  },
+})

package/src/tools/pattern-checker-tool.ts

@@ -1,6 +1,6 @@
 import os from "node:os";
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { extname, join, resolve } from "node:path";
+import { dirname, extname, join, resolve } from "node:path";
 import { tool, type ToolContext } from "@opencode-ai/plugin";
 import {
   loadIndex,
@@ -8,6 +8,13 @@ import {
   type ScvdIndex,
   type ScvdIndexEntry,
 } from "../knowledge/scvd-index";
+import {
+  extractDetectionRulesFromSkills,
+  loadPatternPacks,
+} from "./pattern-loader";
+import type { PatternDefinition } from "./pattern-schema";
+
+export type PatternSource = "builtin" | "yaml" | "skill";
 
 export interface Match {
   pattern: string;
@@ -16,6 +23,8 @@ export interface Match {
   lines: [number, number];
   description: string;
   exploitReference?: string;
+  patternSource?: PatternSource;
+  category?: string;
 }
 
 export interface MatchSource {
@@ -28,6 +37,7 @@ export interface PatternCheckResult {
   patternsChecked: number;
   executionTime: number;
   target: string;
+  patternVersion?: string;
 }
 
 type PatternCheckArgs = {
@@ -51,8 +61,11 @@ type BuiltinPattern = {
   regex: RegExp;
   description: string;
   exploitReference?: string;
+  source?: PatternSource;
 };
 
+export const PATTERN_PACK_VERSION = "1.0.0";
+
 const BUILTIN_PATTERNS: BuiltinPattern[] = [
   {
     name: "reentrancy",
@@ -113,6 +126,21 @@ function normalizeSeverity(value: string): Match["severity"] {
   return "Informational";
 }
 
+function normalizePatternDefinitions(
+  patterns: PatternDefinition[],
+  source: PatternSource
+): BuiltinPattern[] {
+  return patterns.map((patternDef) => ({
+    name: patternDef.name,
+    category: patternDef.category,
+    severity: patternDef.severity,
+    regex: new RegExp(patternDef.regex),
+    description: patternDef.description,
+    ...(patternDef.exploit_ref ? { exploitReference: patternDef.exploit_ref } : {}),
+    source,
+  }));
+}
+
 function uniqueScvdEntries(entries: ScvdIndexEntry[]): ScvdIndexEntry[] {
   const deduped = new Map<string, ScvdIndexEntry>();
   for (const entry of entries) {
@@ -127,7 +155,7 @@ async function collectScvdMatches(
 ): Promise<Match[]> {
   const detectedCategories = new Set<string>();
   for (const match of matches) {
-    const category = PATTERN_NAME_TO_CATEGORY.get(match.pattern);
+    const category = match.category ?? PATTERN_NAME_TO_CATEGORY.get(match.pattern);
     if (category) {
       detectedCategories.add(category);
     }
@@ -171,7 +199,7 @@ async function collectScvdMatches(
   }));
 }
 
-function collectSolidityFiles(target: string): string[] {
+function collectSolidityFiles(target: string, maxDepth = 8): string[] {
   const absoluteTarget = resolve(target);
   let stats: ReturnType<typeof statSync>;
 
@@ -190,19 +218,19 @@ function collectSolidityFiles(target: string): string[] {
   }
 
   const discovered: string[] = [];
-  const stack = [absoluteTarget];
+  const stack: Array<{ path: string; depth: number }> = [{ path: absoluteTarget, depth: 0 }];
 
   while (stack.length > 0) {
     const current = stack.pop();
-    if (!current) {
+    if (!current || current.depth > maxDepth) {
       continue;
     }
 
-    const entries = readdirSync(current, { withFileTypes: true });
+    const entries = readdirSync(current.path, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = resolve(current, entry.name);
+      const fullPath = resolve(current.path, entry.name);
       if (entry.isDirectory()) {
-        stack.push(fullPath);
+        stack.push({ path: fullPath, depth: current.depth + 1 });
         continue;
       }
 
@@ -252,6 +280,8 @@ function findMatches(file: string, patterns: BuiltinPattern[]): Match[] {
         lines: lineWindow(content, index),
         description: pattern.description,
         exploitReference: pattern.exploitReference,
+        patternSource: pattern.source ?? "builtin",
+        category: pattern.category,
       });
     }
   }
@@ -259,13 +289,16 @@ function findMatches(file: string, patterns: BuiltinPattern[]): Match[] {
   return matches;
 }
 
-function selectPatterns(categories?: string[]): BuiltinPattern[] {
+function selectPatterns(
+  availablePatterns: BuiltinPattern[],
+  categories?: string[]
+): BuiltinPattern[] {
   if (!categories || categories.length === 0) {
-    return BUILTIN_PATTERNS;
+    return availablePatterns;
   }
 
   const set = new Set(categories);
-  return BUILTIN_PATTERNS.filter((pattern) => set.has(pattern.category));
+  return availablePatterns.filter((pattern) => set.has(pattern.category));
 }
 
 export async function executePatternCheck(
@@ -282,7 +315,17 @@ export async function executePatternCheck(
   const startedAt = Date.now();
   context.metadata({ title: `Pattern check: ${args.target}` });
 
-  const selectedPatterns = selectPatterns(args.patterns);
+  const skillsDir = join(dirname(dirname(__dirname)), "skills");
+  const yamlPatterns = loadPatternPacks(join(skillsDir, "patterns"));
+  const skillDetectionRules = extractDetectionRulesFromSkills(skillsDir);
+
+  const allPatterns: BuiltinPattern[] = [
+    ...BUILTIN_PATTERNS.map((pattern) => ({ ...pattern, source: "builtin" as const })),
+    ...normalizePatternDefinitions(yamlPatterns, "yaml"),
+    ...normalizePatternDefinitions(skillDetectionRules, "skill"),
+  ];
+
+  const selectedPatterns = selectPatterns(allPatterns, args.patterns);
   const solidityFiles = collectSolidityFiles(args.target);
   if (solidityFiles.length === 0) {
     throw new Error(`No Solidity files found for target: ${args.target}`);
@@ -320,6 +363,7 @@ export async function executePatternCheck(
     patternsChecked: selectedPatterns.length,
     executionTime: Date.now() - startedAt,
     target: args.target,
+    patternVersion: PATTERN_PACK_VERSION,
   };
 }