audit-system 2.0.0

package/lib/install.js

@@ -0,0 +1,229 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import { getPackagePath, getProjectPath, getAuditSystemDir, getClaudeDir, copyDir, writeJson } from './utils.js';
+import { detectLanguageSync, formatLanguage } from './detect-lang.js';
+
+const AGENTS_LIST = [
+  'orchestrator',
+  'assumption-analyzer',
+  'economic-attacker',
+  'state-machine-hacker',
+  'composition-attacker',
+  'exploit-writer',
+  'test-generator',
+  'report-writer',
+];
+
+const SKILLS_LIST = [
+  'audit-connect',
+  'auditor',
+  'novel-discovery',
+  'exploit-generator',
+  'test-generator',
+];
+
+export async function install(options = {}) {
+  const projectPath = options.projectPath || getProjectPath();
+  const forceLang = options.lang || null;
+  const auditDir = getAuditSystemDir(projectPath);
+  const claudeDir = getClaudeDir(projectPath);
+  const packagePath = getPackagePath();
+
+  console.log(chalk.blue.bold('\n=== Audit System Installer ===\n'));
+
+  // 1. Detect language
+  let lang = forceLang || detectLanguageSync(projectPath);
+  if (!lang) {
+    console.log(chalk.yellow('⚠  Nenhuma linguagem detectada automaticamente.'));
+    console.log(chalk.yellow('   Use --lang=solidity ou --lang=rust para forçar.\n'));
+  }
+  console.log(chalk.white(`📂 Projeto: ${projectPath}`));
+  console.log(chalk.white(`🌐 Linguagem: ${formatLanguage(lang)}\n`));
+
+  // 2. Create .audit-system directory
+  console.log(chalk.yellow('1. Criando .audit-system/...'));
+  await fs.ensureDir(auditDir);
+
+  // 3. Copy agents
+  console.log(chalk.yellow('2. Copiando agents...'));
+  const agentsDest = path.join(auditDir, 'agents');
+  await copyDir(path.join(packagePath, 'agents'), agentsDest);
+  console.log(chalk.green(`   ✓ ${AGENTS_LIST.length} agents copiados`));
+
+  // 4. Copy skills
+  console.log(chalk.yellow('3. Copiando skills...'));
+  const skillsDest = path.join(auditDir, 'skills');
+  await copyDir(path.join(packagePath, 'skills'), skillsDest);
+  console.log(chalk.green(`   ✓ ${SKILLS_LIST.length} skills copiadas`));
+
+  // 5. Copy vault
+  console.log(chalk.yellow('4. Copiando knowledge base...'));
+  const vaultDest = path.join(auditDir, 'vault');
+  await copyDir(path.join(packagePath, 'obsidian-vault'), vaultDest);
+  console.log(chalk.green('   ✓ Knowledge base copiada'));
+
+  // 6. Copy config
+  console.log(chalk.yellow('5. Copiando configuração...'));
+  const configSrc = path.join(packagePath, 'config.json');
+  const configDest = path.join(auditDir, 'config.json');
+  await fs.copy(configSrc, configDest);
+  console.log(chalk.green('   ✓ Configuração copiada'));
+
+  // 7. Write .env file with paths
+  console.log(chalk.yellow('6. Configurando variáveis...'));
+  const envContent = [
+    `AUDIT_SYSTEM_PATH="${auditDir}"`,
+    `AUDIT_AGENTS_PATH="${path.join(auditDir, 'agents')}"`,
+    `AUDIT_SKILLS_PATH="${path.join(auditDir, 'skills')}"`,
+    `AUDIT_VAULT_PATH="${path.join(auditDir, 'vault')}"`,
+    `AUDIT_LANG="${lang || 'auto'}"`,
+    `AUDIT_OUTPUT_PATH="${path.join(projectPath, 'audit-output')}"`,
+    `AUDIT_MODEL="auto-detect"`,
+    ``,
+  ].join('\n');
+  await fs.writeFile(path.join(auditDir, '.env'), envContent);
+  console.log(chalk.green('   ✓ Variáveis configuradas'));
+
+  // 8. Create .claude/ configuration
+  console.log(chalk.yellow('7. Configurando Claude Code...'));
+  const claudeSkillsDir = path.join(claudeDir, 'skills');
+  await fs.ensureDir(claudeSkillsDir);
+
+  // Copy the main skill to .claude/skills/
+  const mainSkillSrc = path.join(skillsDest, 'audit-connect.md');
+  const mainSkillDest = path.join(claudeSkillsDir, 'audit-connect.md');
+  if (await fs.pathExists(mainSkillSrc)) {
+    await fs.copy(mainSkillSrc, mainSkillDest);
+  }
+
+  // Create settings.json
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const settings = {
+    skills: {
+      'audit-connect': {
+        description: 'Connect audit-system to current project and activate all resources',
+        type: 'prompt',
+        file: 'skills/audit-connect.md',
+      },
+      'audit-agent': {
+        description: 'Execute specific audit agent',
+        type: 'prompt',
+        file: 'skills/audit-connect.md',
+      },
+      'audit-status': {
+        description: 'Show audit-system connection status',
+        type: 'prompt',
+        file: 'skills/audit-connect.md',
+      },
+      'audit-agents': {
+        description: 'List all available audit agents',
+        type: 'prompt',
+        file: 'skills/audit-connect.md',
+      },
+    },
+  };
+  await writeJson(settingsPath, settings);
+  console.log(chalk.green('   ✓ Claude Code configurado'));
+
+  // 9. Summary
+  console.log(chalk.blue.bold('\n=== Instalação Completa! ===\n'));
+  console.log(chalk.white('Resumo:'));
+  console.log(chalk.cyan(`  📁 .audit-system/    → Agents, skills, vault, config`));
+  console.log(chalk.cyan(`  📁 .claude/           → Configuração do Claude Code`));
+  console.log(chalk.cyan(`  🌐 Linguagem         → ${formatLanguage(lang)}`));
+  console.log(chalk.cyan(`  🤖 Agents            → ${AGENTS_LIST.length} especialistas`));
+  console.log(chalk.cyan(`  📝 Skills            → ${SKILLS_LIST.length} prompts`));
+  console.log(chalk.cyan(`  📚 Vault             → Knowledge base completo\n`));
+
+  console.log(chalk.white('Próximo passo:'));
+  console.log(chalk.green('  No Claude Code, digite: /audit-connect\n'));
+
+  return { lang, auditDir, claudeDir };
+}
+
+export async function showStatus(options = {}) {
+  const projectPath = options.projectPath || getProjectPath();
+  const auditDir = getAuditSystemDir(projectPath);
+  const claudeDir = getClaudeDir(projectPath);
+
+  const hasAuditDir = await fs.pathExists(auditDir);
+  const hasClaudeDir = await fs.pathExists(claudeDir);
+  const lang = detectLanguageSync(projectPath);
+
+  console.log(chalk.blue.bold('\n=== Audit System Status ===\n'));
+  console.log(chalk.white(`📂 Projeto: ${projectPath}`));
+  console.log(chalk.white(`🌐 Linguagem: ${formatLanguage(lang)}`));
+  console.log(chalk.white(`📁 .audit-system/: ${hasAuditDir ? chalk.green('✓') : chalk.red('✗')}`));
+  console.log(chalk.white(`📁 .claude/: ${hasClaudeDir ? chalk.green('✓') : chalk.red('✗')}`));
+  console.log();
+
+  if (hasAuditDir && hasClaudeDir) {
+    console.log(chalk.green('✓ Sistema instalado e configurado.'));
+    console.log(chalk.cyan('  Abra o Claude Code e digite /audit-connect\n'));
+  } else {
+    console.log(chalk.yellow('⚠ Sistema não está instalado neste projeto.'));
+    console.log(chalk.cyan('  Execute: npx audit-system connect\n'));
+  }
+}
+
+export async function listAgents() {
+  console.log(chalk.blue.bold('\n=== Audit System Agents ===\n'));
+  const agents = [
+    ['orchestrator', 'Coordinator', 'Coordena workflows multi-agente'],
+    ['assumption-analyzer', 'Specialist', 'Phase 1: Quebra de suposições'],
+    ['economic-attacker', 'Specialist', 'Phase 3: Modelagem econômica'],
+    ['state-machine-hacker', 'Specialist', 'Phase 4: Máquina de estados'],
+    ['composition-attacker', 'Specialist', 'Phase 5: Ataques por composição'],
+    ['exploit-writer', 'Implementer', 'PoCs em Solidity ou Rust/Anchor'],
+    ['test-generator', 'Implementer', 'Testes Foundry ou Anchor'],
+    ['report-writer', 'Documenter', 'Relatórios profissionais'],
+  ];
+  for (const [name, type, desc] of agents) {
+    console.log(chalk.cyan(`  ${name.padEnd(22)} ${type.padEnd(14)} ${desc}`));
+  }
+  console.log(chalk.white('\n  LANG-aware: ajustam análise para Solidity ou Rust.\n'));
+}
+
+export async function doctor(options = {}) {
+  const projectPath = options.projectPath || getProjectPath();
+  const auditDir = getAuditSystemDir(projectPath);
+  let allOk = true;
+
+  console.log(chalk.blue.bold('\n=== Audit System Doctor ===\n'));
+
+  // Check Node version
+  const nodeVer = process.version;
+  const major = parseInt(nodeVer.slice(1).split('.')[0]);
+  const nodeOk = major >= 16;
+  console.log(`${nodeOk ? chalk.green('✓') : chalk.red('✗')} Node.js: ${nodeVer} ${nodeOk ? '' : '(requer >= 16)'}`);
+  if (!nodeOk) allOk = false;
+
+  // Check audit-system directory
+  const hasAudit = await fs.pathExists(auditDir);
+  console.log(`${hasAudit ? chalk.green('✓') : chalk.red('✗')} .audit-system/: ${hasAudit ? 'Encontrado' : 'Não encontrado'}`);
+  if (!hasAudit) allOk = false;
+
+  // Check agents
+  if (hasAudit) {
+    const agentsDir = path.join(auditDir, 'agents');
+    const hasAgents = await fs.pathExists(agentsDir);
+    console.log(`${hasAgents ? chalk.green('✓') : chalk.red('✗')} Agents: ${hasAgents ? 'Presentes' : 'Ausentes'}`);
+    if (!hasAgents) allOk = false;
+  }
+
+  // Check Claude config
+  const hasClaude = await fs.pathExists(getClaudeDir(projectPath));
+  console.log(`${hasClaude ? chalk.green('✓') : chalk.yellow('⚠')} .claude/: ${hasClaude ? 'Configurado' : 'Não configurado (necessário para Claude Code)'}`);
+
+  // Check language
+  const lang = detectLanguageSync(projectPath);
+  console.log(`${lang ? chalk.green('✓') : chalk.yellow('⚠')} Linguagem: ${formatLanguage(lang) || 'Não detectada (use --lang=)'}`);
+
+  console.log();
+  if (allOk) {
+    console.log(chalk.green('✓ Tudo OK! Sistema pronto para uso.\n'));
+  } else {
+    console.log(chalk.yellow('⚠ Alguns problemas encontrados. Execute: npx audit-system connect\n'));
+  }
+}

package/lib/utils.js

@@ -0,0 +1,41 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+export function getPackagePath() {
+  return PACKAGE_ROOT;
+}
+
+export function getProjectPath() {
+  return process.cwd();
+}
+
+export function getAuditSystemDir(projectPath) {
+  return path.join(projectPath, '.audit-system');
+}
+
+export function getClaudeDir(projectPath) {
+  return path.join(projectPath, '.claude');
+}
+
+export async function copyDir(src, dest) {
+  await fs.ensureDir(dest);
+  await fs.copy(src, dest, {
+    filter: (srcPath) => {
+      const basename = path.basename(srcPath);
+      return basename !== 'node_modules';
+    }
+  });
+}
+
+export async function writeJson(filePath, obj) {
+  await fs.writeFile(filePath, JSON.stringify(obj, null, 2) + '\n');
+}
+
+export function resolvePath(...segments) {
+  return path.resolve(...segments);
+}

package/obsidian-vault/README.md

@@ -0,0 +1,103 @@
+# Audit System — Knowledge Base
+
+tags: #index #home
+
+---
+
+## Structure
+
+```
+obsidian-vault/
+├── vulnerabilities/       ← Known vulnerability types with PoC
+├── attack-patterns/     ← Abstract attack patterns
+├── hypotheses/          ← Active attack hypotheses per audit
+├── poc/                 ← Completed proof of concepts
+├── test-strategies/     ← Testing methodologies
+├── reports/             ← Completed audit reports
+├── failed-hypotheses/  ← What didn't work + why
+├── invariant-catalog/   ← DeFi invariants that can be violated
+├── novel-patterns/      ← Novel discovery frameworks
+└── research/            ← Research materials
+    ├── emerging-threats/    ← New attack research
+    ├── protocol-specific/     ← Protocol-specific knowledge
+    └── cross-protocol-analysis/ ← Multi-protocol studies
+```
+
+---
+
+## Vulnerability Index
+
+| Vulnerability | Severity | Notes |
+|---|---|---|
+| [[vulnerabilities/reentrancy]] | CRITICAL | CEI pattern |
+| [[vulnerabilities/access-control]] | CRITICAL/HIGH | Modifiers |
+| [[vulnerabilities/oracle-manipulation]] | CRITICAL | TWAP |
+| [[vulnerabilities/flash-loan-attack]] | CRITICAL | Atomicity |
+
+---
+
+## Attack Patterns
+
+- [[attack-patterns/state-inconsistency]] — Root cause of many bugs
+- [[attack-patterns/privilege-escalation]] — Access control bypass
+- [[attack-patterns/price-manipulation]] — Oracle attacks
+
+---
+
+## Novel Discovery Resources
+
+- [[invariant-catalog/defi-invariants]] — Common invariants to test
+- [[novel-patterns/pattern-mutation-framework]] — Mutate patterns for novel attacks
+- [[failed-hypotheses/_template]] — Learn from failed attempts
+
+---
+
+## Test Strategies
+
+- [[test-strategies/fuzzing]] — Automated random testing
+- [[test-strategies/invariant-testing]] — Property-based testing
+
+---
+
+## Workflow
+
+### Standard Audit
+```
+New Audit
+    ↓
+Create hypothesis in hypotheses/
+    ↓
+Cross-reference vulnerabilities/
+    ↓
+Build PoC in Foundry
+    ↓
+Save result (confirmed → poc/, refuted → failed-hypotheses/)
+    ↓
+Write report entry in reports/
+```
+
+### Novel Discovery Audit
+```
+Standard Audit Pass
+    ↓
+Apply novel discovery (see skills/novel-discovery.md)
+    ↓
+Map assumptions → Break assumptions → Economic model
+    ↓
+State machine analysis → Composition attacks
+    ↓
+Generate novel hypotheses
+    ↓
+Test and document in hypotheses/
+```
+
+---
+
+## Skills Reference
+
+| Skill | Purpose |
+|---|---|
+| [[../skills/auditor]] | Full contract analysis |
+| [[../skills/exploit-generator]] | PoC creation |
+| [[../skills/test-generator]] | Test suite generation |
+| [[../skills/novel-discovery]] | Novel vulnerability discovery |

package/obsidian-vault/attack-patterns/state-inconsistency.md

@@ -0,0 +1,90 @@
+# State Inconsistency Pattern
+
+tags: #pattern #state #reentrancy #critical
+
+---
+
+## Description
+State becomes inconsistent when multiple variables must be updated atomically but aren't. This is the root cause behind reentrancy, cross-function attacks, and many logic bugs.
+
+---
+
+## Hypothesis Framework
+
+```
+Given: Variable A and Variable B must always satisfy: A == f(B)
+
+Attack vector:
+1. Read A (stale value)
+2. External interaction happens
+3. B is updated
+4. A is NOT updated
+5. Invariant A == f(B) broken
+```
+
+---
+
+## Common Manifestations
+
+### Reentrancy Root Cause
+```
+balance[user] → not zeroed before external call
+External call → re-enters → reads stale balance
+Withdraws again using stale balance
+```
+
+### Cross-Function State Bug
+```
+Function A: sets state = PROCESSING
+External call in A
+Function B: checks state == IDLE (stale) and executes
+State becomes inconsistent
+```
+
+### Snapshot Manipulation
+```
+Snapshot taken at block N
+Attacker front-runs to inflate balance
+Snapshot shows inflated balance
+Attacker claims reward/vote based on fake snapshot
+```
+
+---
+
+## Detection Questions
+
+```
+1. Are there multiple state variables that must be updated together?
+2. Is there any external call between reads and writes?
+3. Can state be read between partial updates?
+4. Is there a time gap where state is inconsistent?
+```
+
+---
+
+## Test Strategy
+
+```solidity
+function test_stateConsistency() public {
+    // Record state at point A
+    uint256 stateA = target.variableA();
+    uint256 stateB = target.variableB();
+
+    // Verify invariant holds before
+    assertTrue(checkInvariant(stateA, stateB));
+
+    // Perform operation
+    target.operation();
+
+    // Verify invariant holds after
+    stateA = target.variableA();
+    stateB = target.variableB();
+    assertTrue(checkInvariant(stateA, stateB));
+}
+```
+
+---
+
+## Links
+- [[vulnerabilities/reentrancy]]
+- [[vulnerabilities/access-control]]

package/obsidian-vault/exploits/_index.md

@@ -0,0 +1,109 @@
+# Real-World Exploit Index
+
+This directory contains detailed analyses of real-world smart contract exploits. Use these as reference when auditing similar protocols.
+
+---
+
+## Bridge Exploits
+
+| Exploit | Year | Loss | Vector | Relevance |
+|---------|------|------|--------|-----------|
+| [[ronin-2022]] | 2022 | $625M | Validator compromise | High - Multi-sig bridges |
+| [[wormhole-2022]] | 2022 | $325M | Signature verification | High - All signature-based bridges |
+| [[nomad-2022]] | 2022 | $190M | Replay/Merkle root | Medium - Optimistic verification |
+| [[harmony-2022]] | 2022 | $100M | Multi-sig compromise | High - Multi-sig bridges |
+
+---
+
+## Governance Exploits
+
+| Exploit | Year | Loss | Vector | Relevance |
+|---------|------|------|--------|-----------|
+| [[beanstalk-2022]] | 2022 | $182M | Flash loan governance | High - Token-based governance |
+| [[dao-2016]] | 2016 | $60M | Reentrancy | Medium - Historical reference |
+
+---
+
+## DEX Exploits
+
+| Exploit | Year | Loss | Vector | Relevance |
+|---------|------|------|--------|-----------|
+| [[bancor-2018]] | 2018 | $13.5M | Reentrancy + oracle | Medium - AMM DEXs |
+| [[uni-v1-2021]] | 2021 | Multiple | Price manipulation | High - Spot price reliance |
+
+---
+
+## Lending Exploits
+
+| Exploit | Year | Loss | Vector | Relevance |
+|---------|------|------|--------|-----------|
+| [[cream-2021]] | 2021 | $130M | Flash loan manipulation | High - Lending protocols |
+| [[euler-2023]] | 2023 | $200M | Donation attack | High - Lending protocols |
+
+---
+
+## How to Use This Index
+
+### During Audit Preparation
+1. Identify protocol type (DEX, lending, bridge, governance)
+2. Review relevant exploits
+3. Add exploit patterns to hypothesis generation
+
+### During Hypothesis Generation
+1. For each hypothesis, ask: "Has this happened before?"
+2. If yes, study the exploit details
+3. Adapt the attack vector to current protocol
+
+### During PoC Development
+1. Use exploit code as template
+2. Adapt to current protocol's specifics
+3. Test if same vulnerability exists
+
+---
+
+## Common Patterns Across Exploits
+
+### 1. Signature/Verification Failures
+- [[ronin-2022]] - Validator key compromise
+- [[wormhole-2022]] - Signature not bound to message
+- [[harmony-2022]] - Multi-sig key compromise
+
+**Detection:** Always verify signature binding, key management
+
+### 2. Replay Attacks
+- [[nomad-2022]] - Merkle proof replay
+- Multiple bridges - Cross-chain replay
+
+**Detection:** Nonce tracking, chain ID inclusion
+
+### 3. Governance Capture
+- [[beanstalk-2022]] - Flash loan voting
+- Various - Whale manipulation
+
+**Detection:** Lockup requirements, vote caps
+
+### 4. Oracle Manipulation
+- Multiple exploits - Price feed manipulation
+
+**Detection:** TWAP, multiple sources, sanity checks
+
+---
+
+## Hypothesis Templates by Exploit Type
+
+Use these when starting an audit:
+
+```
+Given [PROTOCOL TYPE], could [EXPLOIT TYPE] from [[EXPLOIT NAME]] happen here?
+
+Example:
+Given this lending protocol, could flash loan manipulation
+from [[cream-2021]] happen here?
+```
+
+---
+
+## Related Resources
+- [[../hypotheses/]] - Protocol-specific hypothesis templates
+- [[../vulnerabilities/]] - Vulnerability pattern documentation
+- [[../attack-patterns/]] - Attack pattern catalog