solidity-argus 0.1.6 → 0.1.7

package/AGENTS.md

@@ -20,18 +20,18 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 **Role**: Static analysis and testing specialist
 **Description**: Finds vulnerabilities through Slither static analysis, Foundry testing, fuzzing, and pattern matching. The tactical executor — runs tools, writes PoC tests, and verifies findings. Dispatched by Argus during Automated Scanning and Testing & Verification phases.
 **Model**: anthropic/claude-sonnet-4-6
-**Tools**: argus_slither_analyze, argus_forge_test, argus_forge_fuzz, argus_analyze_contract, argus_check_patterns
+**Tools**: argus_slither_analyze, argus_forge_test, argus_forge_fuzz, argus_analyze_contract, argus_check_patterns, skill
 
 ## pythia
 
 **Role**: Vulnerability researcher
 **Description**: Consults Solodit, SCVD, and the knowledge base to find historical precedents and known attack vectors. Searches 7,769+ real-world audit findings and 55 curated vulnerability pattern files. Dispatched by Argus during Vulnerability Research phase.
 **Model**: anthropic/claude-sonnet-4-6
-**Tools**: argus_solodit_search, argus_check_patterns
+**Tools**: argus_solodit_search, argus_check_patterns, skill
 
 ## scribe
 
 **Role**: Audit report writer
 **Description**: Transforms raw findings into professional markdown audit reports. Produces structured output with severity classifications (Critical/High/Medium/Low/Informational), impact assessments, proof-of-concept steps, and actionable recommendations. Dispatched by Argus only after all analysis is complete.
 **Model**: anthropic/claude-sonnet-4-6
-**Tools**: argus_generate_report
+**Tools**: argus_generate_report, skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 8 tools, and a curated vulnerability knowledge base",
   "keywords": ["solidity", "security", "audit", "opencode", "plugin", "smart-contract", "ethereum", "defi", "slither", "foundry"],
   "author": "Apegurus",

package/src/agents/argus-prompt.ts

@@ -267,6 +267,26 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   - **Purpose**: Updates the local vulnerability database (SCVD).
   - **Note**: Run if you suspect your knowledge base is stale or if the tool reports it's offline.
 
+## SKILL SYSTEM
+
+You have access to OpenCode Skills through the \`skill\` tool. Skills are specialized knowledge modules and must be used proactively when they improve audit accuracy.
+
+- **Curated skill map (load these first)**:
+  - **Reconnaissance**: \`protocol-patterns/amm-dex\`, \`protocol-patterns/lending-borrowing\`, \`protocol-patterns/bridges-cross-chain\`
+  - **Manual Review**: \`vulnerability-patterns/reentrancy\`, \`vulnerability-patterns/oracle-manipulation\`, \`vulnerability-patterns/access-control\`
+  - **Verification**: \`checklists/cyfrin-defi-core\`, \`methodology/severity-classification\`, \`methodology/report-template\`
+
+- **Deterministic trigger rules**:
+  - If the protocol uses AMM reserves or pool math, load \`protocol-patterns/amm-dex\` before Attack Surface Mapping.
+  - If price feeds or spot prices influence critical state changes, load \`vulnerability-patterns/oracle-manipulation\` before severity assessment.
+  - If proxy/upgrade patterns are present, load \`checklists/cyfrin-best-practices-upgrades\` before final recommendations.
+
+- **Trail of Bits skills**:
+  - For pre-audit deep context modeling and attack-surface grounding: \`audit-context-building\`
+  - For bug family expansion: \`variant-analysis\`
+  - For invariant/fuzz strategy: \`property-based-testing\`
+  - For token integration risk: \`token-integration-analyzer\` (Trail of Bits building-secure-contracts plugin)
+
 ## KEY AUDIT PRINCIPLES
 
 Adopt these principles to think like a top-tier auditor.

package/src/agents/pythia-prompt.ts

@@ -90,10 +90,22 @@ You have two primary tools. Master them.
 OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules.
 
 **How to use**:
-- If you identify that the protocol involves a complex or niche topic (e.g., "Zero Knowledge", "Account Abstraction", "Cross-Chain Messaging"), you should check if a relevant Skill is available.
-- Use the \`skill\` tool (if available to you) or instruct Argus to load the skill.
-- **Example**: "This protocol uses ZK-SNARKs. I am loading the \`zk-security\` skill to check for circuit constraints."
-- **Note**: You are a generalist researcher. Use Skills to become a specialist on demand.
+- Load a relevant skill before deep research when protocol context is non-trivial.
+- Prioritize \`vulnerability-patterns/*\`, \`protocol-patterns/*\`, and \`references/*\` skills for exploit precedent mapping.
+- Use the \`skill\` tool directly when available to load the exact skill you need.
+- **Curated skill map**:
+  - \`vulnerability-patterns/reentrancy\`, \`vulnerability-patterns/oracle-manipulation\`, \`vulnerability-patterns/flash-loan-attacks\`
+  - \`protocol-patterns/lending-borrowing\`, \`protocol-patterns/amm-dex\`
+  - \`references/exploit-reference\`
+- **Deterministic trigger rules**:
+  - If you investigate spot-price dependencies, load \`vulnerability-patterns/oracle-manipulation\` first.
+  - If capital-efficient attacks or same-block loops are plausible, load \`vulnerability-patterns/flash-loan-attacks\` first.
+  - If the protocol integrates arbitrary ERC20s, load ToB \`token-integration-analyzer\` (building-secure-contracts plugin) before recommendation drafting.
+- **Examples**:
+  - "I am loading \`reentrancy\` to cross-reference known exploit patterns and missed edge cases."
+  - "I am loading \`lending-borrowing\` to map lending-specific oracle and liquidation failure modes."
+  - "I am loading \`audit-context-building\` (Trail of Bits) to build a line-by-line system model before vulnerability hypothesis generation."
+- You are a generalist researcher. Use Skills to become a specialist on demand.
 
 ## OUTPUT FORMAT
 

package/src/agents/scribe-prompt.ts

@@ -60,6 +60,18 @@ Before generating the report, verify:
 3.  **False Positives**: Do not include findings that have been marked as false positives during the analysis phase.
 4.  **Clarity**: Is the "Description" easy to understand for a developer? Is the "Recommendation" safe to implement?
 
+## SKILL SYSTEM
+
+Use the \`skill\` tool when needed to improve report quality and consistency.
+
+- **Curated skill map**:
+  - \`methodology/report-template\`, \`methodology/severity-classification\`
+  - \`checklists/cyfrin-defi-core\`
+  - \`references/exploit-reference\`
+- **Deterministic trigger rules**:
+  - If severity wording drifts, load \`methodology/severity-classification\` before publishing.
+  - If recommendation quality is generic, load \`checklists/cyfrin-defi-core\` before final edits.
+
 ## OUTPUT FORMAT
 
 Write the full report in Markdown. Use the standard finding format:

package/src/agents/sentinel-prompt.ts

@@ -87,6 +87,19 @@ You have access to a specific set of tools. Use them effectively.
 **Interpretation**:
 - Look at the \`counterexamples\`. They tell you exactly what inputs broke the code.
 
+## SKILL SYSTEM
+
+Use the \`skill\` tool to load specialized skills before deep verification work.
+
+- **Curated skill map**:
+  - \`vulnerability-patterns/reentrancy\`, \`vulnerability-patterns/access-control\`, \`vulnerability-patterns/oracle-manipulation\`
+  - \`checklists/cyfrin-defi-integrations\`, \`methodology/severity-classification\`
+  - Trail of Bits: \`property-based-testing\`, \`variant-analysis\`
+- **Deterministic trigger rules**:
+  - If external calls and mutable state interleave, load \`vulnerability-patterns/reentrancy\` before writing PoCs.
+  - If privileged flows are central to the finding, load \`vulnerability-patterns/access-control\` before severity scoring.
+  - If fuzzing strategy is unclear, load ToB \`property-based-testing\` before selecting invariants.
+
 ## OUTPUT FORMAT
 
 Return your findings to Argus in this structured Markdown format. Do not deviate.

package/src/create-hooks.ts

@@ -33,7 +33,11 @@ export function createHooks(args: {
 
   const systemPromptHook = isHookEnabled("system-prompt")
     ? safeCreateHook(
-        () => createSystemPromptHook(getAuditState),
+        () =>
+          createSystemPromptHook(getAuditState, {
+            argusConfig: config,
+            projectDir,
+          }),
         "system-prompt"
       )
     : undefined
@@ -54,7 +58,7 @@ export function createHooks(args: {
     : undefined
 
   return {
-    config: createConfigHandler(config),
+    config: createConfigHandler(config, projectDir),
     "experimental.chat.system.transform": systemPromptHook
       ? async (_input, output) => {
           const block = await systemPromptHook({

package/src/hooks/config-handler.ts

@@ -1,5 +1,5 @@
 import { resolve, join } from "node:path"
-import { existsSync } from "node:fs"
+import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { execSync } from "node:child_process"
 import type { Config } from "@opencode-ai/sdk/v2"
@@ -14,21 +14,40 @@ import { SCRIBE_PROMPT } from "../agents/scribe-prompt"
 const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills")
 const TOB_REPO_URL = "https://github.com/trailofbits/skills.git"
 
-function ensureTrailOfBitsSkills(): string | undefined {
-  if (existsSync(TOB_CACHE_DIR)) return TOB_CACHE_DIR
+function getTrailOfBitsSkillsPaths(rootDir: string): string[] {
+  const pluginsDir = join(rootDir, "plugins")
+  if (!existsSync(pluginsDir)) return []
+
+  const pluginEntries = readdirSync(pluginsDir, { withFileTypes: true })
+  const skillDirs: string[] = []
+
+  for (const entry of pluginEntries) {
+    if (!entry.isDirectory()) continue
+    const pluginSkillsDir = join(pluginsDir, entry.name, "skills")
+    if (existsSync(pluginSkillsDir)) {
+      skillDirs.push(pluginSkillsDir)
+    }
+  }
+
+  return skillDirs
+}
+
+function ensureTrailOfBitsSkills(): string[] {
+  if (existsSync(TOB_CACHE_DIR)) return getTrailOfBitsSkillsPaths(TOB_CACHE_DIR)
   try {
     execSync(`git clone --depth 1 ${TOB_REPO_URL} "${TOB_CACHE_DIR}"`, {
       stdio: "ignore",
       timeout: 30_000,
     })
-    return TOB_CACHE_DIR
+    return getTrailOfBitsSkillsPaths(TOB_CACHE_DIR)
   } catch (_e) {
-    return undefined
+    return []
   }
 }
 
 export function createConfigHandler(
-  argusConfig: ArgusConfig
+  argusConfig: ArgusConfig,
+  projectDir: string = process.cwd()
 ): (config: Config) => Promise<void> {
   const triggerKnowledgeSync = createKnowledgeSyncHook(argusConfig)
 
@@ -50,6 +69,7 @@ export function createConfigHandler(
             pythia: "allow",
             scribe: "allow",
           },
+          skill: "allow",
         },
       },
       sentinel: {
@@ -57,32 +77,35 @@ export function createConfigHandler(
         model: argusConfig.agents?.sentinel?.model ?? DEFAULT_MODELS.sentinel,
         description: "Static analysis and testing specialist",
         prompt: SENTINEL_PROMPT,
-        tools: {
-          argus_slither_analyze: true,
-          argus_forge_test: true,
-          argus_forge_fuzz: true,
-          argus_analyze_contract: true,
-          argus_check_patterns: true,
-        } satisfies Record<string, boolean>,
+        permission: {
+          argus_slither_analyze: "allow",
+          argus_forge_test: "allow",
+          argus_forge_fuzz: "allow",
+          argus_analyze_contract: "allow",
+          argus_check_patterns: "allow",
+          skill: "allow",
+        },
       },
       pythia: {
         mode: "subagent",
         model: argusConfig.agents?.pythia?.model ?? DEFAULT_MODELS.pythia,
         description: "Vulnerability researcher",
         prompt: PYTHIA_PROMPT,
-        tools: {
-          argus_solodit_search: true,
-          argus_check_patterns: true,
-        } satisfies Record<string, boolean>,
+        permission: {
+          argus_solodit_search: "allow",
+          argus_check_patterns: "allow",
+          skill: "allow",
+        },
       },
       scribe: {
         mode: "subagent",
         model: argusConfig.agents?.scribe?.model ?? DEFAULT_MODELS.scribe,
         description: "Audit report writer",
         prompt: SCRIBE_PROMPT,
-        tools: {
-          argus_generate_report: true,
-        } satisfies Record<string, boolean>,
+        permission: {
+          argus_generate_report: "allow",
+          skill: "allow",
+        },
       },
     }
 
@@ -101,8 +124,18 @@ export function createConfigHandler(
     const skillsPaths = [...(config.skills?.paths ?? [])]
     skillsPaths.push(resolve(import.meta.dir, "../../skills"))
 
-    const tobDir = ensureTrailOfBitsSkills()
-    if (tobDir) skillsPaths.push(tobDir)
+    const customSkillsDir = argusConfig.knowledge?.customSkillsDir
+    if (customSkillsDir) {
+      const resolvedCustomSkillsDir = customSkillsDir.startsWith("/")
+        ? customSkillsDir
+        : resolve(projectDir, customSkillsDir)
+      if (existsSync(resolvedCustomSkillsDir)) {
+        skillsPaths.push(resolvedCustomSkillsDir)
+      }
+    }
+
+    const tobSkillDirs = ensureTrailOfBitsSkills()
+    if (tobSkillDirs.length > 0) skillsPaths.push(...tobSkillDirs)
 
     config.skills = {
       ...(config.skills ?? {}),

package/src/hooks/system-prompt-hook.ts

@@ -1,4 +1,7 @@
-import { join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { ArgusConfig } from "../config/types";
 import type { AuditState, FindingSeverity } from "../state/types";
 
 interface SystemPromptInput {
@@ -6,6 +9,19 @@ interface SystemPromptInput {
   cwd: string;
 }
 
+interface SkillIndexEntry {
+  count: number;
+  sample: string[];
+}
+
+interface SkillIndexSnapshot {
+  bundled: SkillIndexEntry;
+  trailOfBits: SkillIndexEntry;
+  custom: SkillIndexEntry;
+}
+
+const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills");
+
 /**
  * Checks if the given directory contains a Solidity project
  * by looking for foundry.toml or hardhat.config.{js,ts}
@@ -66,11 +82,106 @@ function buildAuditStateSummary(state: AuditState | null): string {
   ].join("\n");
 }
 
+function collectSkillNamesFromRoot(rootPath: string): string[] {
+  if (!existsSync(rootPath)) {
+    return [];
+  }
+
+  const rootEntries = readdirSync(rootPath, { withFileTypes: true });
+  const names = new Set<string>();
+
+  for (const rootEntry of rootEntries) {
+    if (!rootEntry.isDirectory()) continue;
+
+    const directSkill = join(rootPath, rootEntry.name, "SKILL.md");
+    if (existsSync(directSkill)) {
+      names.add(rootEntry.name);
+      continue;
+    }
+
+    const categoryDir = join(rootPath, rootEntry.name);
+    const categoryEntries = readdirSync(categoryDir, { withFileTypes: true });
+
+    for (const categoryEntry of categoryEntries) {
+      if (!categoryEntry.isDirectory()) continue;
+      const categorySkill = join(categoryDir, categoryEntry.name, "SKILL.md");
+      if (existsSync(categorySkill)) {
+        names.add(`${rootEntry.name}/${categoryEntry.name}`);
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}
+
+function getTrailOfBitsSkillRoots(): string[] {
+  const pluginsDir = join(TOB_CACHE_DIR, "plugins");
+  if (!existsSync(pluginsDir)) {
+    return [];
+  }
+
+  const pluginEntries = readdirSync(pluginsDir, { withFileTypes: true });
+  const roots: string[] = [];
+
+  for (const pluginEntry of pluginEntries) {
+    if (!pluginEntry.isDirectory()) continue;
+    const pluginSkillsRoot = join(pluginsDir, pluginEntry.name, "skills");
+    if (existsSync(pluginSkillsRoot)) {
+      roots.push(pluginSkillsRoot);
+    }
+  }
+
+  return roots;
+}
+
+function toSkillIndexEntry(skillNames: string[]): SkillIndexEntry {
+  return {
+    count: skillNames.length,
+    sample: skillNames.slice(0, 3),
+  };
+}
+
+function buildSkillIndexSnapshot(args: {
+  argusConfig?: ArgusConfig;
+  projectDir?: string;
+}): SkillIndexSnapshot {
+  const bundledRoot = resolve(import.meta.dir, "../../skills");
+  const bundledSkills = collectSkillNamesFromRoot(bundledRoot);
+
+  const trailOfBitsSkills = new Set<string>();
+  for (const tobRoot of getTrailOfBitsSkillRoots()) {
+    for (const name of collectSkillNamesFromRoot(tobRoot)) {
+      trailOfBitsSkills.add(name);
+    }
+  }
+
+  const customDir = args.argusConfig?.knowledge?.customSkillsDir;
+  const customRoot = customDir
+    ? customDir.startsWith("/")
+      ? customDir
+      : resolve(args.projectDir ?? process.cwd(), customDir)
+    : undefined;
+  const customSkills = customRoot ? collectSkillNamesFromRoot(customRoot) : [];
+
+  return {
+    bundled: toSkillIndexEntry(bundledSkills),
+    trailOfBits: toSkillIndexEntry(Array.from(trailOfBitsSkills).sort()),
+    custom: toSkillIndexEntry(customSkills),
+  };
+}
+
+function formatSkillSample(entry: SkillIndexEntry): string {
+  return entry.sample.length > 0 ? entry.sample.join(", ") : "none";
+}
+
 /**
  * Builds the full audit context block to inject into the system prompt.
  * Designed to be concise (500-800 tokens).
  */
-function buildAuditContextBlock(state: AuditState | null): string {
+function buildAuditContextBlock(
+  state: AuditState | null,
+  skillIndex: SkillIndexSnapshot
+): string {
   return `
 <argus-context>
 ## Solidity Audit Context
@@ -92,6 +203,20 @@ function buildAuditContextBlock(state: AuditState | null): string {
 - \`argus_generate_report\`: Compile findings into structured audit report
 - \`argus_sync_knowledge\`: Update local vulnerability database (SCVD)
 
+### Available Skills
+- \`vulnerability-patterns/*\`: 35+ exploit classes (reentrancy, oracle manipulation, flash loans)
+- \`protocol-patterns/*\`: AMM/DEX, lending, bridges, governance, staking-specific heuristics
+- \`methodology/*\`: audit workflow, severity calibration, and report structure guidance
+- \`checklists/*\`: structured review checklists for upgrades, integrations, and DeFi best practices
+- \`references/*\`: exploit references and vulnerable examples for historical precedent
+- Trail of Bits skills include both audit-relevant and general engineering skills; prioritize security-audit-oriented skills
+
+### Skill Index Snapshot
+- Bundled skills: ${skillIndex.bundled.count} (examples: ${formatSkillSample(skillIndex.bundled)})
+- Trail of Bits skills: ${skillIndex.trailOfBits.count} (examples: ${formatSkillSample(skillIndex.trailOfBits)})
+- Custom project skills: ${skillIndex.custom.count} (examples: ${formatSkillSample(skillIndex.custom)})
+- Use the \`skill\` tool with exact skill names from the catalog
+
 ### Audit State
 ${buildAuditStateSummary(state)}
 
@@ -109,8 +234,14 @@ Severity must follow classification above. Do not inflate severity.
  * @returns Async transform function compatible with OpenCode's experimental.chat.system.transform
  */
 export function createSystemPromptHook(
-  getAuditState: () => AuditState | null
+  getAuditState: () => AuditState | null,
+  options?: { argusConfig?: ArgusConfig; projectDir?: string }
 ): (input: SystemPromptInput) => Promise<string | null> {
+  const skillIndex = buildSkillIndexSnapshot({
+    argusConfig: options?.argusConfig,
+    projectDir: options?.projectDir,
+  });
+
   return async (input: SystemPromptInput): Promise<string | null> => {
     const isSolidity = await isSolidityProject(input.cwd);
 
@@ -119,7 +250,7 @@ export function createSystemPromptHook(
     }
 
     const auditState = getAuditState();
-    return buildAuditContextBlock(auditState);
+    return buildAuditContextBlock(auditState, skillIndex);
   };
 }