muxover/deeptrace

# DeepTrace DeepTrace 是一个用于 Cursor 和 Claude Code 的 agent 技能。大多数代码审查只是粗略浏览文本，并猜测运行时会发生什么。DeepTrace 让 agent 转而去观察。它会映射项目、运行项目，并追踪实际的执行情况，然后再得出结论。该技能附带了一些小工具：一个项目扫描器、一个测试和构建运行器，以及用于 Python、JavaScript、Go 和 Rust 的运行时追踪器。由于有了这些工具，调查结果来源于真实的行为，而不是代码的阅读理解，并且报告每次都遵循相同的结构。 ## 功能 - 映射、运行并追踪真实项目，而不是仅仅阅读粘贴的代码片段。 - 通过六个级别的分析进行工作，从基础逻辑一直到真实故障。 - 逐步分析执行过程：输入、状态更改、输出以及发生中断的位置。 - 从开发者、用户、攻击者以及高负载的角度来阅读代码。 - 会指出“在提供的上下文中未定义”，而不是凭空捏造它无法看到的行为。 - 以固定格式报告调查结果，包含严重程度和置信度评分。 - 包含四个可选的附加技能，分别用于安全性、性能、UI 状态和 API。 ## 工作原理 每次分析都试图达到六个级别的深度： 1. 语法和直接逻辑 2. 控制流 3. 状态和数据流 4. 边缘情况 5. 系统压力 6. 真实世界故障模拟 它追踪实际运行的内容，而不是进行抽象的描述： ``` flowchart LR input[Input enters system] --> exec[Step-by-step execution] exec --> state[State changes tracked] state --> output[Output generated] output --> fail[Failure points identified] ``` 如果多个组件相互通信，它也会跟踪它们之间的流程。 ## 工具包 在真实项目中，agent 会运行这些工具并读取它们的输出。它们是纯粹的 Python 脚本，无需安装任何东西。 - `recon.py` 扫描项目并报告其技术栈、语言、入口点、最大的文件以及 TODO/FIXME 注释。 - `run.py` 查找并运行项目的测试、构建或应用程序（Python、Node、Go、Rust 或 Make），并捕获输出和退出代码。传递 `--dry-run` 可以先查看命令。 - `trace.py` 在 `sys.settrace` 下运行 Python 入口点，并记录调用图、异常及其生成的任何线程。 - `trace-node.js` 在 V8 profiler 下运行 Node 或 JS 入口点，并打印调用树和最耗时的函数。 - `trace-go.py` 使用 Delve 追踪程序或测试中的 Go 函数调用。 - `trace-rust.py` 使用 `cargo flamegraph` 对 Rust 二进制文件或测试进行性能分析，并在未安装 profiler 时回退到 backtrace 运行。 Python、JavaScript、Go 和 Rust 是一等公民。对于其他任何语言，agent 会驱动该语言自己的 tracer；请参阅 [skills/deeptrace/scripts/reference.md](skills/deeptrace/scripts/reference.md)。运行器会执行你的代码，因此仅将其指向你信任的代码。 ## 示例 每个示例都是采用七部分输出格式的完整分析： - [race-condition.md](examples/race-condition.md)：一个 check-then-act 的并发 bug。 - [security-sql-injection.md](examples/security-sql-injection.md)：注入和身份验证绕过。 - [performance-n-plus-one.md](examples/performance-n-plus-one.md)：N+1 查询性能爆炸。 - [ui-stale-closure.md](examples/ui-stale-closure.md)：React stale-closure 导致的冻结。 - [api-idempotency.md](examples/api-idempotency.md)：重试时导致的重复扣费。 ## 安装 每个技能都有自己的文件夹。将你想要的技能复制到你的技能目录中。 Cursor（个人，所有项目）： ``` cp -r skills/deeptrace ~/.cursor/skills/deeptrace ``` Cursor（项目，通过 repo 共享）： ``` cp -r skills/deeptrace .cursor/skills/deeptrace ``` Claude Code：以相同的方式将技能文件夹放在你的 Claude Code 技能目录下。 通过替换文件夹名称来安装任何扩展技能，例如 `skills/deeptrace-security`。 ## 用法 要求 agent 进行调试、审计或追踪某些内容，核心的 `deeptrace` 技能就会自动加载。附加技能仅在你指名时加载，例如“在这个 handler 上使用 deeptrace-security”。 ## 技能 - `deeptrace`：用于追踪、边缘情况和故障的核心技能。自动加载。 - `deeptrace-security`：注入、身份验证绕过、输入模糊测试、泄露的密钥。 - `deeptrace-performance`：复杂度、分配、N+1 查询、锁争用、扩展性。 - `deeptrace-ui-simulation`：渲染和状态转换、异步 UI 竞争、陈旧状态。 - `deeptrace-api-audit`：请求和响应结构、状态代码、幂等性、错误契约。 ## 项目布局 ``` DeepTrace/ ├── README.md This file ├── LICENSE MIT license ├── CONTRIBUTING.md Contributor guide ├── .gitignore Ignored paths ├── .editorconfig Editor defaults ├── .markdownlint.json Markdown lint rules ├── pyproject.toml Ruff + pytest config ├── requirements-dev.txt Dev dependencies (pytest, ruff) ├── .github/ │ ├── PULL_REQUEST_TEMPLATE.md PR template │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md Bug report form │ │ └── feature_request.md Feature request form │ └── workflows/ │ └── ci.yml Markdown lint on push and PR ├── tests/ Pytest suite for the toolkit ├── examples/ │ ├── race-condition.md Concurrency trace │ ├── security-sql-injection.md Security audit trace │ ├── performance-n-plus-one.md Performance trace │ ├── ui-stale-closure.md UI state trace │ └── api-idempotency.md API audit trace └── skills/ ├── deeptrace/ Core engine │ ├── SKILL.md Spec + active investigation workflow │ └── scripts/ │ ├── recon.py Static project map │ ├── run.py Polyglot test/build/run runner │ ├── trace.py Python runtime tracer │ ├── trace-node.js Node/JS runtime tracer │ ├── trace-go.py Go runtime tracer (Delve) │ ├── trace-rust.py Rust runtime tracer (flamegraph) │ └── reference.md Tool usage + cross-language tracing ├── deeptrace-security/SKILL.md Security and abuse focus ├── deeptrace-performance/SKILL.md Performance and scaling focus ├── deeptrace-ui-simulation/SKILL.md UI state focus └── deeptrace-api-audit/SKILL.md API contract focus ``` ## 支持矩阵 推理适用于任何语言。其工具对 Python、JavaScript、Go 和 Rust 提供一等支持，对于其他语言则回退到每种语言各自的工具。 | 功能 | 一等支持 | 通过原生工具（agent 驱动） | 未覆盖 | |------------|-------------|----------------------------------|-------------| | 静态映射 (`recon.py`) | 约 20 种语言，12 种 manifests | 任何文本文件 | 语义/调用图分析 | | 运行测试/构建 (`run.py`) | Python, Go, JS, Rust, Make | 任何 `Makefile` target | Bazel、自定义工具链、仅限 Docker 的设置 | | 运行时追踪 | Python (`trace.py`), JS (`trace-node.js`), Go (`trace-go.py`), Rust (`trace-rust.py`) | JVM, Ruby（通过 profilers） | PHP、C/C++、C# 深度追踪 | Go 追踪需要 Delve，而 Rust 调用栈性能分析需要 `cargo flamegraph`。两者都会被自动检测，并且当缺少 profiler 时，Rust 仍然可以使用 backtrace 回退机制运行。这里没有沙盒，没有性能分析仪表板，没有运行时竞争检测器，也没有数据库或网络检查。运行器会在你的机器上执行真实的代码。 ## 局限性 DeepTrace 是一个带有一些辅助工具的推理技能，而不是完整的 debugger 或静态分析器。运行器会执行真实的项目代码，因此请仅在你信任且运行安全的代码上使用它。确定性的逐行追踪仅适用于 Python；其他语言使用采样 profilers 或它们自己的 tracers，这可能会遗漏非常短暂的调用。分析的质量仅取决于它所看到的代码和输出，而置信度评分是模型自身的估计，而不是测量结果。在根据其发现采取行动之前，请进行检查。 ## 许可证 根据 [MIT](LICENSE) 许可证授权。 ## 链接 - Repository: https://github.com/muxover/deeptrace - Issues: https://github.com/muxover/deeptrace/issues

Made with ❤️ by Jax (@muxover)

标签：AI智能体, MITM代理, SOC Prime, 云安全监控, 代码调试, 可视化界面, 开发工具, 数据可视化, 日志审计, 运行时追踪, 逆向工具, 静态分析