Tracewire

Tracewire turns recon/scan data and traffic/session logs into an interactive network graph, a replayable incident timeline, and a plain-English incident narrative.

It is a React frontend backed by a small Express server. The server holds the AI provider key, streams responses to the browser with Server-Sent Events, and serves the production build.

Features

• Upload recon/scan data and traffic/session logs separately or together
• Parse .pcap and .pcapng files directly in the browser
• Stream graph and timeline analysis token by token from the server
• Support Anthropic, Gemini, and OpenAI-compatible providers
• Use fallback provider settings if the primary provider fails
• Run locally with Vite during development or with Docker in production

Requirements

• Node.js 18.11 or newer
• npm
• An API key for at least one supported AI provider

Installation

1. Install dependencies

npm install

2. Create your environment file

cp .env.example .env

3. Configure the AI provider

Edit .env and set your primary provider credentials:

AI_API_KEY=your-key-here
AI_API_URL=https://api.anthropic.com/v1/messages
AI_MODEL=claude-sonnet-5
PORT=3001

The defaults in .env.example already point to Groq for convenience. You can change them to any supported provider.

Supported primary providers:

• Anthropic native: https://api.anthropic.com/v1/messages
• Gemini native: https://generativelanguage.googleapis.com/v1beta
• OpenAI-compatible chat endpoints: Groq, OpenAI, OpenRouter, Together AI, Ollama/LM Studio, GitHub Models, and similar services

If you use Gemini, set AI_API_URL to the base URL only. The server builds the streaming endpoint automatically from AI_MODEL.

4. Optional fallback provider

If you want a backup provider, set these too:

FALLBACK_AI_API_KEY=your-fallback-key-here
FALLBACK_AI_API_URL=https://models.github.ai/inference/chat/completions
FALLBACK_AI_MODEL=openai/gpt-4o-mini

Leave FALLBACK_AI_API_KEY unset to disable fallback.

Running locally

Tracewire uses two processes during development.

Terminal 1: backend server

npm run dev:server

This starts the Express server on http://localhost:3001.

Terminal 2: frontend

npm run dev

This starts Vite on http://localhost:5173 and proxies /api/* requests to the backend.

Open http://localhost:5173 in your browser.

Build and production run

npm run build
npm run server

You can also use the combined command:

npm start

That builds the frontend and then starts the Express server, which serves the built app from dist/.

Docker

docker build -t tracewire .
docker run -p 3001:3001 --env-file .env tracewire

Open http://localhost:3001 after the container starts.

Project structure

server/
  index.js        Express app with SSE endpoints and static file hosting
  aiClient.js     Server-side AI provider client with streaming + fallback
  prompts.js      Prompt builders for graph and timeline analysis
src/
  components/     React UI components
  lib/            Browser-side parsing, sample data, and shared types
public/           Static assets
Dockerfile        Production container build

API overview

The server exposes these endpoints:

• GET /api/health - health check and API key status
• POST /api/analyze/graph - streams graph analysis as SSE chunks
• POST /api/analyze/timeline - streams timeline analysis as SSE chunks

Both analyze endpoints expect JSON with reconData and/or trafficData. The timeline endpoint also accepts knownIds so graph and timeline nodes stay aligned.

Notes on packet capture support

Tracewire can parse .pcap and .pcapng files client-side into flow summaries. The first 500 packets are used to keep large uploads responsive. Plain-text formats such as .txt, .log, .csv, .json, .xml, and .nmap are also supported.

Deployment

This app needs a platform that can run a persistent Node process. A purely static host is not enough because the server holds the API key and streams model output.

Good deployment targets include Render, Railway, Fly.io, AWS App Runner, and any platform that can run the included Dockerfile.

Environment variables

Variable	Required	Purpose
AI_API_KEY	Yes	Primary provider API key
AI_API_URL	No	Primary provider endpoint
AI_MODEL	No	Primary provider model name
FALLBACK_AI_API_KEY	No	Backup provider API key
FALLBACK_AI_API_URL	No	Backup provider endpoint
FALLBACK_AI_MODEL	No	Backup provider model name
PORT	No	Server port, defaults to 3001

Stack

• React 19 + TypeScript + Vite
• Express
• Server-Sent Events
• Tailwind CSS v4
• Framer Motion
• d3-force
• lucide-react