Chill-Ethical-People/TraceQuarry

GitHub: Chill-Ethical-People/TraceQuarry

TraceQuarry 是一个本地优先的 Linux DFIR 工作台，将 UAC 收集的取证数据转化为可审查的事件时间线、IoC 匹配和辅助调查发现。

Stars: 3 | Forks: 0

# TraceQuarry

CI status CodeQL status Snyk Open Source status Gitleaks secret scan status Apache-2.0 license Python 3.11 and 3.12

TraceQuarry layered timeline mark

TraceQuarry 是一个本地优先的 Linux DFIR 工作台，用于处理类 Unix Artifacts Collector (UAC) 证据。它将 UAC 归档文件或解压后的 UAC 目录 转换为经得起审查的事件时间线、源覆盖率索引、IoC 命中记录，以及 供响应人员审查的高价值发现。 标语：**挖掘时间线。保全证据。** ## 引导式演练

TraceQuarry guided walkthrough showing synthetic UAC intake, time-range inspection, assisted investigation, findings, raw timeline evidence, and analyst annotation

这段 28 秒的光标引导式演练使用了内置的合成测试数据。它 演示了归档文件接入、调查配置文件选择、证据范围 检查、事件设置与 IoC、实时运行进度、摘要审查、 原始事件验证，以及通过自然浏览器工作流进行的分析师批注。 选择预览图以打开 [全分辨率 WebM 视频](docs/media/tracequarry-walkthrough.webm)。 ## 为什么分析师使用 TraceQuarry Linux UAC 收集包含丰富的证据，但有用的信号分散在 认证日志、审计日志、Shell 历史记录、账户文件、持久化 位置、包日志、进程快照、网络状态和文件系统 元数据中。TraceQuarry 将这些来源整合到一个标准化时间线中，同时 保留源路径和原始行上下文，以便进行经得起审查的复核。 使用它可以快速从“我们有一个 UAC 归档文件”转变为响应人员视角下的视图，涵盖 访问、特权活动、持久化、可疑工具、IoC 命中，以及 值得进一步深入验证的事件窗口。 ## DFIR 用例 当您需要快速确定使用 UAC 收集的 Linux 主机范围 并回答响应人员的以下问题时，请使用 TraceQuarry： - 可疑访问是何时开始和结束的？ - 哪些源 IP 进行了认证、认证失败或对 SSH 进行了暴力破解？ - 登录失败活动是否最终演变成了成功的 root 或普通用户登录？ - 是否通过 cron、systemd、PAM、Shell 配置文件、 rc.local、init.d 或 SSH 授权密钥添加了持久化机制？ - 是否被滥用了 sudoers、UID 0 账户、特权组、SUID/SGID 文件或 Linux capabilities？ - 是否更改了密码、解锁了账户、添加了用户，或修改了特权组 成员身份？ - 是否被访问了凭据文件、SSH 密钥、云元数据、kube configs 或密码 资料？ - 证据中是否存在常见的攻击者工具，如 `rclone`、`anydesk`、隧道工具、 挖矿程序、归档实用程序或云/容器 CLI？ - 能否生成一个更小的事件窗口时间线，用于审查、报告 或移交给其他分析师？ TraceQuarry 是一个分流和时间线辅助工具。调查发现只是线索，而非最终 结论。在将重要发现用于报告之前，请根据原始源代码行和相关的 时间线上下文对其进行验证。 ## 证据处理 建议的响应人员处理方式： - 使用复制的 UAC 归档文件进行操作，而不是原始的主证据。 - 在您的案例笔记中记录原始归档名称、大小、哈希值、收集主机、收集时间、 分析师和时区假设。 - 保持输出目录针对特定案例，例如 `out///`。 - 将解析器输出视为衍生证据，并保留用于生成它的命令行或 GUI 设置。 - 不要将真实的 UAC 归档、提取的证据或生成的解析器输出 推送到共享存储库中。 TraceQuarry 在设计上是本地优先的。解析器不需要将证据 上传到外部服务。 GUI 特意限制为仅限环回访问。不要将其直接暴露在 LAN 或 Internet 上。要从另一台工作站进行访问，请使用终止于分析主机的 经过身份验证的 SSH 隧道。TraceQuarry 创建的新工作目录 权限为 `0700`，衍生证据的权限为 `0600`；当收集 包含敏感资料时，请使用特定于案例的加密卷。 ## 案例快速入门 1. 检查归档时间范围。 ``` cd tracequarry python3 -m uac_parser.web --host 127.0.0.1 --port 8765 --work-dir web_runs ``` 打开 `http://127.0.0.1:8765`，选择 **Archive upload** 或 **Server path**，选择日志年份和时区，然后点击 **Inspect Time Range**。对于 假设主导的审查，在开始分析之前选择一个 **Assisted investigation** 配置文件。 2. 运行具有较宽时间窗口的首次解析。 ``` python3 -m uac_parser.cli /cases/uac-host01.tar.gz --out out/host01-first-pass \ --incident-start 2026-04-01T00:00:00+08:00 \ --incident-end 2026-06-16T23:59:59+08:00 \ --year 2026 \ --timezone Asia/Hong_Kong \ --threat-type ransomware_extortion \ --ioc 198.51.100.50 \ --ioc rclone \ --ioc anydesk ``` 3. 审查 `summary.md`、`findings.json` 和 `timeline_mini.csv`。 4. 一旦了解了入侵时期，就使用更窄的窗口重新运行。 5. 将 CSV/JSONL 时间线、发现结果、源覆盖率和确切的 命令行导出或附加到案例记录中。 ## 辅助调查 辅助调查将分析师选择的假设应用于已完成的 时间线。它会优先考虑相关的调查发现，检查是否存在重要的 artifact 组，识别已支持和未解决的调查问题， 并推荐下一步的分析方向。它不会过滤完整的时间线、更改原始 证据、证明所选的威胁类型、识别恶意软件或归因于某个攻击者。 可用的配置文件： - `comprehensive`：当入侵模式未知时的广泛入侵分流 - `ransomware_extortion`：访问、环境准备、数据窃取、影响和清理 - `public_facing_exploitation`：从漏洞利用请求到 payload 执行和持久化 - `credential_compromise`：身份验证、机密信息、账户更改、sudo 和远程访问 - `persistence_backdoor`：PAM、loader、systemd、cron、SSH-key 和账户持久化 - `cryptomining_resource_hijacking`：挖矿程序、矿池、持久化、云和容器滥用 - `apt_like_intrusion`：有效账户、凭据、分层持久化、隧道和跨主机访问 辅助运行会添加 `assisted_investigation.md` 和 `assisted_investigation.json`。案例模式会添加 `case_assisted_investigation.md` 和 `case_assisted_investigation.json`。选定的 配置文件和生成的输出哈希会保留在运行清单中。 已完成的 GUI 任务还提供 **Explore Timeline**。证据资源管理器 分页显示事件窗口或完整的 JSONL 时间线，支持文本、 严重程度和源类型过滤，并显示带有 主机和收集来源的原始记录。分析师的处置结果、标签和备注会保存 到 `analyst_annotations.json`；它们绝不会修改解析器时间线或源 证据。 ## 选择时间设置 Linux 的 auth、cron、syslog 和 package 日志通常使用省略 年份的 syslog 样式时间戳。TraceQuarry 需要年份和时区来将这些记录 标准化为 UTC。 - 对于没有年份的日志，使用 `--year` 指定应用年份。 - 对于收集时的主机本地时区，使用 `--timezone`。 - 尽可能使用带时区信息的事件窗口，例如 `2026-06-16T09:58:00+08:00`。 - 对照已知的业务事件、EDR 警报、 防火墙日志、VPN 日志或 SIEM 数据确认标准化的 UTC 输出。 已知注意事项：文件名嵌入了较早年份的轮转文件可能仍然 包含没有年份的日志行。如果将 `--year 2026` 应用于诸如 `yum.log-20230101` 的轮转文件，解析器可能会显示出明显的未来或偏移的日期。 在最终确定事件窗口之前，请审查 `source_index.json`、轮转文件名和原始源行。 没有原生时间戳的状态 artifacts 可能会获得 `correlated_*` 时间戳（当 bodyfile 或 auditd PATH 记录支持时间线放置时）。 ## 输出审查顺序 对于事件响应，请按以下顺序审查输出： 1. `parser_errors.log` 确认关键源是否未能解析。空文件是最理想的。 2. `source_index.json` 检查证据覆盖率。确认是否存在 auth 日志、audit 日志、Shell 历史、 登录历史、进程状态、网络状态、账户文件、sudoers、cron、 systemd、PAM、SSH 密钥和 bodyfile 数据。 3. `summary.md` 阅读响应人员摘要，了解高级发现、横向移动说明、 账户生命周期更改、暴力破解摘要和攻击剧情。 4. `findings.json` 将此视为高价值线索的队列。将每个重要发现关联到 原始源代码行、源文件、时间戳类型、用户、进程、命令和 相关事件。 5. `timeline_mini.csv` 将此作为可疑事件窗口的主要分析师时间线。 按 `severity`、`event_category`、`event_action`、`user`、`src_ip`、 `process`、`command`、`ttp` 和 `source_path` 进行过滤。 6. `timeline_full.csv` 当 mini 时间线在所选窗口边缘显示可疑活动，或者 您需要发现早期的环境准备、密码 更改、账户创建或持久化时使用此文件。 7. `ioc_hits.csv` 使用此文件来确定已知 IP、域、哈希、路径、用户名和工具名称的范围。 大量的 IoC 命中在报告前应按操作、用户、源文件和 首次/最后一次出现的时间进行分组。 ## 输出契约 TraceQuarry 会将以下文件写入选定的输出目录： - `timeline_full.jsonl`：所有解析的事件 - `timeline_full.csv`：适合电子表格的完整时间线 - `timeline_mini.jsonl`：设置了开始或结束时间时的事件窗口事件 - `timeline_mini.csv`：适合电子表格的 mini 时间线 - `findings.json`：相关联的检测和攻击剧情 - `ioc_hits.json` 和 `ioc_hits.csv`：提供 IoC 时的 IoC 匹配 - `summary.md`：人类可读的调查摘要 - `source_index.json`：发现的证据来源和解析覆盖率 - `parser_errors.log`：供分析师审查的非致命解析器错误 - `run_manifest.json`：输入身份、源哈希、解析器覆盖率、规则指纹、 执行设置和输出哈希，以实现可重复性 - `assisted_investigation.md` 和 `.json`：当选择了威胁配置文件时的 假设主导的优先级、就绪情况、 检查清单状态、证据引用、安全防护措施和分析师分析枢轴 对于多收集案例工作区，TraceQuarry 还会写入： - `hosts//`：每个 UAC 输入的标准单次收集输出 - `case_timeline_full.jsonl` 和 `case_timeline_full.csv`：合并的案例时间线 - `case_timeline_mini.jsonl` 和 `case_timeline_mini.csv`：合并的事件窗口时间线 - `case_findings.json`：案例发现、攻击剧情和关联 - `case_correlation.json`：结构化的跨收集关联数据 - `case_ioc_hits.json` 和 `case_ioc_hits.csv`：案例级别的 IoC 匹配 - `case_summary.md`：用于 GUI 预览和报告移交的案例级别摘要 - `case_assisted_investigation.md` 和 `.json`：案例级别的假设主导审查 - `case_source_index.json`：单次收集的源覆盖率和来源 - `case_parser_errors.log`：按收集分组的解析器错误 - `case_manifest.json`：案例级别的收集身份、设置、规则和输出哈希 ## CLI 用法 ``` python3 -m uac_parser.cli /cases/uac-host01.tar.gz --out out/host01 \ --incident-start 2026-06-16T08:00:00Z \ --incident-end 2026-06-16T12:00:00Z \ --year 2026 \ --timezone UTC \ --host host01 \ --threat-type credential_compromise \ --ioc 198.51.100.50 \ --ioc rclone \ --ioc-file known_iocs.csv ``` 多收集案例工作区： ``` python3 -m uac_parser.cli --case-out out/case-acme-linux \ --case-name "ACME Linux Intrusion" \ --input /cases/uac-host01.tar.gz \ --input /cases/uac-host02.tar.gz \ --incident-start 2026-06-16T08:00:00Z \ --incident-end 2026-06-16T12:00:00Z \ --year 2026 \ --timezone UTC \ --threat-type apt_like_intrusion \ --ioc 198.51.100.50 \ --ioc rclone ``` 案例模式还可以读取清单： ``` python3 -m uac_parser.cli --case-out out/case-acme-linux \ --input-manifest case-inputs.txt \ --year 2026 \ --timezone Asia/Hong_Kong ``` 已安装的控制台脚本： - `tracequarry` - `tracequarry-web` - `uac-timeline` - `uac-timeline-web` IoC 文件接受每行一个值或以下格式的 CSV 行： ``` value,kind,label 198.51.100.50,ip,synthetic source rclone,literal,exfiltration tooling anydesk,literal,remote access tooling /tmp/kworker,path,suspicious staging path ``` 可接受的 IoC 种类包括 `ip`、`domain`、`hash`、`path` 和 `literal`。 ## Web GUI 用法 Web GUI 复用了与 CLI 相同的解析器流水线。当 分析师想要预览时间范围、从浏览器上传归档文件，或者让 另一位响应人员在无需构建命令行的情况下运行解析器时，它非常有用。 ``` python3 -m uac_parser.web --host 127.0.0.1 --port 8765 --work-dir web_runs ``` GUI 默认上传限制为 8 GiB，工作目录配额为 40 GiB，两个 并发分析插槽，以及 120 秒的请求超时。在 专用的分析工作站上调整这些设置时，不要移除磁盘安全余量： ``` python3 -m uac_parser.web --host 127.0.0.1 --port 8765 --work-dir web_runs \ --max-upload-gib 8 --max-work-dir-gib 40 \ --max-concurrent-jobs 2 --request-timeout 120 ``` 打开 `http://127.0.0.1:8765`，然后： 1. 对于浏览器选择的 `.tar.gz`、`.tgz`、`.tar` 或 `.zip` UAC 输出，选择 **Archive upload**。选择多个归档文件以创建案例工作区。 2. 对于分析计算机上已有的文件或解压目录， 选择 **Server path**。每行输入一个路径以创建案例工作区。 3. 设置日志年份和时区。 4. 点击 **Inspect Time Range**。 5. 设置或细化事件开始和结束时间。 6. 添加已知的 IoC。 7. 运行分析并输出目录路径。 如果同时填写了上传和服务器路径，选定的源模式将控制 使用哪个输入。 当提供多个输入时，实时运行面板会显示收集 和关联计数，打开案例摘要预览，并链接案例级别的 输出和单次收集的主机摘要。 浏览器 API 使用每个进程的请求 token，并拒绝非环回的 Host 和 Origin 值。重启服务器会使打开的 GUI 页面失效，并使 先前的输出 URL 不可用；重新加载页面并从其文件系统输出目录 运行或重新打开相关案例。 ## 检测覆盖率 当前的覆盖率针对 Linux 入侵分流进行了调整： - 身份验证：SSH 暴力破解、无效用户、多次失败后的成功 登录、root 登录、登录历史导出、账户锁定/解锁事件和 密码更改 - 执行：Shell 历史命令、下载执行链、从 `/tmp`、`/var/tmp`、`/dev/shm` 和 `/run` 进行的分阶段执行、反向 Shell 语法和 进程列表信号 - 持久化：cron、systemd、rc.local、init.d、Shell 配置文件、不受限制的 SSH 授权密钥、LD_PRELOAD 和 PAM 后门候选 - 提权：UID 0 异常、sudoers 风险、NOPASSWD 条目、 特权组成员身份、SUID/SGID 文件、Linux capabilities、Docker/LXD 组风险和账户备份差异对比 - 凭据访问：SSH 密钥访问、凭据文件访问、本地密码哈希 元数据、弱哈希识别、历史记录中的明文密码泄露和 shadow 时间戳提取 - 横向移动：出站 SSH、SCP、rsync、known_hosts、网络探测和 未发现证据时的明确否定发现 - 数据窃取和工具：`rclone`、云 CLI、归档实用程序、数据库 转储、隧道工具、挖矿程序、破坏性命令和勒索软件影响 指标 - 审计和账户生命周期：auditd 账户事件、passwd/shadow/group 备份 比较、创建/删除/修改的账户、密码更改、账户 解锁和特权组添加 与攻击者相关的匹配只是技术提示。没有 独立威胁情报的支持，不要将其作为归因进行报告。 工具、TTP、恶意软件/payload 元数据和非归因性的攻击者相似性 配置文件合并在 `rules/tagging_registry.yml` 中。工具和 TTP 规则 在 runtime 丰富事件；攻击者配置文件优先考虑观察到的 信号组合，而不主张归因。注册表哈希保留在运行 清单中，以便分析师可以识别用于案例的确切检测内容。 欢迎社区补充内容。请参阅 [检测包贡献指南](rules/README.md) 并在提交前验证更改： ``` PYTHONPATH=. python3 -m uac_parser.rules_cli ``` ## 证据就绪情况 GUI 的 **Inspect Time Range** 操作还会报告跨 身份验证、审计、命令历史、网络状态、进程状态、账户、 持久化和文件系统类的证据就绪情况。缺失的类别是一个覆盖差距，而不是 否定发现。 仅当命令历史、网络状态和 SSH 主机历史证据可用时， TraceQuarry 才会报告未观察到横向移动证据。 否则，评估将被标记为不确定，并列出缺失的来源。 ## 发现验证手册 对于每个高影响发现： 1. 在 `timeline_mini.csv` 或 `timeline_full.csv` 中定位源事件。 2. 可用时，从提取的 UAC 内容中打开原始的 `source_path`。 3. 捕获原始行、前一行和后一行。 4. 确认时间戳类型：原生日志时间、bodyfile 时间、audit 时间或 关联时间戳。 5. 检查命令是由攻击者、管理员、 EDR/AV 进程还是防御性的 grep/search 命令执行的。 6. 在同一时间窗口内关联 SSH、sudo、进程、网络、账户、持久化和文件 时间线事件。 7. 在案例笔记中记录置信度和不确定性。 特别警告：TraceQuarry 尝试避免将防御性 `grep` 或 `rg` 指标搜索命令中 的可疑字符串视为已确认的 payload 执行。分析师在写下结论之前仍应验证上下文。 ## 报告指南 建议的经得起审查的报告用语： - “TraceQuarry 解析了 UAC 收集并生成了一个标准化时间线。” - “该发现表明与……一致的证据” - “在 `` 的 `` 中观察到了源代码行。” - “时间戳使用时区 `` 和日志年份 `` 进行了标准化。” - “这是一种技术相似性，不是归因。” - “仅在源覆盖率支持该陈述时，才使用” “在解析的源中未发现出站横向移动的证据”。 避免过度声明： - 如果操作仅出现在搜索、 注释、检测规则或扫描程序输出中，则不要声明发生了该操作。 - 如果缺少相关源，则不要声明没有发生任何活动。 - 不要仅凭 TTP 重叠就归因于知名的攻击者。 ## 安装 TraceQuarry 支持 Python 3.11 和 3.12。PyYAML 用于验证和加载 外部检测注册表。 ``` git clone https://github.com/Chill-Ethical-People/TraceQuarry.git cd tracequarry python3 -m venv .venv source .venv/bin/activate python3 -m pip install . ``` 您也可以使用 `PYTHONPATH` 直接从存储库根目录运行它： ``` cd tracequarry PYTHONPATH=. python3 -m uac_parser.cli tests/fixtures/uac_sample --out /tmp/tracequarry-sample ``` ## 许可证和所有权 TraceQuarry 在 Apache License, Version 2.0 下发布。您可以 在该许可证下使用、修改和重新分发软件，同时 Chill Ethical People 保留原始项目的版权所有权。 许可证涵盖软件。TraceQuarry 名称、徽标、组合标识、favicon、 品牌资产和 Chill Ethical People 标志仍是项目身份资产， 不授予用于不相关品牌宣传或背书的权利。有关 确切条款，请参阅 `LICENSE` 和 `NOTICE`。 欢迎在相同的 Apache-2.0 条款下做出贡献。不要贡献 真实的事件证据、凭据、客户数据或您无权 分享的第三方材料。在打开公开 issue 或 pull request 之前，请参阅 `CONTRIBUTING.md` 和 `SECURITY.md`。 ## 验证和分析师信心 TraceQuarry 使用内置的 fixture 证据和生成的合成 场景进行了验证。自动化测试套件涵盖： - 单收集和多收集案例流水线 - 时间线身份、来源、关联和预期的去重 - 威胁配置文件优先级和 IoC 丰富 - 归档遍历、成员大小和扩展限制保护 - 输出遍历、Host、Origin 和 CSRF 安全性回归 - 公开作业数据脱敏和严格的证据文件权限 - 过大的 HTTP 请求拒绝和解析器错误报告 CI 还针对 `requirements.txt` 中固定的生产依赖基线 运行 Snyk Open Source。计划的每周监视器会检查相同的基线 是否存在新披露的漏洞；上面的 Snyk 徽章反映了该工作流的 最新结果。Gitleaks 会在推送、 pull request、每周计划以及手动发布检查时扫描完整可达的 Git 历史。 这些检查建立了对实现的信心，而不是证据结论。 对于案例报告，请根据原始源代码行、 收集覆盖率、主机时区和事件窗口假设验证决定性的发现。将 任何解析器错误或缺失的来源作为限制记录在调查报告中。 ## 冒烟测试 在对案例证据使用更改后的解析器构建之前，请运行 fixture 冒烟测试： ``` cd tracequarry PYTHONPATH=. python3 -m uac_parser.cli tests/fixtures/uac_sample \ --out /tmp/tracequarry-smoke \ --incident-start 2026-06-16T09:58:00+08:00 \ --incident-end 2026-06-16T18:01:40+08:00 \ --year 2026 \ --timezone Asia/Hong_Kong ``` - 确认冒烟输出中存在预期的文件： ``` ls /tmp/tracequarry-smoke/timeline_full.csv \ /tmp/tracequarry-smoke/timeline_mini.csv \ /tmp/tracequarry-smoke/findings.json \ /tmp/tracequarry-smoke/source_index.json \ /tmp/tracequarry-smoke/parser_errors.log ``` 运行自动化的正确性、归档安全性、关联和流水线测试： ``` cd tracequarry PYTHONPATH=. python3 -m unittest discover -s tests -v ``` ## 发行版验证 GitHub 发行版包括源代码分发、wheel、CycloneDX SBOM 和 `SHA256SUMS`。在安装前验证下载的 artifact： ``` shasum -a 256 -c SHA256SUMS python3 -m pip install tracequarry-*.whl ``` 敏感的安全问题应通过 [GitHub Security Advisories](https://github.com/Chill-Ethical-People/TraceQuarry/security/advisories/new) 私下报告，或发送电子邮件至 [`contact@chillethicalpeople.com`](mailto:contact@chillethicalpeople.com)。 维护者在更改存储库可见性或发布 release tag 时应完成[公开发布检查清单](docs/public-release-checklist.md)。
标签：Python, 库, 应急响应, 数字取证, 无后门, 自动化脚本, 逆向工具