ABE — Database Specification (SQLite)

Rationale

File-based storage loses all data on container restart. SQLite requires zero extra services and is perfect for self-hosted deployment.

Library

Use better-sqlite3 (synchronous, faster than async alternatives for this use case).

Location

Database file: data/abe.db (persisted via Docker volume)

Schema

Table: sessions

CREATE TABLE IF NOT EXISTS sessions (
  id TEXT PRIMARY KEY,
  url TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'running',
  seed INTEGER NOT NULL,
  max_states INTEGER NOT NULL DEFAULT 50,
  states_visited INTEGER NOT NULL DEFAULT 0,
  anomalies_found INTEGER NOT NULL DEFAULT 0,
  started_at INTEGER NOT NULL,
  finished_at INTEGER,
  config_json TEXT NOT NULL DEFAULT '{}'
);

Table: states

CREATE TABLE IF NOT EXISTS states (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL REFERENCES sessions(id),
  url TEXT NOT NULL,
  title TEXT NOT NULL,
  dom_snapshot_path TEXT,
  visit_count INTEGER NOT NULL DEFAULT 0,
  discovered_at INTEGER NOT NULL
);

Table: actions

CREATE TABLE IF NOT EXISTS actions (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL REFERENCES sessions(id),
  state_id TEXT NOT NULL REFERENCES states(id),
  type TEXT NOT NULL,
  selector TEXT,
  value TEXT,
  url TEXT,
  seed INTEGER NOT NULL,
  executed_at INTEGER NOT NULL,
  sequence_order INTEGER NOT NULL
);

Table: anomalies

CREATE TABLE IF NOT EXISTS anomalies (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL REFERENCES sessions(id),
  type TEXT NOT NULL,
  severity TEXT NOT NULL,
  description TEXT NOT NULL,
  action_trace_json TEXT NOT NULL,
  evidence_json TEXT NOT NULL,
  screenshot_path TEXT,
  dom_snapshot_path TEXT,
  detected_at INTEGER NOT NULL
);

Table: notifications

CREATE TABLE IF NOT EXISTS notifications (
  id TEXT PRIMARY KEY,
  anomaly_id TEXT NOT NULL REFERENCES anomalies(id),
  channel TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  sent_at INTEGER,
  error TEXT
);

Repository Pattern

Create src/db/ with:

src/db/connection.ts — singleton SQLite connection, runs migrations on startup
src/db/SessionRepository.ts — CRUD for sessions
src/db/AnomalyRepository.ts — CRUD for anomalies, includes filter by session/severity
src/db/migrations.ts — runs all CREATE TABLE IF NOT EXISTS on startup

Rules

All DB operations are synchronous (better-sqlite3 is sync)
Repositories are injected into the API server, never imported directly by core engine
The engine emits events → the API server listens and persists to DB

2.6 KiB Raw Permalink Blame History