Tracehound

面向高速API的确定性运行时安全缓冲区

外部系统发出威胁信号。Tracehound保留证据。

网站 · 文档索引 · API参考 · 配置 · RFC · 安全 · 更新日志

Tracehound是一个无需决策的取证运行时，位于上游检测和下游响应之间。它不分类流量、不应用启发式规则、也不替代WAF。它接收明确的威胁信号，隔离证据，并保留防篡改的操作记录，而不会成为主机应用程序的新拒绝服务向量。

WAF是可能的上游权威来源之一，而非产品边界。Tracehound的证据路径可以由任何能够映射到scent.threat的明确外部威胁信号源驱动，包括反向代理、机器人管理、滥用检测器和内部风险服务，同时原生防护措施（如速率限制和有效载荷大小控制）继续独立运行。

此仓库包含开源的Tracehound基础组件：@tracehound/core、@tracehound/express、@tracehound/fastify 和 @tracehound/cli。当前工作集中在真实世界的开源验证、部署信心和操作员可用性上。

Tracehound保证的内容

无决策运行时：Tracehound从不判断流量是否恶意。上游系统提供威胁信号。
确定性行为：热路径中无机器学习、启发式或概率分支。
故障开放的主机安全：运行时故障不会使Tracehound变成应用层的拒绝服务向量。
无有效载荷的运行时膜：原始有效载荷字节保留在隔离边界内；运行时代码仅接收元数据句柄。
防篡改保管：证据生命周期事件通过AuditChain记录。
有限资源使用：隔离、速率限制、通知投递、猎犬队列和衰减工作流均有明确上限。

Tracehound不是什么

不是WAF、IDS、SIEM、RASP或威胁分类器
不是APM或请求分析平台
不是策略引擎或访问控制层
不是运行时应用程序代码的有效载荷检查服务

运行时模型

请求/事件
  -> 适配器提取Scent
  -> agent.intercept(scent)
     -> rate_limited        (429)
     -> clean               (通过)
     -> payload_too_large   (413)
     -> ignored             (重复签名，通过)
     -> quarantined         (403，仅元数据运行时句柄)
     -> error               (故障开放)

拦截状态

仓库范围

安装

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 会哈希原始入口字节而不是规范化的有效载荷字节

框架适配器

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 提供运行时状态、统计、实时观察输出和本地追踪检查工作流。

tracehound status
tracehound stats
tracehound inspect --trace-id <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 命令会明确失败，而不是编造健康运行时状态。

文档地图

开发

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

贡献与安全

许可证

Tracehound 使用 Apache-2.0 许可证。

`clean`	`Scent` 上无威胁信号	通过
`rate_limited`	来源超过有界滑动窗口限制	HTTP `429` + `Retry-After`
`payload_too_large`	有效载荷超过 `maxPayloadSize`	HTTP `413`
`ignored`	重复签名或压力下的确定性丢弃	通过
`quarantined`	证据成功存储	HTTP `403`
`error`	Tracehound内部故障	默认故障开放通过

入门	开始使用
API 接口	API 参考
运行时选项	配置参考
升级路径	重大变更
证据保管	证据生命周期策略
故障开放行为	故障开放规范
性能范围	性能 SLA
安全验证	安全保证
架构治理	RFC 索引
安全审查语料库	安全说明

`@tracehound/core`	安全引擎、证据生命周期、隔离、AuditChain、观察者、猎犬池、通知
`@tracehound/express`	轻量Express中间件适配器
`@tracehound/fastify`	轻量Fastify插件适配器
`@tracehound/cli`	CLI和终端检查工具

tracehound

最受欢迎