Skip to content

README.md

Latest commit

 

History

History
137 lines (99 loc) · 2.9 KB

README.md

File metadata and controls

137 lines (99 loc) · 2.9 KB

ISNAD Scanner

中文文档

Detection oracle for the ISNAD trust protocol. Scans AI resources (skills, prompts, configs) for malicious patterns and submits flags to the on-chain oracle.

Installation

cd scanner
npm install
npm run build

Usage

Scan a file

# Basic scan
npm run scan -- scan ./path/to/skill.js

# Output as JSON
npm run scan -- scan ./path/to/skill.js --json

# With custom resource hash
npm run scan -- scan ./path/to/skill.js --hash 0x123...

Scan multiple files

# Scan all JS files in a directory
npm run scan -- batch "./skills/**/*.js"

# Fail fast on first high-risk finding
npm run scan -- batch "./skills/**/*.js" --fail-fast

Generate evidence

npm run scan -- evidence ./malicious-skill.js

Submit flag to oracle

# Dry run (analyze but don't submit)
npm run scan -- flag ./malicious-skill.js --dry-run

# Submit to testnet
npm run scan -- flag ./malicious-skill.js --network testnet

# Submit to mainnet
npm run scan -- flag ./malicious-skill.js --network mainnet

Run as service

# Set environment variables
export ISNAD_PRIVATE_KEY=0x...
export ISNAD_AUTO_FLAG=false  # Set true for automatic flagging

# Start service
npm start

Environment Variables

Variable Description Default
ISNAD_PRIVATE_KEY Private key for flag submissions Required
ISNAD_REGISTRY_ADDRESS Registry contract address Sepolia default
ISNAD_ORACLE_ADDRESS Oracle contract address Sepolia default
ISNAD_NETWORK testnet or mainnet testnet
ISNAD_AUTO_FLAG Auto-submit flags false
ISNAD_MIN_CONFIDENCE Min confidence for auto-flag 0.7

Detection Patterns

The scanner detects:

Critical

  • Dynamic code execution (eval, Function)
  • Shell command execution (exec, spawn)
  • Child process imports
  • VM module usage
  • Keychain/credential store access
  • System directory writes

High

  • Data exfiltration (webhooks, base64 sends)
  • Sensitive file reads (.env, .ssh, credentials)
  • Raw socket access
  • DNS-based exfiltration
  • Security bypass attempts
  • Cryptocurrency mining

Medium

  • Environment variable access
  • Recursive directory reads
  • Home directory access
  • Obfuscation patterns

Low

  • Unicode escape sequences
  • Minor suspicious patterns

API

import { analyzeContent, formatResult } from '@isnad/scanner';

const result = analyzeContent(code, resourceHash);
console.log(formatResult(result));

// Result includes:
// - riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'clean'
// - riskScore: number
// - confidence: 0-1
// - findings: detailed pattern matches

Contract Addresses

Base Sepolia (Testnet)

  • Registry: 0x8340783A495BB4E5f2DF28eD3D3ABcD254aA1C93
  • Oracle: 0x4f1968413640bA2087Db65d4c37912d7CD598982

Base Mainnet

  • Coming soon

License

MIT