tracehound/tracehound

 Tracehound 是一个无决策的取证运行时，位于上游检测与下游响应之间。它不对流量进行分类，不应用启发式规则，也不替代 WAF。它接收明确的威胁信号，隔离证据，并维护防篡改的操作记录，同时不会成为宿主应用程序的全新拒绝服务攻击向量。 WAF 是一种可能的上游授权方，而不是产品的边界。Tracehound 的证据路径可以由任何能够映射到 `scent.threat` 的明确外部威胁信号源驱动，包括反向代理、Bot 管理系统、滥用检测器和内部风险服务，同时原生的防护机制（如速率限制和 payload 大小控制）仍会继续独立运行。 本仓库包含开源的 Tracehound 基础组件：`@tracehound/core`、`@tracehound/express`、`@tracehound/fastify` 和 `@tracehound/cli`。目前的工作重心在于真实世界的 OSS 验证、部署置信度以及运维人员可用性。 ## Tracehound 的保证 - **无决策运行时**：Tracehound 从不决定流量是否为恶意流量。威胁信号由上游系统提供。 - **确定性行为**：在热路径中没有 ML（机器学习）、启发式算法或概率性分支。 - **故障开放的宿主安全性**：运行时故障不会使 Tracehound 变成应用层的 DoS 攻击向量。 - **无 payload 的运行时屏障**：原始 payload 字节保留在隔离边界内；运行时代码仅接收元数据句柄。 - **防篡改的监管链**：证据生命周期事件通过 `AuditChain` 进行记录。 - **有界的资源使用**：隔离、速率限制、通知交付、hound 队列和衰减工作流都具有明确的限制。 ## Tracehound 不是什么 - 不是 WAF、IDS、SIEM、RASP 或威胁分类器 - 不是 APM 或请求分析平台 - 不是策略引擎或访问控制层 - 不是用于运行时应用代码的 payload 检查服务 ## 运行时模型 ``` Request/Event -> Adapter extracts Scent -> agent.intercept(scent) -> rate_limited (429) -> clean (pass through) -> payload_too_large (413) -> ignored (duplicate signature, pass through) -> quarantined (403, metadata-only runtime handle) -> error (fail-open) ``` ### 拦截状态 | 状态 | 含义 | 默认适配器行为 | | :------------------ | :------------------------------------------------------- | :-------------------------------- | | `clean` | `Scent` 上没有威胁信号 | 直接放行 | | `rate_limited` | 来源超出了有界的滑动窗口限制 | HTTP `429` + `Retry-After` | | `payload_too_large` | Payload 超过了 `maxPayloadSize` | HTTP `413` | | `ignored` | 重复签名或在压力下的确定性丢弃 | 直接放行 | | `quarantined` | 证据存储成功 | HTTP `403` | | `error` | 内部 Tracehound 故障 | 默认为故障开放直接放行 | ## 仓库范围 | 包 | 角色 | | :------------------------------------------ | :---------------------------------------------------------------------------------------------- | | [`@tracehound/core`](./packages/core) | 安全引擎、证据生命周期、隔离、AuditChain、监视器、hound 池、通知 | | [`@tracehound/express`](./packages/express) | 轻量级 Express 中间件适配器 | | [`@tracehound/fastify`](./packages/fastify) | 轻量级 Fastify 插件适配器 | | [`@tracehound/cli`](./packages/cli) | CLI 和终端检查工具 | ## 安装 ``` pnpm add @tracehound/core pnpm add @tracehound/core @tracehound/express pnpm add @tracehound/core @tracehound/fastify pnpm add -g @tracehound/cli ``` 要求： - Node.js `>=20` - 用于仓库开发的 `pnpm` 工作区工具 ## 快速开始 ``` import { createTracehound, generateSecureId, type Scent } from '@tracehound/core' const th = createTracehound({ maxPayloadSize: 1_000_000, quarantine: { maxCount: 10_000, maxBytes: 100_000_000, }, rateLimit: { windowMs: 60_000, maxRequests: 100, }, }) const scent: Scent = { id: generateSecureId(), timestamp: Date.now(), source: { ip: '203.0.113.10', userAgent: 'curl/8.7.1', }, payload: { method: 'POST', path: '/api/login', body: { username: 'alice' }, }, threat: { category: 'injection', severity: 'high', }, } const result = th.agent.intercept(scent) if (result.status === 'quarantined') { console.log(result.handle.signature) console.log(result.handle.membrane) // metadata_only } th.shutdown() ``` 备注： - `Scent.source` 是一个结构化对象：`{ ip, userAgent?, tls? }` - `Scent.payload` 必须可序列化为 JSON - 如果存在 `ingressBytes`，Tracehound 将对原始入口字节进行哈希处理，而不是对规范化的 payload 字节 ## 框架适配器 ### Express ``` import { Buffer } from 'node:buffer' import express from 'express' import { createTracehound } from '@tracehound/core' import { tracehound } from '@tracehound/express' const app = express() const th = createTracehound() app.use( express.json({ verify: (req, _res, buf) => { Reflect.set(req, 'rawBody', Buffer.from(buf)) }, }), ) app.use( tracehound({ agent: th.agent, emitTraceIdHeader: true, }), ) ``` ### Fastify ``` import fastify from 'fastify' import { createTracehound } from '@tracehound/core' import { tracehoundPlugin } from '@tracehound/fastify' const app = fastify() const th = createTracehound() app.register(tracehoundPlugin, { agent: th.agent, emitTraceIdHeader: true, }) ``` 适配器说明： - Express 和 Fastify 适配器被有意设计为轻量级，不携带任何安全决策逻辑 - 对于确定性的入口字节签名，请在 Tracehound 运行前设置 `rawBody` - `emitTraceIdHeader` 是可选的，它为本地检查工作流启用了 `x-tracehound-trace-id` - `@tracehound/fastify` 使用命名导出 `tracehoundPlugin` ## CLI 和操作快照 Tracehound CLI 提供运行时状态、统计信息、实时监视输出以及本地 trace 检查工作流。 ``` tracehound status tracehound stats tracehound inspect --trace-id tracehound watch tracehound history clear tracehound disk clear ``` `status`、`stats` 和 `watch` 需要经过签名的运行时快照。请在应用运行时配置快照导出： ``` import { createTracehound } from '@tracehound/core' const th = createTracehound({ snapshot: { path: '/var/run/tracehound/system-snapshot.json', secret: process.env.TRACEHOUND_SNAPSHOT_SECRET, intervalMs: 1000, }, }) ``` ``` export TRACEHOUND_SYSTEM_SNAPSHOT_PATH=/var/run/tracehound/system-snapshot.json export TRACEHOUND_SNAPSHOT_SECRET=replace-me export TRACEHOUND_SNAPSHOT_MAX_AGE_MS=5000 export TRACEHOUND_SNAPSHOT_MAX_FUTURE_SKEW_MS=5000 ``` 如果快照输入缺失、过期、被篡改或无法验证，CLI 命令将明确报错，而不是伪造健康的运行时状态。 ## 文档导航 | 区域 | 文档 | | :---------------------- | :--------------------------------------------------------------- | | 入门指引 | [入门指南](./docs/GETTING-STARTED.md) | | API 接口 | [API 参考](./docs/API.md) | | 运行时选项 | [配置参考](./docs/CONFIGURATION.md) | | 升级路径 | [破坏性变更](./docs/BREAKING-CHANGES.md) | | 证据监管 | [证据生命周期策略](./docs/EVIDENCE-LIFECYCLE-POLICY.md) | | 故障开放行为 | [故障开放规范](./docs/FAIL-OPEN-SPEC.md) | | 性能指标 | [性能 SLA](./docs/PERFORMANCE-SLA.md) | | 安全验证 | [安全保证](./docs/SECURITY-ASSURANCE.md) | | 架构治理 | [RFC 索引](./docs/rfc/README.md) | | 安全审查语料 | [安全自述文件](./security/readme.md) | ## 开发 ``` pnpm build pnpm test pnpm test:coverage pnpm lint pnpm validate:paranoid ``` 各包示例： ``` pnpm --filter @tracehound/core test pnpm --filter @tracehound/express test pnpm --filter @tracehound/fastify test pnpm --filter @tracehound/cli test ``` ## 贡献与安全 - [贡献指南](./CONTRIBUTING.md) - [安全策略](./SECURITY.md) - [行为准则](./CODE_OF_CONDUCT.md) ## 许可证 Tracehound 基于 [Apache-2.0 许可证](./LICENSE) 授权。

标签：API安全, CISA项目, Cloudflare, CodeQL, DevSecOps, GNU通用公共许可证, IPS, IP 地址批量处理, JSON输出, MITM代理, MITRE ATT&CK, Node.js, npm包, Semgrep, WAF辅助, WordPress安全扫描, 上游代理, 中间件, 取证保证, 威胁情报, 威胁检测与响应, 安全合规, 安全缓冲, 安全评估工具, 开发者工具, 操作安全, 数字取证, 确定性运行时, 网络代理, 网络流量分析, 自动化攻击, 自动化脚本, 证据保全, 防篡改记录, 高并发API