{"id":44760696,"url":"https://github.com/tracehound/tracehound","last_synced_at":"2026-03-12T00:07:58.175Z","repository":{"id":342035013,"uuid":"1172024307","full_name":"tracehound/tracehound","owner":"tracehound","description":"Operational security controls with forensic guarantees","archived":false,"fork":false,"pushed_at":"2026-03-10T01:11:24.000Z","size":1802,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T01:39:52.162Z","etag":null,"topics":["audit-trail","cybersecurity","deterministic","fail-open","forensics","runtime-security","security","security-buffer","tamper-evident"],"latest_commit_sha":null,"homepage":"https://tracehoundlabs.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tracehound.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap/ENHANCED-QUARANTINE-PROTOCOL.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["laphilosophia"],"open_collective":"erdem-arslan","thanks_dev":"gh/tracehound"}},"created_at":"2026-03-03T21:39:19.000Z","updated_at":"2026-03-09T20:35:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tracehound/tracehound","commit_stats":null,"previous_names":["tracehound/tracehound"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/tracehound/tracehound","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tracehound%2Ftracehound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tracehound%2Ftracehound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tracehound%2Ftracehound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tracehound%2Ftracehound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tracehound","download_url":"https://codeload.github.com/tracehound/tracehound/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tracehound%2Ftracehound/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30404072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T21:51:19.558Z","status":"ssl_error","status_checked_at":"2026-03-11T21:50:57.892Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit-trail","cybersecurity","deterministic","fail-open","forensics","runtime-security","security","security-buffer","tamper-evident"],"created_at":"2026-02-16T02:26:48.624Z","updated_at":"2026-03-12T00:07:58.169Z","avatar_url":"https://github.com/tracehound.png","language":"TypeScript","readme":"![Tracehound](.github/assets/tracehound-banner.jpg)\n\n\u003cdiv align=\"center\"\u003e\n\n**Deterministic runtime security buffer for high-velocity APIs**\n\n**External systems signal threats. Tracehound preserves evidence.**\n\n[![Advanced CodeQL Analysis](https://github.com/tracehound/tracehound/actions/workflows/codeql-advanced.yml/badge.svg?branch=main)](https://github.com/tracehound/tracehound/actions/workflows/codeql-advanced.yml)\n[![Semgrep Security Analysis](https://github.com/tracehound/tracehound/actions/workflows/semgrep.yml/badge.svg)](https://github.com/tracehound/tracehound/actions/workflows/semgrep.yml)\n[![Codecov](https://github.com/tracehound/tracehound/actions/workflows/codecov.yml/badge.svg)](https://github.com/tracehound/tracehound/actions/workflows/codecov.yml)\n[![OpenSSF Scorecard](https://github.com/tracehound/tracehound/actions/workflows/scorecard.yml/badge.svg)](https://github.com/tracehound/tracehound/actions/workflows/scorecard.yml)\n[![Paranoid Validation](https://github.com/tracehound/tracehound/actions/workflows/security-paranoid.yml/badge.svg?branch=main)](https://github.com/tracehound/tracehound/actions/workflows/security-paranoid.yml)\n[![License: Apache2.0](https://img.shields.io/badge/License-Apache2.0-blue.svg)](https://opensource.org/license/apache-2-0)\n[![npm](https://img.shields.io/npm/v/@tracehound/core.svg)](https://www.npmjs.com/package/@tracehound/core)\n\n[Website](https://tracehoundlabs.com) · [Documentation Index](./docs/README.md) · [API Reference](./docs/API.md) · [Configuration](./docs/CONFIGURATION.md) · [RFCs](./docs/rfc/README.md) · [Security](./security/readme.md) · [Changelog](./CHANGELOG.md)\n\n\u003c/div\u003e\n\nTracehound is a decision-free forensic runtime that sits between upstream detection and downstream response. It does not classify traffic, apply heuristics, or replace a WAF. It receives explicit threat signals, quarantines evidence, and preserves a tamper-evident operational record without becoming a new denial-of-service vector for the host application.\n\nWAFs are one possible upstream authority, not the product boundary. Tracehound’s evidence path can be driven by any explicit external threat signal source that can be mapped into `scent.threat`, including reverse proxies, bot-management systems, abuse detectors, and internal risk services, while native guardrails such as rate limiting and payload-size controls continue to operate independently.\n\nThis repository contains the open-source Tracehound substrate: `@tracehound/core`, `@tracehound/express`, `@tracehound/fastify`, and `@tracehound/cli`. Current work is centered on real-world OSS validation, deployment confidence, and operator usability.\n\n## What Tracehound Guarantees\n\n- **Decision-free runtime**: Tracehound never decides whether traffic is malicious. Upstream systems provide the threat signal.\n- **Deterministic behavior**: No ML, heuristics, or probabilistic branching in the hot path.\n- **Fail-open host safety**: Runtime faults do not turn Tracehound into an application-layer DoS vector.\n- **Payload-less runtime membrane**: Raw payload bytes stay inside the quarantine boundary; runtime code receives metadata-only handles.\n- **Tamper-evident custody**: Evidence lifecycle events are recorded through `AuditChain`.\n- **Bounded resource use**: Quarantine, rate limiting, notification delivery, hound queues, and decay workflows have explicit caps.\n\n## What Tracehound Is Not\n\n- Not a WAF, IDS, SIEM, RASP, or threat classifier\n- Not an APM or request analytics platform\n- Not a policy engine or access-control layer\n- Not a payload-inspection service for runtime application code\n\n## Runtime Model\n\n```text\nRequest/Event\n  -\u003e Adapter extracts Scent\n  -\u003e agent.intercept(scent)\n     -\u003e rate_limited        (429)\n     -\u003e clean               (pass through)\n     -\u003e payload_too_large   (413)\n     -\u003e ignored             (duplicate signature, pass through)\n     -\u003e quarantined         (403, metadata-only runtime handle)\n     -\u003e error               (fail-open)\n```\n\n### Intercept Statuses\n\n| Status              | Meaning                                                  | Default adapter behavior          |\n| :------------------ | :------------------------------------------------------- | :-------------------------------- |\n| `clean`             | No threat signal on the `Scent`                          | Pass through                      |\n| `rate_limited`      | Source exceeded bounded sliding-window limits            | HTTP `429` + `Retry-After`        |\n| `payload_too_large` | Payload exceeded `maxPayloadSize`                        | HTTP `413`                        |\n| `ignored`           | Duplicate signature or deterministic drop under pressure | Pass through                      |\n| `quarantined`       | Evidence stored successfully                             | HTTP `403`                        |\n| `error`             | Internal Tracehound failure                              | Fail-open pass through by default |\n\n## Repository Scope\n\n| Package                                     | Role                                                                                            |\n| :------------------------------------------ | :---------------------------------------------------------------------------------------------- |\n| [`@tracehound/core`](./packages/core)       | Security engine, evidence lifecycle, quarantine, AuditChain, watcher, hound pool, notifications |\n| [`@tracehound/express`](./packages/express) | Thin Express middleware adapter                                                                 |\n| [`@tracehound/fastify`](./packages/fastify) | Thin Fastify plugin adapter                                                                     |\n| [`@tracehound/cli`](./packages/cli)         | CLI and terminal inspection tooling                                                             |\n\n## Installation\n\n```bash\npnpm add @tracehound/core\npnpm add @tracehound/core @tracehound/express\npnpm add @tracehound/core @tracehound/fastify\npnpm add -g @tracehound/cli\n```\n\nRequirements:\n\n- Node.js `\u003e=20`\n- `pnpm` workspace tooling for repository development\n\n## Quick Start\n\n```ts\nimport { createTracehound, generateSecureId, type Scent } from '@tracehound/core'\n\nconst th = createTracehound({\n  maxPayloadSize: 1_000_000,\n  quarantine: {\n    maxCount: 10_000,\n    maxBytes: 100_000_000,\n  },\n  rateLimit: {\n    windowMs: 60_000,\n    maxRequests: 100,\n  },\n})\n\nconst scent: Scent = {\n  id: generateSecureId(),\n  timestamp: Date.now(),\n  source: {\n    ip: '203.0.113.10',\n    userAgent: 'curl/8.7.1',\n  },\n  payload: {\n    method: 'POST',\n    path: '/api/login',\n    body: { username: 'alice' },\n  },\n  threat: {\n    category: 'injection',\n    severity: 'high',\n  },\n}\n\nconst result = th.agent.intercept(scent)\n\nif (result.status === 'quarantined') {\n  console.log(result.handle.signature)\n  console.log(result.handle.membrane) // metadata_only\n}\n\nth.shutdown()\n```\n\nNotes:\n\n- `Scent.source` is a structured object: `{ ip, userAgent?, tls? }`\n- `Scent.payload` must be JSON-serializable\n- If `ingressBytes` is present, Tracehound hashes raw ingress bytes instead of canonicalized payload bytes\n\n## Framework Adapters\n\n### Express\n\n```ts\nimport { Buffer } from 'node:buffer'\nimport express from 'express'\nimport { createTracehound } from '@tracehound/core'\nimport { tracehound } from '@tracehound/express'\n\nconst app = express()\nconst th = createTracehound()\n\napp.use(\n  express.json({\n    verify: (req, _res, buf) =\u003e {\n      Reflect.set(req, 'rawBody', Buffer.from(buf))\n    },\n  }),\n)\n\napp.use(\n  tracehound({\n    agent: th.agent,\n    emitTraceIdHeader: true,\n  }),\n)\n```\n\n### Fastify\n\n```ts\nimport fastify from 'fastify'\nimport { createTracehound } from '@tracehound/core'\nimport { tracehoundPlugin } from '@tracehound/fastify'\n\nconst app = fastify()\nconst th = createTracehound()\n\napp.register(tracehoundPlugin, {\n  agent: th.agent,\n  emitTraceIdHeader: true,\n})\n```\n\nAdapter notes:\n\n- Express and Fastify adapters are intentionally thin and carry no security decision logic\n- For deterministic ingress-byte signatures, set `rawBody` before Tracehound runs\n- `emitTraceIdHeader` is optional and enables `x-tracehound-trace-id` for local inspection workflows\n- `@tracehound/fastify` uses the named export `tracehoundPlugin`\n\n## CLI and Operational Snapshots\n\nTracehound CLI provides runtime status, stats, live watch output, and local trace inspection workflows.\n\n```bash\ntracehound status\ntracehound stats\ntracehound inspect --trace-id \u003ctrace-id\u003e\ntracehound watch\ntracehound history clear\ntracehound disk clear\n```\n\n`status`, `stats`, and `watch` require a signed runtime snapshot. Configure snapshot export in the application runtime:\n\n```ts\nimport { createTracehound } from '@tracehound/core'\n\nconst th = createTracehound({\n  snapshot: {\n    path: '/var/run/tracehound/system-snapshot.json',\n    secret: process.env.TRACEHOUND_SNAPSHOT_SECRET,\n    intervalMs: 1000,\n  },\n})\n```\n\n```bash\nexport TRACEHOUND_SYSTEM_SNAPSHOT_PATH=/var/run/tracehound/system-snapshot.json\nexport TRACEHOUND_SNAPSHOT_SECRET=replace-me\nexport TRACEHOUND_SNAPSHOT_MAX_AGE_MS=5000\nexport TRACEHOUND_SNAPSHOT_MAX_FUTURE_SKEW_MS=5000\n```\n\nIf snapshot input is missing, stale, tampered, or unverifiable, CLI commands fail explicitly instead of fabricating healthy runtime state.\n\n## Documentation Map\n\n| Area                    | Document                                                         |\n| :---------------------- | :--------------------------------------------------------------- |\n| Onboarding              | [Getting Started](./docs/GETTING-STARTED.md)                     |\n| API surface             | [API Reference](./docs/API.md)                                   |\n| Runtime options         | [Configuration Reference](./docs/CONFIGURATION.md)               |\n| Upgrade path            | [Breaking Changes](./docs/BREAKING-CHANGES.md)                   |\n| Evidence custody        | [Evidence Lifecycle Policy](./docs/EVIDENCE-LIFECYCLE-POLICY.md) |\n| Fail-open behavior      | [Fail-Open Spec](./docs/FAIL-OPEN-SPEC.md)                       |\n| Performance envelope    | [Performance SLA](./docs/PERFORMANCE-SLA.md)                     |\n| Security validation     | [Security Assurance](./docs/SECURITY-ASSURANCE.md)               |\n| Architecture governance | [RFC Index](./docs/rfc/README.md)                                |\n| Security review corpus  | [Security Readme](./security/readme.md)                          |\n\n## Development\n\n```bash\npnpm build\npnpm test\npnpm test:coverage\npnpm lint\npnpm validate:paranoid\n```\n\nPer-package examples:\n\n```bash\npnpm --filter @tracehound/core test\npnpm --filter @tracehound/express test\npnpm --filter @tracehound/fastify test\npnpm --filter @tracehound/cli test\n```\n\n## Contributing and Security\n\n- [Contributing Guide](./CONTRIBUTING.md)\n- [Security Policy](./SECURITY.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n\n## License\n\nTracehound is licensed under the [Apache-2.0 License](./LICENSE).\n","funding_links":["https://github.com/sponsors/laphilosophia","https://opencollective.com/erdem-arslan","https://thanks.dev/gh/tracehound"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftracehound%2Ftracehound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftracehound%2Ftracehound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftracehound%2Ftracehound/lists"}