apu-saha-990/Project-5-Neural-Trace

# Neural-Trace v2 一个用于追踪资金来源、监控钱包可疑活动并生成专业调查报告的区块链取证工具。 ## 解决的问题 当发生加密货币诈骗时，被盗资金不会停留在一个地方。它会移动——有时经过几十个钱包，有时跨多个交易所，有时通过旨在隐藏踪迹的服务。调查人员手动追踪这些资金需要逐个点击数百个钱包页面，记录信息并手动拼凑画面。而等到他们完成时，资金已经再次移动。本工具自动化了这一过程：你粘贴一个钱包地址，它会自动追踪——构建一张资金接触过的每个钱包的完整地图，标注金额流动情况以及最终去向。 ## 实际应用 本工具是在一起涉及加密货币预售诈骗的活跃调查过程中构建的。调查确认了超过125个与诈骗相关的钱包，追踪了超过3.76亿美元的资金，并识别了主要受监管交易所的存款账户。本工具生成的调查报告已准备提交给法律顾问，用于一起RICO案件。目标是提供能够支持向交易所发出传票的证据——迫使它们揭示被盗资金最终流入的账户持有人身份。 本工具生成的报告包含结构化数据——钱包表格、交易记录、异常警报和交易所识别信息。书面叙述层目前位于工具之外：导出的JSON数据被输入到公共AI中，AI读取完整数据集并生成英文调查摘要。该摘要随后被整合成最终提交给法律顾问的文档。构建一个专门针对区块链取证和金融犯罪模式训练的自定义AI，能够自动在导出过程中生成叙述——这是本项目下一阶段的主要目标。 ## 工作原理 1. 你在浏览器中打开工具——它会要求输入用户名和密码以允许访问 2. 你粘贴要调查的钱包地址并为案件指定项目名称 3. 工具向外追踪资金——检查每个目标钱包，然后递归检查这些钱包，最多深入7层 4. 每个钱包都会被自动分类：受害者收款点、通道钱包、交易所账户、混币器等 5. 当追踪运行时，屏幕上的实时地图会自动绘制——你可以看到资金流动实时发生 6. 追踪完成后，点击导出即可获得两个文件：一个结构化数据文件和一个格式化的Word文档，可直接交给律师 7. 然后你可以切换到监控标签页，监视同一批钱包的新活动——大额转账、异常模式、休眠超过90天后突然激活的钱包，以及共享Gas资助者（表明钱包由同一操作者控制） 8. 源头追踪标签页反向工作——对每个钱包，它会找出资金最初来自哪里，包括哪个交易所发送以及该交易所是否要求身份验证 9. 每次启动工具前，都会运行38项自动化检查，以确认系统正常工作 ## 已实现的功能 **调查仪表板**——一个单页Web界面，所有操作都在浏览器中完成。与本地服务器通信，实时网络图会在钱包被发现时显示。设计成真正的情报工具风格，而非电子表格。 **正向追踪器**——从种子钱包向外追踪资金。每跳获取交易历史，识别钱包类型，并构建图谱。当遇到已知交易所、混币器或达到最大跳数深度时停止。 **实时图谱**——在追踪运行时自动绘制。钱包以六边形节点显示。节点之间的线条表示资金流动，颜色和粗细反映流动金额。交易所目标节点会脉冲显示红色。点击任意节点可高亮显示其与源头之间的完整链条。 **监控引擎**——对已完成的追踪结果，在选定时间窗口内重新检查每个钱包。检测异常：单笔超过5万美元的转账、结构化交易（设计用于规避检测的相似金额多笔转账）、突然激活（休眠90天以上的钱包突然活动）以及共享Gas资助者。 **源头追踪器**——从每个钱包反向查找其资金来源。显示汇总表格：钱包地址、资金来源、跳数、涉及的交易所以及该交易所是否要求身份验证。 **报告生成器**——对任何已完成的运行，生成两个文件：一个用于进一步分析的结构化JSON文件，以及一个包含所有发现、表格和叙述的格式化Word文档。选择Word格式是经过深思熟虑的——法律团队可以在Word文件中进行编辑和注释，而这是PDF无法实现的，在实践中非常重要。 **钱包注册表**——包含76个已知交易所地址、混币器和桥接器的查找表。追踪过程中发现的每个钱包都会立即与此注册表进行比对。 **登录保护**——工具在浏览器加载任何内容之前要求输入用户名和密码。凭据设置在本地配置文件中，绝不会在应用程序中硬编码。 **测试套件**——每次启动工具时运行的38项自动化测试。它们会在其他操作运行前检查分析逻辑、交易所识别和运算符识别是否正常工作。 ## 已发现的Bug ### Bug 1 — 监控终端被原始数据淹没 监控会运行，但终端会充满输出，最终屏幕变成无法阅读的原始数据墙。 查看服务器代码时，我发现监控端点实际上为每次运行启动了两个独立进程。第一个本应向浏览器流式传输实时日志行，第二个本应捕获最终结果。问题是第一个进程没有方法将其日志输出与结果分离——它使用了没有标记的普通print语句，导致数千行JSON结果被当作日志消息处理，并直接以纯文本形式流式传输到终端。 第二个进程处理方式正确——它在输出中使用了特殊标记，使服务器能够将日志与结果分离。但此时第一个进程已经淹没了浏览器。 ``` // Before — two processes, first one dumps raw JSON into the terminal runPython(['-c', `...print(json.dumps(result))`], onLog, onDone, onError); const proc2 = ef(python, ['-c', `...sys.stdout.write('__RESULT__' + json.dumps(result))`]); // After — one process, clean separation of logs and result const proc2 = ef(python, ['-c', `...sys.stdout.write('__RESULT__' + json.dumps(result))`]); ``` 修复方法是完全移除第一个进程。第二个进程已经正确处理了一切。一行删除，问题解决。经验教训是：当看起来正常运行但输出错误时，问题通常比你想象的更早出现在流程中。我盯着前端渲染代码看了好几天，才在服务器中发现重复的进程。 ### Bug 2 — 图谱在追踪过程中崩溃并显示“节点未找到” 在开发过程中，我重构了钱包数据的内部存储方式以清理导出格式。重构后，图谱在追踪过程中停止加载——抛出“节点未找到”错误。 问题起初不明显。追踪器将钱包存储在以小写地址为键的查找表中——因为以太坊地址不区分大小写，大小写混合会导致不匹配。图谱渲染器需要每个钱包具有`id`字段以正确连接所有元素。重构后，我将`id`设置为API返回的原始地址——其中有时会混合大小写字母。 可视化图谱使用独立系统来绘制钱包之间的连接线。该系统通过`id`查找钱包以确定源节点和目标节点。当`id`大小写混合而查找表键为小写时，系统无法找到钱包并导致崩溃。 ``` // Before — id was set to original address, case not guaranteed id: n.addr // could be "0x443fBE5c...047F" // After — force lowercase to match the lookup table id: (n.addr || '').toLowerCase() // always "0x443fbe5c...047f" ``` 修复方法只有一行，但定位问题花费了较长时间，因为错误信息在图谱库深处生成——它不会告诉你哪个字段导致了不匹配。经验教训是：当你使用具有特定键格式的查找表时，所有引用该表的内容都必须使用完全相同的格式。不允许例外。 ## 我是如何构建它的 我来自制造业背景。没有计算机科学学位，没有训练营经历。我构建它是因为我亲身受到所调查诈骗的影响——我损失了资金，因此我想做些有用的事情。 我在开发过程中全程使用AI（Claude）——作为学习工具、代码审查员和调试伙伴。每个终端错误都提交给Claude。决策由我做出：构建什么、如何构建、输出应呈现什么形式，以及取证调查人员在报告中实际需要什么。我做出了这些决定。 架构决策——保持API密钥在服务器端、将图谱渲染器与数据管道分离、独立构建三种分析模式、添加登录保护以便安全演示——都源于解决实际问题。当API密钥在浏览器源代码中可见时会发生什么？当图谱坐标出现在导出数据中并污染它时？我遇到了这两者并进行了修复。系统正常运行。测试通过。我可以实时演示所有功能。 ## 我的收获 - 以太坊地址看起来像纯文本，但实际上不区分大小写——大小写混合会静默破坏查找方式，且难以察觉 - 免费的公共API有严格的速率限制，影响调查数据质量——每次调用最多500笔交易，这意味着高交易量钱包总是不完整，这必须在任何用于法律用途的报告中披露 - 如何在不刷新页面的情况下将实时数据从服务器流式传输到浏览器——以及混合两种方法处理同一数据流时会出现什么问题 - 在提供浏览器工具的同时保持密钥在服务器端，需要特定模式——服务器在发送页面之前注入密钥，这样浏览器永远不会在源代码中看到它 - 从代码生成Word文档比PDF更适合法律工作——法律团队可以编辑和注释Word文件，这在实践中很重要 - 结构化——将大额转账拆分为小额以规避检测——具有可被自动识别的特定数学模式 - 如何构建一个无需使用真实API密钥即可运行的测试套件，通过在测试中用受控的假数据替换真实数据调用 - 构建调查工具中最困难的部分是决定哪些信息真正有用，而不是仅仅看起来令人印象深刻——我不断删减那些增加复杂性但不增加报告阅读者价值的功能 ## 下一步计划 - 对本地服务器添加速率限制，防止意外过载 - 在发送到网络之前对钱包地址格式进行服务器端验证 - 审计日志——记录执行了哪些追踪以及何时执行 - 训练一个针对取证和金融犯罪模式的自定义AI模型——取代当前将JSON导出导入公共AI并单独编译叙述的手动步骤。目标是实现一个“导出”按钮，一次性生成结构化数据、调查叙述和最终文档 - 跨链追踪——通过桥接器追踪资金在以太坊与其他网络之间的流动 ## 使用方法 ``` # 克隆并进入目录 git clone https://github.com/yourusername/neural-trace.git cd neural-trace # 复制环境文件并填写您的凭据 cp .env.example .env nano .env # 运行设置 — 安装依赖项，运行测试，启动工具 chmod +x setup.sh ./setup.sh ``` ## 环境变量 ``` ETHERSCAN_API_KEY=your_key_here # Free key from etherscan.io/myapikey NEURAL_TRACE_PORT=8080 # Port to run on (default: 8080) NEURAL_TRACE_USER=admin # Login username for browser access NEURAL_TRACE_PASS=changeme # Login password — change this before use LOG_LEVEL=INFO # Logging verbosity ``` ## 技术栈 | 功能 | 技术 | |---|---| | 提供Web界面并处理所有API请求 | Node.js | | 从区块链获取钱包交易数据 | Etherscan API v2 | | 分析交易中的异常、结构和休眠状态 | Python 3 | | 生成Word格式报告 | docx（Node.js库） | | 绘制实时钱包图谱 | D3.js | | 从服务器向浏览器流式传输实时进度 | Server-Sent Events (SSE) | | 安全存储凭证和API密钥 | 环境变量（.env） | | 通过登录提示保护界面 | HTTP基本认证 | | 启动时运行自动化检查 | pytest | | 获取实时ETH价格 | CoinGecko API | ## 项目结构 ``` neural-trace/ ├── app.html # Entire frontend — graph, monitor, origin trace UI ├── server.js # Local web server and all API endpoints ├── setup.sh # Setup, dependency checks, test runner, launcher ├── core/ │ ├── analyser.py # Spike, structuring, and volume analysis │ ├── fetcher.py # All Etherscan API calls │ ├── intelligence.py # Dormancy and gas map analysis │ ├── monitor.py # Monitor engine orchestrator │ └── pricer.py # Live ETH price fetcher ├── config/ │ ├── exchanges.py # Registry of 76 known exchange/mixer addresses │ └── settings.py # All configuration constants ├── reports/ │ ├── forward_report.js # Word document generator for forward traces │ ├── monitor_report.js # Word document generator for monitor runs │ └── origin_report.js # Word document generator for origin traces ├── tests/ │ ├── conftest.py # Mocks API calls so tests need no live credentials │ ├── test_analyser.py # 16 tests for transaction analysis logic │ ├── test_exchanges.py # 14 tests for exchange/mixer/bridge detection │ └── test_intelligence.py # 8 tests for operator detection logic ├── data/ │ ├── forward_trace/ # Saved forward trace JSON files │ ├── monitor/ # Saved monitor run JSON files │ ├── origin_trace/ # Saved origin trace JSON files │ └── reports/ # Generated Word documents ├── .env.example # Template for credentials and configuration └── requirements.txt # Python dependencies ``` *从制造业转型的职业探索者。在公共平台学习。构建真实事物。*

标签：AI辅助报告, ESC漏洞, ETH分析工具, JSON数据导出, MITM代理, RICO欺诈调查, 专业调查报告, 交易所识别, 交易模式识别, 交易追溯, 以太坊钱包追踪, 加密货币反洗钱, 加密资产追踪, 区块链取证, 区块链数据分析, 可疑活动监控, 可视化图谱, 存款账户追踪, 安全规则引擎, 数字货币调查, 法律级调查报告, 自动化取证, 自定义脚本, 证据收集, 资金流分析, 逆向工具, 钱包图谱, 链上数据分析