Runestone

Runestone is a local-first detection workflow assistant for blue teams and detection engineers. It helps turn security evidence into explainable ATT&CK-style mappings, defensive context, and validation cards that support analyst decisions.

This public README is intentionally concise. The public repository should show the workflow and value without publishing the full private rebuild packet, detailed roadmap, rule catalog, prompt strategy, or enterprise deployment plan.

Maintainer: @hcbomb

Stack

• Frontend: React, TypeScript, Vite, lucide icons
• Backend: Fastify, TypeScript, Node node:sqlite
• AI: optional local Ollama summary enrichment
• Persistence: local SQLite database under data/
• Outputs: analysis history, defensive context, validation cards, Navigator-style layer export

Architecture

flowchart LR
  Analyst["Detection engineer or blue team analyst"]
  UI["React UI<br/>localhost:5173"]
  API["Fastify API<br/>localhost:8787"]
  Parser["Evidence parser<br/>JSON, JSONL, CSV, raw text"]
  Rules["Public detection rules<br/>ATT&CK-style mappings"]
  Validation["Validation cards<br/>telemetry, candidate logic, decisions"]
  Store["SQLite history<br/>local data directory"]
  Ollama["Optional Ollama<br/>local summary only"]
  Export["Navigator-style layer export"]

  Analyst --> UI
  UI --> API
  API --> Parser
  Parser --> Rules
  Rules --> Validation
  Validation --> Store
  Validation --> Export
  API -. optional .-> Ollama

Loading

Quick Start

nvm use
npm install
cp .env.example .env
npm run dev

Open the Vite URL printed by the terminal, normally http://127.0.0.1:5173.

The API runs on http://127.0.0.1:8787 by default.

Ollama

Ollama is optional. The app always runs deterministic mapping rules first, then asks Ollama for a concise analyst summary only when the UI toggle is enabled.

ollama pull llama3.1:8b
ollama serve

Set these in .env if you want a different model or host:

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.1:8b

API

GET  /api/health
GET  /api/knowledge
GET  /api/analyses
GET  /api/analyses/:id
GET  /api/analyses/:id/navigator-layer
POST /api/analyze
POST /api/webhooks/splunk

Example manual analysis:

curl -s http://127.0.0.1:8787/api/analyze \
  -H 'content-type: application/json' \
  -d @samples/public-synthetic-evidence.json

Webhook

Set SPLUNK_WEBHOOK_TOKEN in .env, then configure a local SIEM-style webhook to POST JSON to:

http://127.0.0.1:8787/api/webhooks/splunk

Include this header:

x-runestone-token: <your token>

The API also accepts legacy x-detection-mapper-token for the same webhook token.

The webhook accepts any of these shapes:

{ "search_name": "name", "result": { "...": "..." } }
{ "search_name": "name", "results": [{ "...": "..." }] }
{ "events": [{ "...": "..." }] }

Use synthetic data for public demos.

Current POC Scope

Runestone currently focuses on the core detection workflow:

• Import a small evidence slice.
• Map relevant behavior.
• Review evidence and rationale.
• Generate validation guidance.
• Mark analyst decisions.
• Export or preserve the analysis locally.

Screenshots

Public Documentation

The public documentation packet lives in docs/public/README.md.

See System Impact for the current local footprint and BOTS data posture.

The private rebuild packet is intentionally not part of the public repository.

Repository Strategy

Recommended split:

• Public repo: workflow shell, public docs, synthetic samples, and public-safe examples.
• Private repo: full rebuild packet, detailed rules, private roadmap, enterprise strategy, prompts, evaluation plan, and internal notes.

Before publishing code publicly, review rule logic and sample data. Source code can expose as much project IP as documentation.

Development Checks

Run:

npm run check

Additional security-oriented checks:

npm run security:audit
npm run sbom

See Security and Quality Checks for the public CI and repository hygiene baseline.

Generated private PDF deliverables are ignored by default for public publishing.