muhammadtalhaofficial/ForensIQ-AI
GitHub: muhammadtalhaofficial/ForensIQ-AI
基于 AI 与启发式分析的 Solana 区块链取证平台，能对任意钱包地址生成风险评分、威胁检测报告，并将报告哈希永久锚定上链以确保不可篡改。
Stars: 1 | Forks: 0
# ForensIQ — AI 驱动的区块链取证调查员
## 这是什么？
ForensIQ 是一个基于 Solana 构建的全栈区块链取证平台。您只需粘贴一个钱包地址，系统就会：
1. 通过 Helius API 从 Solana 区块链提取钱包的完整交易历史
2. 对交易数据运行 13 种取证启发式算法（如 rug pull、混合器、闪电贷攻击、资金抽水器等）
3. 使用语义向量搜索检索包含过往取证案例的 RAG 知识库
4. 将所有信息输入到 LLM（Groq / Llama 3.3 70B）中，以生成结构化的调查报告
5. 将报告的 SHA-256 哈希值作为 Solana 备忘录交易锚定——永久且不可篡改地记录在链上
6. 在带有风险评分、置信度仪表和模式网格的聊天式 UI 中展示报告
此外，还有一个高性能的 Rust 二进制文件（`rust/forensiq-engine`），它可以作为独立的 CLI 工具，通过 Rayon 进行并行处理，运行相同的取证流水线。
## 架构概览
```
User Input (wallet address)
│
▼
Helius API (Solana RPC)
→ fetch transaction history
│
▼
Forensic Heuristics Engine
→ 13 detection categories
→ risk scoring
│
├──────────────────────────────────────┐
▼ ▼
RAG Pipeline Groq LLM (Llama 3.3 70B)
→ embed query (OpenAI) → structured JSON report
→ semantic search (pgvector) → risk level + confidence
→ retrieve matching case docs → markdown full report
│ │
└──────────────┬───────────────────────┘
▼
On-chain Report Anchoring
→ Solana Memo Program
→ tamper-proof hash stored on-chain
│
▼
React UI (TanStack)
→ ChatInterface
→ ConfidenceMeter
→ ThreatPatternGrid
→ MetadataPanel
```
## 技术栈
### 前端
| 层级 | 技术 |
|---|---|
| 框架 | React 19 + TypeScript |
| 路由 | TanStack Router (基于文件) |
| 数据获取 | TanStack Query |
| 样式 | Tailwind CSS v4 + shadcn/ui |
| UI 基础组件 | Radix UI |
| 动画 | Framer Motion |
| 图表 | Recharts |
| 构建工具 | Vite 7 |
| 部署 | Cloudflare Workers |
### 后端 / AI
| 层级 | 技术 |
|---|---|
| 服务器运行时 | TanStack Start (SSR) |
| LLM | Groq — Llama 3.3 70B Versatile |
| 嵌入 | OpenAI `text-embedding-3-small` |
| 向量数据库 | Supabase + pgvector |
| 区块链数据 | Helius Enhanced RPC |
| 链上锚定 | Solana Memo Program |
| 语音输出 | ElevenLabs TTS |
| 本地模型回退 | @xenova/transformers (HuggingFace) |
### Rust 引擎
| 层级 | 技术 |
|---|---|
| 异步运行时 | Tokio |
| HTTP 客户端 | Reqwest |
| 并行计算 | Rayon |
| 图算法 | Petgraph |
| 哈希计算 | SHA2 |
| 序列化 | Serde + serde_json |
| 日志 | Tracing + tracing-subscriber |
## 项目结构
```
ForensIQ/
├── forensiqai-explorer/ # Main web application
│ ├── src/
│ │ ├── components/
│ │ │ ├── forensiq/ # App-specific UI components
│ │ │ │ ├── ChatInterface.tsx
│ │ │ │ ├── ConfidenceMeter.tsx
│ │ │ │ ├── ThreatPatternGrid.tsx
│ │ │ │ ├── MetadataPanel.tsx
│ │ │ │ ├── IntelligenceFeed.tsx
│ │ │ │ ├── ReportCard.tsx
│ │ │ │ ├── RiskBadge.tsx
│ │ │ │ ├── VoiceButton.tsx
│ │ │ │ └── ...
│ │ │ └── ui/ # shadcn/ui base components
│ │ ├── lib/
│ │ │ ├── forensic/ # TypeScript heuristics engine
│ │ │ │ ├── engine.ts # ForensicEngine class
│ │ │ │ ├── heuristics.ts # 13 detection categories
│ │ │ │ └── types.ts # Shared types
│ │ │ ├── solana/ # Solana blockchain clients
│ │ │ │ ├── analyzer.ts # Main wallet analyzer
│ │ │ │ ├── heliusClient.ts
│ │ │ │ ├── memoStore.ts # On-chain report anchoring
│ │ │ │ ├── knownMixers.ts
│ │ │ │ └── verifier.ts
│ │ │ └── rag/ # RAG pipeline
│ │ │ ├── chunker.ts
│ │ │ ├── ingest.ts
│ │ │ ├── openai.ts
│ │ │ ├── retriever.ts
│ │ │ ├── contextBuilder.ts
│ │ │ └── store.ts
│ │ ├── pages/api/forensiq/ # API endpoints
│ │ │ ├── investigate.ts # Main investigation endpoint
│ │ │ ├── ingest.ts # RAG document ingestion
│ │ │ ├── query.ts # RAG semantic search
│ │ │ └── voice.ts # ElevenLabs TTS
│ │ └── routes/ # Page routes
│ │ ├── index.tsx # Investigate page
│ │ ├── threats.tsx # Threat database
│ │ └── submit.tsx # Submit threat report
│ ├── supabase/
│ │ └── migrations/
│ │ └── 001_init.sql # pgvector schema + indexes
│ ├── scripts/
│ │ ├── ingest-cli.ts # CLI: ingest documents into RAG
│ │ ├── run-migration.ts # CLI: run DB migration
│ │ └── solana-inspect.ts # CLI: inspect Solana wallet
│ └── data/ # Drop forensic case docs here
│
└── rust/
└── forensiq-engine/ # Standalone Rust forensic CLI
├── src/
│ ├── main.rs # CLI entry point
│ ├── analyzer.rs # Full analysis pipeline
│ ├── rpc.rs # Helius HTTP client
│ ├── parser.rs # Transaction parser
│ ├── graph.rs # Petgraph wallet graph
│ ├── heuristics.rs # Signal detection (parallel)
│ ├── types.rs # Shared types
│ └── utils.rs # SHA-256 hashing
└── Cargo.toml
```
## 检测类别
取证引擎在每次调查中会检查 13 种威胁模式：
| 类别 | 检测内容 |
|---|---|
| `rug_pull` | 大规模代币抛售、移除流动性、开发者钱包资金抽离 |
| `flash_loan` | 在同一区块内借贷并偿还 |
| `phishing_drainer` | 钱包资金抽水合约、授权劫持 |
| `mixer_laundering` | 与已知的混合器/滚筒地址交互 |
| `bridge_exploit` | 可疑的跨链桥交互 |
| `oracle_manipulation` | 预言机价格攻击、夹单模式 |
| `wash_trading` | 关联钱包之间的循环转账 |
| `sybil_attack` | 由单一来源资助的大量钱包 |
| `pump_and_dump` | 协调买入施压后进行大规模抛售 |
| `honeypot` | 阻止卖出的合约 |
| `dormant_activation` | 旧钱包突然转移大额资金 |
| `coordinated_draining` | 多个钱包同时进行资金抽离 |
| `validator_compromise` | 验证者密钥滥用模式 |
## 前置条件
- Node.js 18+ 或 Bun
- Rust 1.75+（仅用于 Rust 引擎）
- 启用了 pgvector 的 Supabase 项目
- API 密钥（参见环境变量）
## 快速开始
### 1. 克隆并安装依赖
```
git clone https://github.com/your-username/forensiq.git
cd forensiq/forensiqai-explorer
npm install
```
### 2. 设置环境变量
复制示例文件并填入您的密钥：
```
cp .env.example .env.local
```
然后编辑 `.env.local`（参见下文的环境变量部分）。
### 3. 运行数据库迁移
这将在 Supabase 中创建 `documents` 表和 `pgvector` 索引：
```
npm run rag:migrate
```
### 4. 导入您的取证知识库
将 markdown、PDF 或文本文件放入 `data/` 文件夹中，然后运行：
```
npm run rag:ingest -- ./data
```
您导入的取证案例文档（黑客事后分析、混合器报告、漏洞分析）越多，RAG 驱动的调查效果就越好。
### 5. 启动开发服务器
```
npm run dev
```
打开 `http://localhost:3000` 并粘贴任何 Solana 钱包地址以开始调查。
## 环境变量
在 `forensiqai-explorer/` 中创建一个 `.env.local` 文件，内容如下：
```
# Solana / Helius
HELIUS_API_KEY=your_helius_api_key
SOLANA_NETWORK=mainnet-beta # or devnet for testing
SOLANA_PRIVATE_KEY=your_base58_private_key # used for on-chain report anchoring
# AI / LLM
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=llama-3.3-70b-versatile
GROQ_FALLBACK_MODEL=llama-3.1-8b-instant
OPENAI_API_KEY=your_openai_api_key # for embeddings only
# Supabase (RAG vector store)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
SUPABASE_DB_URL=postgresql://... # direct Postgres connection for migrations
# Voice (可选)
ELEVENLABS_API_KEY=your_elevenlabs_key
ELEVENLABS_VOICE_ID=your_voice_id
# Local model fallback (可选)
HF_API_KEY=your_huggingface_key
FORCE_LOCAL_MOCK=false
```
## Rust 引擎
Rust 二进制文件提供与 TypeScript 层相同的取证分析，但完全在本地运行，无需 LLM——纯粹是基于并行处理的启发式分析。
### 构建
```
cd rust/forensiq-engine
cargo build --release
```
### 运行
```
# Analyze a wallet (输出 JSON 报告到 stdout)
cargo run --release --
# Limit transaction history
cargo run --release -- 500
```
### 环境变量 (Rust)
```
HELIUS_API_KEY=your_helius_key # optional, falls back to public RPC
RPC_URL=https://api.mainnet-beta.solana.com # optional custom RPC
```
Rust 引擎输出一个 JSON 格式的 `ForensicReport`，包括：
- 总转入/转出量
- 交易计数
- 带有风险评分的交易对手分析
- 取证信号（快速抽资、混合器交互、闪电贷攻击等）
- 整体风险评分（0.0 – 1.0）
- 用于完整性校验的 SHA-256 报告哈希值
## API 端点
所有端点均位于 `src/pages/api/forensiq/` 下。
### `POST /api/forensiq/investigate`
对 Solana 钱包运行完整的 AI 取证调查。
**请求：**
```
{
"walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}
```
**响应：**
```
{
"riskLevel": "critical",
"confidence": 91,
"summary": "This wallet shows coordinated draining behavior...",
"fullReport": "# Forensic Report\n## Overview\n...",
"patterns": [
{ "name": "Rapid Drain", "detected": true, "detail": "68% of total volume moved in 24h" },
{ "name": "Mixer Interaction", "detected": true, "detail": "3 transfers to known tumbler" }
],
"relatedAddresses": ["..."],
"txSignature": "...",
"explorerUrl": "https://explorer.solana.com/tx/..."
}
```
### `POST /api/forensiq/ingest`
将文档导入 RAG 知识库。
```
{
"content": "...",
"metadata": { "title": "Ronin Bridge Hack Analysis", "source": "internal" }
}
```
### `POST /api/forensiq/query`
对 RAG 知识库运行语义搜索。
```
{
"query": "wallet draining pattern phishing",
"topK": 8
}
```
### `POST /api/forensiq/voice`
通过 ElevenLabs 将取证报告转换为语音。
```
{
"text": "Wallet assessed as critical risk. Three threat indicators triggered..."
}
```
## 数据库模式
Supabase 迁移文件（`supabase/migrations/001_init.sql`）创建：
```
-- Enable pgvector
create extension if not exists vector;
-- Document store for RAG
create table documents (
id uuid primary key default gen_random_uuid(),
content text not null,
embedding vector(1536), -- OpenAI text-embedding-3-small
metadata jsonb default '{}',
created_at timestamptz default now()
);
-- IVFFlat index for fast ANN search
create index on documents
using ivfflat (embedding vector_cosine_ops)
with (lists = 100);
-- Semantic search function
create function match_documents(
query_embedding vector(1536),
match_threshold float,
match_count int
) returns table (...)
```
## 移除 Lovable 痕迹
如果您是通过 Lovable 搭建的此项目，请运行以下步骤进行清理：
```
# 1. 删除 Lovable 项目文件夹
rm -rf .lovable/
# 2. 替换 vite.config.ts (见下方)
# 3. 从 package.json 中移除 Lovable devDependency
# 删除: "@lovable.dev/vite-tanstack-config": "^1.5.1"
# 4. 重新安装
npm install
```
**将 `vite.config.ts` 替换为：**
```
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { TanStackRouterVite } from "@tanstack/router-plugin/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import tsconfigPaths from "vite-tsconfig-paths";
import { cloudflare } from "@cloudflare/vite-plugin";
export default defineConfig({
plugins: [
tsconfigPaths(),
tailwindcss(),
TanStackRouterVite({ autoCodeSplitting: true }),
tanstackStart({ server: { entry: "server" } }),
react(),
cloudflare(),
],
define: { global: "window" },
optimizeDeps: { include: ["buffer"] },
});
```
## 部署
### Cloudflare Workers（推荐）
```
npm run build
npx wrangler deploy
```
`wrangler.jsonc` 已经配置完毕。请在 Cloudflare 控制台的 Workers → Settings → Variables 中设置您的环境变量。
### 本地生产构建
```
npm run build
npm run preview
```
## 脚本参考
| 命令 | 功能 |
|---|---|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 生产环境构建 |
| `npm run preview` | 在本地预览生产构建 |
| `npm run lint` | ESLint 检查 |
| `npm run format` | Prettier 格式化 |
| `npm run rag:migrate` | 运行 Supabase 数据库迁移 |
| `npm run rag:ingest -- ./data` | 将文档导入 RAG |
| `npm run solana:analyze` | 通过 CLI 检查钱包 |
## 路线图
- [ ] 完善启发式检测逻辑（全部 13 个类别）
- [ ] 使用真实的取证案例文档填充 RAG 知识库
- [ ] 将 Rust 引擎的输出直接连接到 TypeScript API 流水线
- [ ] 交互式交易图谱可视化 (D3/Cytoscape)
- [ ] Ethereum / EVM 链支持
- [ ] 带有历史风险评分的持久化钱包数据库
- [ ] 通过 Solana WebSocket RPC 进行实时钱包监控
- [ ] 跨协同攻击组的钱包集群检测
- [ ] 在标记的区块链攻击数据上微调的取证 LLM
- [ ] 用于合规移交的 PDF/CSV 取证报告导出
## 贡献
1. Fork 本仓库
2. 创建一个功能分支：`git checkout -b feature/my-feature`
3. 提交您的更改：`git commit -m 'add: my feature'`
4. 推送：`git push origin feature/my-feature`
5. 发起 Pull Request
对于启发式算法的贡献，请遵循现有的 `HeuristicFn` 签名，将您的检测逻辑添加到 `src/lib/forensic/heuristics.ts` 中。每个启发式算法应返回一个包含 `triggered`、`confidence`（0-1）和 `evidence` 字符串数组的 `ForensicHeuristicResult`。
## 安全
- 切勿提交 `.env.local` 或任何包含 API 密钥的文件
- `.env.local` 中的 Solana 私钥仅用于签署链上备忘录交易——请使用具有极少 SOL 余额的专用钱包，而不是您的主钱包
- 仓库中的所有 API 密钥（如果有）都应被视为已泄露——请立即轮换它们
- `SUPABASE_SERVICE_ROLE_KEY` 会绕过行级安全策略——请将其保留在服务端，切勿暴露给客户端
## 许可证
MIT — 详情请参见 [LICENSE](LICENSE)。
## 鸣谢
- [Helius](https://helius.dev) — Enhanced Solana RPC 及交易数据
- [Groq](https://groq.com) — 超快 LLM 推理
- [Supabase](https://supabase.com) — Postgres + pgvector
- [Solana](https://solana.com) — Layer 1 区块链
- [TanStack](https://tanstack.com) — Router, Query, Start
- [shadcn/ui](https://ui.shadcn.com) — UI 组件系统
- [ElevenLabs](https://elevenlabs.io) — 语音合成
标签：AI安全, AMSI绕过, Chat Copilot, DeFi安全, DLL 劫持, Helius, Llama 3, OpenAI, pgvector, RAG, Rayon, Rust, Solana生态, Web3安全, 内存规避, 加密货币洗钱检测, 勒索软件分析, 区块链取证, 区块链安全, 反欺诈, 可视化界面, 合规科技, 向量数据库, 大语言模型, 威胁检测, 并行处理, 智能合约审计, 智能风控, 程序员工具, 网络安全, 网络流量审计, 钱包地址分析, 链上分析, 链上追踪, 防篡改报告, 隐私保护, 风险评分