TRACEHOUND

Deterministic Runtime Security Buffer for Modern Applications.

Tracehound Core is a deterministic and fail-open runtime security layer designed to operate between detection systems and operational response. It provides bounded ingestion, rate and buffer controls, controlled choke mechanisms, and reproducible event processing. The system does not classify threats or enforce policies. Instead, it guarantees controlled runtime behavior and integrity of the resulting event chain.

Documentation · Security Audit · Report Bug · Request Feature · FAQ

About the Project

Tracehound is a deterministic runtime security substrate. It doesn't use heuristics or "guess" if a request is malicious; instead, it acts as a high-integrity buffer for explicit security signals (Scents) from external detectors. By quarantining suspicious events and preserving them in a tamper-evident AuditChain, Tracehound ensures that security events are forever auditable without disrupting production traffic.

Why we built this

Modern security architectures often face a trade-off between "blocking and breaking" or "logging and losing" forensic details. We built Tracehound to solve the gap between real-time traffic and backend security analysis:

• Resilience: Fail-open semantics ensure security tooling never becomes a self-imposed DoS vector.
• Forensic Integrity: Tamper-evident AuditChain provides an immutable record of what actually happened, solving the "log tampering" problem.
• Decoupling: By trusting external logic for detection, Tracehound remains a lightweight, stable, and deterministic buffer that stays out of the way of your application logic.

---

Key Features

• Deterministic Security Buffer: No heuristics, no false positives. It only operates on explicit signals.
• Decision-Free Architecture: Trusts external detection logic, focusing on deterministic evidence handling and bounded ingestion safety.
• Fail-Open Semantics: Designed for high-velocity APIs where production availability is paramount.
• AuditChain: Merkle-chained, tamper-evident forensic logging of all security events.
• Bounded Runtime Controls: Size, queue, and timeout controls are enforced in core paths; performance envelope is deployment-dependent.
• Cold Storage Adapters: Automatic archival of evidence to S3, R2, or GCS.

---

Ecosystem

Tracehound is a monorepo containing several specialized packages:

Package	Purpose
@tracehound/core	The security substrate and runtime agent.
@tracehound/express	Official Express middleware for zero-code integration.
@tracehound/fastify	Official Fastify plugin for high-performance APIs.
@tracehound/cli	Evaluation runtime and forensic inspection tool.

---

Quick Start

Core Usage

import { createTracehound } from '@tracehound/core'

const tracehound = createTracehound({
  quarantine: { maxCount: 1000 },
  rateLimit: { windowMs: 60000, maxRequests: 100 },
})

// Intercept a potential threat signal (Scent)
const result = tracehound.agent.intercept({
  id: 'unique-id',
  timestamp: Date.now(),
  source: '127.0.0.1',
  payload: { path: '/api/v1/user', method: 'POST' },
})

if (result.status === 'quarantined') {
  console.log('Threat quarantined. Signature:', result.handle.signature)
}

Express Integration

import express from 'express'
import { createTracehound } from '@tracehound/core'
import { tracehound } from '@tracehound/express'

const app = express()
const th = createTracehound()

// Mount the middleware
app.use(tracehound({ agent: th.agent }))

app.get('/', (req, res) => res.send('Protected by Tracehound'))

Fastify Integration

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 })

---

Architecture

        External Detector (WAF, SIEM, ML)
                      │
                      ▼
┌───────────────────────────────────────────────┐
│                   TRACEHOUND                  │
├───────────────────────────────────────────────┤
│  Agent         → Traffic orchestrator         │
│  Quarantine    → Evidence buffer              │
│  AuditChain    → Tamper-evident log           │
│  HoundPool     → Process-separated analysis   │
│  Scheduler     → Jittered background          │
│  Notifications → Universal events             │
│  SecurityState → Unified metrics              │
└───────────────────────────────────────────────┘

---

Core Principles

1. Decision-free: Tracehound never decides if a request is malicious. It only acts on external decisions.
2. Detection is external: Use your existing WAF, SIEM, or ML engine to drive Tracehound.
3. Forensics > Visualization: Immutable evidence is our primary product, not pretty dashboards.
4. Local-First: Operates within your application runtime for low-latency interception and auditability.

---

Documentation

• Getting Started
• API & Configuration
• Evidence Lifecycle
• Security Assurance & Chaos Testing

---

Community

• Contributing: Establish clear pathways for contribution.
• Code of Conduct: Maintain a professional and inclusive community.
• Security Policy: Reporting vulnerabilities.

---

RFCs (Request for Comments)

Tracehound development is driven by the RFC process. See the docs/rfc directory for all active and planned proposals.

---

License

Tracehound is licensed under the Apache-2.0 License.