简介这是一款面向Windows系统安全分析与数字取证初学者的本地化痕迹检测工具适用于IT运维人员、网络安全爱好者及计算机取证入门学习者用于快速梳理个人电脑近期使用行为轨迹。工具仅读取注册表中留存的访问记录不联网、不写入、不获取浏览器历史保障隐私与系统安全可有效识别目录/文件访问、关键词搜索、USB设备接入等关键操作痕迹。压缩包共39个文件含5个核心可执行程序如RegistryFinder.exe、查看器.exe、4个批处理脚本用于上下文菜单与注册表关联配置、17个图标资源支持界面可视化操作以及配置文件、日志数据和说明文档等整体体积仅4.5MB轻量便携。目前已有1661人下载学习提供开箱即用的完整检测流程从注册表解析、痕迹归类展示到结果导出附带详细readme说明与多语言配置支持适合实操演练与痕迹分析思维培养。1. 这不是“清道夫”而是一台Windows行为黑匣子能回放你昨天下午3:22在哪个窗口切过屏、谁动过你的Edge历史、U盘插拔时间精确到毫秒你有没有遇到过这种场景一台交接的办公机领导问“上周五下班前谁改过财务报表模板”你翻遍最近文档修改时间却发现Excel自动保存覆盖了原始时间戳或者排查某次蓝屏安全团队只给你一句“怀疑有异常进程驻留”但任务管理器里干干净净——这时候靠人工翻注册表、查事件日志、扒Prefetch文件效率低得像用算盘解微分方程。这个Windows使用痕迹检测工具就是为这类真实排障现场而生的它不删记录不清理缓存而是把系统底层散落各处的“数字指纹”——包括ShellBag资源管理器路径导航历史、UserAssist程序启动频次与时间、AmCache程序执行元数据、LNK快捷方式解析、USBSTOR设备插拔记录、JumpList跳转列表、甚至Recycle.Bin里被删文件的原始路径与删除时间——全部采集、标准化、打上统一时间轴最终生成一份带可交互时间线的HTML报告。它面向的是IT支持工程师、内部审计人员、取证初学者以及所有需要“用证据说话”而非“凭感觉判断”的一线技术角色。项目完全离线运行不联网、不上传、不依赖任何云服务所有分析逻辑封装在单个Python脚本轻量级SQLite数据库中源码开放无混淆、无打包你打开就能读、改完就能跑。2. 技术栈与架构设计为什么选PythonSQLite而不是PowerShell或C这个项目表面看是个“痕迹扫描器”实则是一套Windows用户行为数据的联邦式采集与归一化引擎。它没走传统取证工具的老路比如全盘镜像专业解析而是聚焦“可用性优先”让非专业人员也能在5分钟内拿到一份可读、可验证、可追溯的数据快照。这就决定了它的技术选型不是炫技而是务实权衡。2.1 核心模块划分采集层、解析层、存储层、呈现层四层解耦整个流程严格遵循“采集→解析→存储→呈现”四阶段流水线每个阶段职责单一接口清晰采集层acquisition/负责定位并读取原始数据源。它不硬编码路径而是通过winreg动态查询当前用户的SID再拼接HKEY_USERS\SID\Software\Microsoft\Windows\CurrentVersion\Explorer等关键键值对C:\Windows\Prefetch\目录它用os.scandir()而非glob避免因通配符匹配失败导致漏采对C:\$Recycle.Bin\它绕过权限限制直接调用win32file.CreateFile()以FILE_FLAG_BACKUP_SEMANTICS标志打开句柄确保能读取被删文件的$I元数据文件。解析层parsers/这是项目最厚的模块。每个子模块对应一类Windows痕迹数据格式shellbag.py解析NTUSER.DAT中Software\Microsoft\Windows\Shell\BagMRU和BagMRU的二进制结构还原出用户访问过的每一个文件夹路径及最后访问时间注意这里的时间是Windows FILETIME需转换为Pythondatetimeuserassist.py解密NTUSER.DAT中Software\Microsoft\Windows\CurrentVersion\Explorer\UserAssist下的ROT13加密项名并提取计数器与最后执行时间amcache.py解析C:\Windows\AppCompat\Programs\Amcache.hve注册表 hive 文件提取程序签名、首次运行时间、文件大小、SHA1哈希等字段lnk_parser.py基于pylnk3库深度解析.lnk文件不仅读取目标路径还提取Machine ID、Volume ID、MAC地址等网络环境线索。存储层db/所有解析结果统一写入一个嵌入式SQLite数据库traces.db。表结构高度规范化主表artifacts包含id,source_type如shellbag、userassist,timestamp统一转为ISO8601字符串便于排序,raw_dataJSON序列化原始字段辅表sources记录每次采集的主机名、用户名、采集起止时间用于审计溯源。呈现层report/用Jinja2模板渲染HTML报告。关键设计是“时间轴驱动”前端JavaScript加载traces.db导出的JSON数据后用vis.js构建交互式时间线点击任一节点可展开原始JSON字段同时提供按source_type、timestamp_range、keyword如搜索excel的三级过滤器避免信息过载。提示项目未采用Elasticsearch或MongoDB是因为单机SQLite已足够支撑万级痕迹条目实测10万条插入耗时3秒且零配置、免维护符合“开箱即用”定位。2.2 为什么Python是唯一合理选择三个血泪经验告诉你不是因为“简单”很多人误以为Python适合小工具只是语法甜。错。真正原因是Windows原生API绑定成熟度——pywin32对RegQueryValueEx、CreateFile等底层调用的封装稳定可靠而Rust或Go的Windows FFI生态在注册表深度遍历、卷影复制VSS兼容性上仍有坑曾有同事用Rust写的类似工具在Win10 21H2上因RegOpenKeyEx返回ERROR_ACCESS_DENIED卡死换回Pythonwinreg立刻解决。不是因为“生态全”pylnk3、pyprefetch这些库确实省力但更关键的是调试友好性。当shellbag解析出错时你可以在pdb.set_trace()里直接print(hex(data[0]))看字节流而C需配符号服务器、PowerShell调试器对二进制结构支持弱。最关键部署即拷贝编译成exe会增大体积、引入VC运行时依赖且反编译后逻辑暴露。而.py源码requirements.txt用户双击run.bat内含python main.py即可启动所有依赖用pip install -r requirements.txt一行搞定连Python环境都支持便携版如PortablePython。2.3 目录结构即设计文档一眼看懂数据流向windows-trace-detector/ ├── main.py # 主入口协调采集→解析→存储→呈现全流程 ├── requirements.txt # 仅4个核心依赖pywin32, pyprefetch, pylnk3, jinja2 ├── config.json # 可配置项是否采集Recycle.Bin、最大LNK解析深度、时间范围过滤阈值 ├── acquisition/ │ ├── registry_collector.py # 注册表采集器按预设键路径批量读取 │ ├── filesystem_collector.py # 文件系统采集器处理Prefetch/Amcache/Recycle.Bin │ └── ... ├── parsers/ │ ├── __init__.py # 统一注册解析器from parsers import get_parser │ ├── shellbag.py # ShellBag解析器含详细注释如何识别BagMRU链表头 │ ├── userassist.py # UserAssist解析器含ROT13解密函数 │ └── ... ├── db/ │ ├── init_db.py # 创建traces.db表结构 │ └── sqlite_writer.py # 线程安全的批量插入封装 ├── report/ │ ├── templates/ # Jinja2模板base.html, timeline.html, artifact_detail.html │ └── generate_report.py # 渲染HTML报告输出到./output/report_20240520_1422.html └── output/ # 默认输出目录可配置这个结构不是随意组织的。acquisition/和parsers/物理隔离意味着你可以轻松替换filesystem_collector.py为一个从内存dump中提取AmCache的版本而无需改动解析逻辑report/完全独立未来想接入Web服务只需重写generate_report.py的输出部分模板逻辑复用。3. 快速上手从下载到生成第一份HTML报告含完整命令与参数说明别被“取证工具”四个字吓住——这个项目的设计哲学是“让第一次运行就成功”。下面步骤在Windows 10/11上实测通过全程无需管理员权限仅部分采集项如USBSTOR需提权脚本会自动降级处理。3.1 环境准备Python 3.8 与极简依赖项目要求Python 3.8或更高版本因使用:海象运算符简化条件判断推荐使用官方安装包https://www.python.org/downloads/安装时务必勾选“Add Python to PATH”。验证安装python --version # 应输出 Python 3.8.x 或更高注意不要用Anaconda或Miniconda的base环境因其自带的pywin32版本常与项目不兼容。若已安装建议新建虚拟环境python -m venv venv venv\Scripts\activate.bat3.2 安装依赖四行命令无隐藏坑进入项目根目录后执行pip install --upgrade pip pip install -r requirements.txtrequirements.txt内容精简到极致pywin32306 pyprefetch20230710 pylnk31.0.1 Jinja23.1.3提示pyprefetch版本锁定为20230710因为新版将PrefetchParser类重构为PrefetchFile而本项目仍依赖旧API。若你手动升级导致AttributeError: PrefetchFile object has no attribute get_filename请立即回退pip install pyprefetch20230710。3.3 首次运行理解main.py的三个核心参数项目主入口main.py接受三个关键参数它们直接决定报告的深度与范围参数作用推荐值说明--scope采集范围user可选user仅当前用户、machine全机需管理员权限、custom自定义路径--output输出目录./output默认创建output/子目录报告HTML与traces.db均存放于此--since时间过滤起点2024-01-01T00:00:00ISO8601格式只采集此时间之后的痕迹大幅缩短运行时间执行命令以采集当前用户近30天痕迹为例python main.py --scope user --since 2024-05-01T00:00:00 --output ./my_report你会看到实时日志滚动[INFO] Starting acquisition for scope: user [INFO] Collecting Registry artifacts from NTUSER.DAT... [INFO] Parsing ShellBag data... found 142 entries [INFO] Collecting Filesystem artifacts from Prefetch... [INFO] Parsing AmCache.hve... extracted 89 program records [INFO] Writing 1204 artifacts to traces.db... [INFO] Generating HTML report to ./my_report/report_20240520_1422.html [SUCCESS] Report generated! Open with browser: file:///D:/project/my_report/report_20240520_1422.html关键细节--since参数不是“过滤报告”而是前置过滤采集源。例如ShellBag解析时会跳过时间戳早于--since的条目避免无谓解析Prefetch文件则只读取修改时间晚于该时间的.pf文件。这比在SQLite里WHERE timestamp ?高效得多。3.4 报告解读三步定位关键线索生成的HTML报告不是静态页面而是可交互取证面板时间轴总览Timeline View顶部Vis.js时间线默认显示所有痕迹。鼠标悬停节点显示摘要如“Excel.exe executed at 2024-05-19 15:22:31”点击展开完整JSON。分类筛选Filter Panel左侧栏可按Source Type如只看userassist、Time Range拖动滑块限定区间、Keyword Search输入“chrome”快速定位浏览器痕迹。原始数据钻取Raw Data Tab每个条目底部有Show Raw JSON按钮显示该痕迹在数据库中的原始存储格式含source_path来源文件路径、parsed_fields解析出的字段字典、acquisition_time本次采集时间。实战技巧若发现可疑程序点击其userassist条目 →Show Raw JSON→ 复制raw_data[program_id]字段 → 在AmCache分类中搜索该ID即可关联到该程序的数字签名与文件哈希完成“行为→实体”闭环验证。4. 避坑指南五个真实翻车现场与救命解法这个项目在某高校实验室的23台测试机上跑过完整回归以下问题均来自真实报错日志与用户反馈每一条都附带可立即执行的修复命令。4.1 现象main.py运行报错OSError: [WinError 5] 拒绝访问卡在Collecting Registry artifacts...原因脚本尝试读取HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer等全局注册表项但当前用户无权限。项目默认--scope user时应只读HKEY_CURRENT_USER此错误表明config.json被手动修改或环境变量污染。解决删除项目根目录下的config.json恢复默认配置或确认其内容为{ scope: user, include_machine_keys: false }若必须采集机器级注册表请以管理员身份运行CMD再执行python main.py --scope machine。4.2 现象报告中ShellBag条目大量显示UNKNOWN路径时间戳为1601-01-01T00:00:00原因ShellBag解析器遇到损坏的二进制结构常见于老旧系统或强制关机后的NTUSER.DAT解析器未做容错直接返回空值。解决打开parsers/shellbag.py定位到parse_bagmru_entry()函数在try:块末尾添加兜底逻辑except Exception as e: # 原始代码可能直接raise改为记录警告并返回占位符 logging.warning(fFailed to parse ShellBag entry at offset {offset}: {e}) return { path: UNKNOWN, last_access_time: 1601-01-01T00:00:00, raw_bytes: base64.b64encode(data).decode() }4.3 现象Recycle.Bin采集耗时超10分钟且报告中无任何回收站条目原因filesystem_collector.py默认递归扫描C:\$Recycle.Bin\*下所有子目录但某些企业环境启用了BitLocker导致$Recycle.Bin\S-1-5-21-...目录权限异常os.scandir()抛出PermissionError后中断遍历。解决编辑config.json添加recycle_bin_skip_errors: true{ recycle_bin_skip_errors: true, max_recycle_depth: 3 }同时在filesystem_collector.py的collect_recycle_bin()函数中将for entry in os.scandir(path):包裹在try/except PermissionError中捕获后continue。4.4 现象生成的HTML报告打开后时间轴空白浏览器控制台报错vis.js not loaded原因report/templates/base.html中CDN链接失效原用https://unpkg.com/vis-timelinelatest/standalone/umd/vis-timeline-graph2d.min.js但unpkg近期调整了路径规则。解决打开report/templates/base.html将第12行script srchttps://unpkg.com/vis-timelinelatest/standalone/umd/vis-timeline-graph2d.min.js/script替换为稳定版本CDNscript srchttps://cdn.jsdelivr.net/npm/vis-timeline7.4.10/standalone/umd/vis-timeline-graph2d.min.js/script4.5 现象UserAssist解析出的程序名全是乱码如??????.exe原因userassist.py中ROT13解密函数未正确处理Unicode字符。原始代码对bytes对象直接ROT13但Windows注册表中UserAssist项名是UTF-16-LE编码需先解码再ROT13。解决修改parsers/userassist.py中decrypt_rot13()函数def decrypt_rot13(encoded_bytes): # 原始错误写法return encoded_bytes.translate(...) # 正确写法先解码为字符串ROT13再编码回bytes try: s encoded_bytes.decode(utf-16-le) decrypted .join( chr((ord(c) - ord(A) 13) % 26 ord(A)) if A c Z else chr((ord(c) - ord(a) 13) % 26 ord(a)) if a c z else c for c in s ) return decrypted.encode(utf-16-le) except UnicodeDecodeError: return bDECODE_ERROR5. 二次开发实战给痕迹报告加“行为聚类”功能附完整代码与验证方法当你已经能稳定生成报告下一步自然想回答更深层问题“这些痕迹背后是否存在某种模式”比如连续三天都在19:00-20:00启动notepad.exe并访问C:\Users\Public\Notes\这大概率是定时写日志又或者chrome.exe频繁在凌晨2点访问同一组域名可能指向自动化脚本。本章带你亲手实现一个轻量级“行为聚类”模块不引入复杂算法而是用时间窗口程序路径相似度做规则匹配效果立竿见影。5.1 设计思路为什么不用K-Means而用滑动窗口K-Means需要特征工程如将时间转为向量且对“少量高频行为”敏感度低。我们采用更贴近运维直觉的方案固定时间窗内的同程序行为聚合。逻辑如下将所有userassist和shellbag条目按program_name或path分组对每组按timestamp升序排列计算相邻条目时间差若差值 600秒10分钟则视为同一“会话”合并为一条聚类记录包含start_time,end_time,count,unique_paths去重路径列表最终输出为新表behavior_clusters供报告页面调用。优势零训练、无参数调优、结果可解释。某公司IT部用此逻辑30秒内从2万条痕迹中揪出一个每晚自动备份的robocopy脚本路径规律为C:\Data\*\backup_*。5.2 核心代码cluster_behaviors.py新增模块在项目根目录新建analysis/cluster_behaviors.py内容如下# analysis/cluster_behaviors.py import sqlite3 import json from datetime import datetime, timedelta from typing import List, Dict, Any def cluster_by_time_window(db_path: str, window_seconds: int 600) - List[Dict[str, Any]]: 对traces.db中的痕迹按程序名时间窗聚类 :param db_path: SQLite数据库路径 :param window_seconds: 时间窗大小秒默认10分钟 :return: 聚类结果列表每项含session_id, program_name, start_time, end_time, count, unique_paths conn sqlite3.connect(db_path) conn.row_factory sqlite3.Row # 支持字典式访问 cursor conn.cursor() # 1. 提取所有userassist和shellbag条目标准化字段 cursor.execute( SELECT id, source_type, CASE WHEN source_type userassist THEN json_extract(raw_data, $.program_name) WHEN source_type shellbag THEN json_extract(raw_data, $.path) ELSE UNKNOWN END as key_field, timestamp FROM artifacts WHERE source_type IN (userassist, shellbag) AND timestamp IS NOT NULL ORDER BY key_field, timestamp ) rows cursor.fetchall() conn.close() clusters [] current_cluster None for row in rows: key row[key_field] or UNKNOWN ts datetime.fromisoformat(row[timestamp].replace(Z, 00:00)) if current_cluster is None: # 初始化第一个聚类 current_cluster { session_id: fcluster_{row[id]}, program_name: key, start_time: ts, end_time: ts, count: 1, unique_paths: set([key]) } else: # 判断是否属于当前聚类同程序名 时间差 window if (key current_cluster[program_name] and ts - current_cluster[end_time] timedelta(secondswindow_seconds)): current_cluster[end_time] ts current_cluster[count] 1 current_cluster[unique_paths].add(key) else: # 保存当前聚类开启新聚类 clusters.append({ **current_cluster, unique_paths: list(current_cluster[unique_paths]), duration_seconds: int((current_cluster[end_time] - current_cluster[start_time]).total_seconds()) }) current_cluster { session_id: fcluster_{row[id]}, program_name: key, start_time: ts, end_time: ts, count: 1, unique_paths: set([key]) } # 添加最后一个聚类 if current_cluster: clusters.append({ **current_cluster, unique_paths: list(current_cluster[unique_paths]), duration_seconds: int((current_cluster[end_time] - current_cluster[start_time]).total_seconds()) }) return clusters def save_clusters_to_db(db_path: str, clusters: List[Dict[str, Any]]): 将聚类结果存入数据库新表 behavior_clusters conn sqlite3.connect(db_path) cursor conn.cursor() # 创建表若不存在 cursor.execute( CREATE TABLE IF NOT EXISTS behavior_clusters ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, program_name TEXT NOT NULL, start_time TEXT NOT NULL, end_time TEXT NOT NULL, count INTEGER NOT NULL, duration_seconds INTEGER NOT NULL, unique_paths TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ) # 批量插入 for cluster in clusters: cursor.execute( INSERT INTO behavior_clusters (session_id, program_name, start_time, end_time, count, duration_seconds, unique_paths) VALUES (?, ?, ?, ?, ?, ?, ?) , ( cluster[session_id], cluster[program_name], cluster[start_time].isoformat(), cluster[end_time].isoformat(), cluster[count], cluster[duration_seconds], json.dumps(cluster[unique_paths], ensure_asciiFalse) )) conn.commit() conn.close() print(f[INFO] Saved {len(clusters)} behavior clusters to database.) if __name__ __main__: # 示例从默认output/traces.db聚类窗口10分钟 clusters cluster_by_time_window(./output/traces.db, window_seconds600) save_clusters_to_db(./output/traces.db, clusters)5.3 集成到主流程两行代码注入聚类能力修改main.py在generate_report()函数调用前插入聚类逻辑# main.py 中约第120行原代码 # generate_report(output_dir, db_path) # 新增 print([INFO] Running behavior clustering...) from analysis.cluster_behaviors import cluster_by_time_window, save_clusters_to_db clusters cluster_by_time_window(db_path, window_seconds600) save_clusters_to_db(db_path, clusters) # 原有行保持不变 generate_report(output_dir, db_path)同时在requirements.txt末尾添加# analysis dependencies无需额外依赖纯Python标准库5.4 报告增强在HTML中展示聚类结果修改report/templates/timeline.html在时间轴下方添加新区块!-- report/templates/timeline.html -- h2Behavior Clusters (10-min windows)/h2 div classcluster-list {% for cluster in clusters %} div classcluster-item strong{{ cluster.program_name }}/strong ({{ cluster.count }} times, {{ cluster.duration_seconds }}s) br small{{ cluster.start_time }} → {{ cluster.end_time }}/small br Paths: {{ cluster.unique_paths | join(, ) | truncate(100) }} /div {% endfor %} /div然后修改report/generate_report.py在渲染上下文context中加入clusters# report/generate_report.py 约第85行 def generate_report(output_dir: str, db_path: str): # ... 原有代码 ... # 新增查询聚类数据 conn sqlite3.connect(db_path) conn.row_factory sqlite3.Row clusters [dict(row) for row in conn.execute(SELECT * FROM behavior_clusters ORDER BY count DESC LIMIT 10)] conn.close() context { # ... 原有字段 ... clusters: clusters # 新增 } # ... 原有渲染代码 ...5.5 验证与调优如何确认聚类有效运行后检查output/traces.db是否新增behavior_clusters表sqlite3 ./output/traces.db SELECT COUNT(*) FROM behavior_clusters; # 应返回 0 sqlite3 ./output/traces.db SELECT * FROM behavior_clusters LIMIT 3; # 查看样例数据更关键的是业务验证打开生成的HTML报告找到Behavior Clusters区块。如果看到类似chrome.exe (5 times, 3240s) 2024-05-19T09:15:22 → 2024-05-19T10:09:02 Paths: C:\Users\Alice\Downloads\, https://docs.google.com/, ...说明聚类成功捕获了用户上午的浏览器会话。若结果为空检查--since参数是否过窄或traces.db中是否有足够多的userassist条目SELECT COUNT(*) FROM artifacts WHERE source_typeuserassist;。从那以后我每次给客户交付痕迹报告都会强制走一遍python analysis/cluster_behaviors.py哪怕只是看看top3聚类——它像一道“行为X光”瞬间穿透杂乱的时间戳照出用户真实的操作节奏。这种确定性比任何模糊的“疑似异常”描述都更有说服力。希望帮到你。本文还有配套的精品资源点击获取
