@reneturcios/tracewatch 0.0.0-stage → 0.1.0

package/dist/store.js

@@ -0,0 +1,163 @@
+/**
+ * The store: append-only JSONL files under one directory.
+ *
+ *   scans.jsonl      one ScanRecord per ingest
+ *   findings.jsonl   one FindingObs per finding per scan
+ *   detections.jsonl one DetectionRecord per watch detection
+ *   alerts.jsonl     one AlertRecord per emitted alert
+ *   watch-state.json checkpoints for watch mode (rewritten atomically)
+ *
+ * Reads tolerate a torn final line (a crash mid-append) by skipping any
+ * line that does not parse; appends are single write() calls per record.
+ * Finding status is derived from the observation series on every read,
+ * never stored, so the store cannot disagree with itself.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function defaultStoreDir() {
+    return process.env.TRACEWATCH_STORE ?? join(homedir(), ".tracewatch");
+}
+function readJsonl(file) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Torn or hand-edited line: skip it rather than failing every read.
+        }
+    }
+    return out;
+}
+export class Store {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    file(name) {
+        return join(this.dir, name);
+    }
+    ensure() {
+        mkdirSync(this.dir, { recursive: true });
+    }
+    append(name, record) {
+        this.ensure();
+        appendFileSync(this.file(name), `${JSON.stringify(record)}\n`, "utf8");
+    }
+    appendScan(rec) {
+        this.append("scans.jsonl", rec);
+    }
+    appendFindings(obs) {
+        for (const o of obs)
+            this.append("findings.jsonl", o);
+    }
+    appendDetection(rec) {
+        this.append("detections.jsonl", rec);
+    }
+    appendAlert(rec) {
+        this.append("alerts.jsonl", rec);
+    }
+    scans(repo) {
+        const all = readJsonl(this.file("scans.jsonl"));
+        return repo ? all.filter((s) => s.repo === repo) : all;
+    }
+    findings(repo) {
+        const all = readJsonl(this.file("findings.jsonl"));
+        return repo ? all.filter((f) => f.repo === repo) : all;
+    }
+    detections(repo) {
+        const all = readJsonl(this.file("detections.jsonl"));
+        return repo ? all.filter((d) => d.repo === repo) : all;
+    }
+    alerts(repo) {
+        const all = readJsonl(this.file("alerts.jsonl"));
+        return repo ? all.filter((a) => a.repo === repo) : all;
+    }
+    repos() {
+        return [...new Set(this.scans().map((s) => s.repo))].sort();
+    }
+    scanById(scanId) {
+        return this.scans().find((s) => s.scanId === scanId);
+    }
+    latestScan(repo) {
+        const list = this.scans(repo);
+        return list[list.length - 1];
+    }
+    observations(scanId) {
+        return this.findings().filter((f) => f.scanId === scanId);
+    }
+    /**
+     * Derive every tracked finding for a repo: status, first/last seen,
+     * resolution time, and content version count. Deterministic: output is
+     * sorted by identity, and scan order is store append order.
+     */
+    trackedFindings(repo) {
+        const scanList = this.scans(repo);
+        const scanAt = new Map(scanList.map((s) => [s.scanId, s.at]));
+        const scanIndex = new Map(scanList.map((s, i) => [s.scanId, i]));
+        const byIdentity = new Map();
+        for (const obs of this.findings(repo)) {
+            const arr = byIdentity.get(obs.identity) ?? [];
+            arr.push(obs);
+            byIdentity.set(obs.identity, arr);
+        }
+        const latest = scanList[scanList.length - 1];
+        const out = [];
+        for (const [identity, obsList] of byIdentity) {
+            const sorted = [...obsList].sort((a, b) => (scanIndex.get(a.scanId) ?? 0) - (scanIndex.get(b.scanId) ?? 0));
+            const first = sorted[0];
+            const last = sorted[sorted.length - 1];
+            const isOpen = latest !== undefined && last.scanId === latest.scanId;
+            let resolvedAt;
+            if (!isOpen && latest) {
+                const lastIdx = scanIndex.get(last.scanId) ?? 0;
+                const next = scanList[lastIdx + 1];
+                if (next)
+                    resolvedAt = next.at;
+            }
+            out.push({
+                identity,
+                latest: last,
+                firstSeenAt: scanAt.get(first.scanId) ?? first.scanId,
+                lastSeenAt: scanAt.get(last.scanId) ?? last.scanId,
+                firstScanId: first.scanId,
+                lastScanId: last.scanId,
+                status: isOpen ? "open" : "resolved",
+                resolvedAt,
+                versions: new Set(sorted.map((o) => o.findingId)).size,
+            });
+        }
+        return out.sort((a, b) => a.identity.localeCompare(b.identity));
+    }
+    /** Find one tracked finding by full or prefix findingId, or by identity. */
+    findFinding(repo, idOrPrefix) {
+        const tracked = this.trackedFindings(repo);
+        return (tracked.find((t) => t.latest.findingId === idOrPrefix) ??
+            tracked.find((t) => t.identity === idOrPrefix) ??
+            tracked.find((t) => t.latest.findingId.startsWith(idOrPrefix) && idOrPrefix.length >= 8));
+    }
+    readWatchState() {
+        const file = this.file("watch-state.json");
+        if (!existsSync(file))
+            return null;
+        try {
+            return JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    writeWatchState(state) {
+        this.ensure();
+        const tmp = `${this.file("watch-state.json")}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        renameSync(tmp, this.file("watch-state.json"));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * tracewatch types.
+ *
+ * tracewatch is the Security Wave's memory: it ingests the JSON reports of
+ * hookcheck, actionpin, and injectcheck, stores them as timestamped scan
+ * records, and tracks every finding across scans under a stable ID so a
+ * finding can be diffed, aged, and blamed to the commit that introduced it.
+ * Every record here is plain JSON: the store is append-only JSONL files the
+ * operator can grep by hand.
+ */
+export type ToolName = "hookcheck" | "actionpin" | "injectcheck";
+export declare const TOOLS: ToolName[];
+/** Single severity scale every tool's native scale is mapped onto. */
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+export declare const SEVERITY_ORDER: Severity[];
+export interface ToolScanInfo {
+    /** Version of the tool that produced the report, e.g. "0.1.14". */
+    version: string;
+    /** The tool's own verdict string, e.g. "COMPROMISED-PATTERN". */
+    verdict: string;
+    counts: Record<string, number>;
+    status: "ok" | "error";
+    error?: string;
+}
+export interface ScanRecord {
+    scanId: string;
+    /** Repo key the scan belongs to (a name, or an owner/repo slug). */
+    repo: string;
+    /** ISO timestamp of the ingest. */
+    at: string;
+    source: "run" | "import" | "watch";
+    /** Local path that was scanned, when known. */
+    path?: string;
+    /** GitHub slug (owner/repo) when known. */
+    github?: string;
+    /** git HEAD of the target at scan time, when it is a repo. */
+    headSha?: string | null;
+    tools: Partial<Record<ToolName, ToolScanInfo>>;
+    warnings: string[];
+}
+/**
+ * One observation of one finding in one scan. The store keeps every
+ * observation; a finding's status (open, resolved, changed) is always
+ * derived from the observation series, never stored as mutable state.
+ */
+export interface FindingObs {
+    /** tw_ + 16 hex: hash of tool, rule, normalized location, content signature. */
+    findingId: string;
+    /** Durable match key: tool | location | rule. Stable across content edits. */
+    identity: string;
+    scanId: string;
+    repo: string;
+    tool: ToolName;
+    rule: string;
+    severity: Severity;
+    /** File path normalized relative to the scan root (or a source label). */
+    file: string;
+    line?: number;
+    detail: string;
+    excerpt?: string;
+    /** Content signature the findingId was built from (sha256 hex). */
+    signature: string;
+    /** Tool-specific payload diff and blame need (command text, uses/ref, ...). */
+    data: Record<string, unknown>;
+}
+/** A finding plus its derived status across the whole store. */
+export interface TrackedFinding {
+    identity: string;
+    /** Most recent observation. */
+    latest: FindingObs;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    firstScanId: string;
+    lastScanId: string;
+    status: "open" | "resolved";
+    /** Scan time at which the finding was first absent after being present. */
+    resolvedAt?: string;
+    /** Distinct findingIds over time: more than one means the content changed. */
+    versions: number;
+}
+export interface DetectionRecord {
+    at: string;
+    repo: string;
+    kind: "issue" | "pr" | "tree" | "file";
+    /** Issue/PR number, file path, or commit SHA the content arrived as. */
+    sourceRef: string;
+    /** The content's own creation timestamp (issue created_at, commit time, file birth/mtime). */
+    createdAt: string;
+    timeToDetectMs: number;
+    scanId?: string;
+    findingIds: string[];
+}
+export interface AlertRecord {
+    at: string;
+    repo: string;
+    kind: "new-finding" | "changed-finding" | "ref-event" | "detection" | "watch-note";
+    message: string;
+    findingId?: string;
+    detection?: DetectionRecord;
+}
+export interface RefEvent {
+    identity: string;
+    file: string;
+    action: string;
+    oldRef: string;
+    newRef: string;
+    oldClassification: string;
+    newClassification: string;
+    kind: "ref-move" | "pin-regression" | "pin-improvement";
+    /** Scan the event was observed in (the "to" scan of the diff). */
+    scanId: string;
+    at: string;
+}
+export interface ChangedFinding {
+    identity: string;
+    before: FindingObs;
+    after: FindingObs;
+    /** Human-readable field moves, e.g. "severity: medium -> high". */
+    changes: string[];
+    refEvent?: RefEvent;
+}
+export interface ScanDiff {
+    repo: string;
+    from: {
+        scanId: string;
+        at: string;
+    } | null;
+    to: {
+        scanId: string;
+        at: string;
+    };
+    added: FindingObs[];
+    resolved: FindingObs[];
+    changed: ChangedFinding[];
+    unchangedCount: number;
+    refEvents: RefEvent[];
+    verdictMoves: {
+        tool: ToolName;
+        from: string | null;
+        to: string | null;
+    }[];
+}
+export interface CommitInfo {
+    sha: string;
+    author: string;
+    date: string;
+    subject: string;
+}
+export interface PullRef {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+}
+export interface Provenance {
+    repo: string;
+    finding: FindingObs;
+    status: "open" | "resolved";
+    firstSeenAt: string;
+    lastSeenAt: string;
+    confirmed: {
+        /** Earliest commit whose diff introduced the finding's needle (git log -S). */
+        introducingCommit?: CommitInfo;
+        /** Commit git blame assigns to the finding's current line at HEAD. */
+        currentLineCommit?: CommitInfo;
+        pullRequests?: PullRef[];
+        /** For action ref moves: first-seen and last-seen refs from the store itself. */
+        refHistory?: {
+            ref: string;
+            classification: string;
+            firstScanId: string;
+            firstAt: string;
+            lastScanId: string;
+            lastAt: string;
+        }[];
+        source?: {
+            kind: string;
+            ref: string;
+            url?: string;
+        };
+    };
+    /** Statements supported only circumstantially; labeled, never merged with confirmed. */
+    inferred: string[];
+    /** What could not be established, with the reason. Never guessed around. */
+    notEstablished: string[];
+}
+export interface HealthReport {
+    repo: string;
+    scanCount: number;
+    firstScanAt: string | null;
+    lastScanAt: string | null;
+    verdictTrend: {
+        scanId: string;
+        at: string;
+        verdicts: Partial<Record<ToolName, string>>;
+    }[];
+    open: {
+        total: number;
+        byTool: Record<string, number>;
+        bySeverity: Record<string, number>;
+    };
+    resolvedCount: number;
+    meanTimeOpenMs: number | null;
+    refEvents: RefEvent[];
+    detections: {
+        count: number;
+        medianMs: number | null;
+        maxMs: number | null;
+        byKind: Record<string, {
+            count: number;
+            medianMs: number | null;
+            maxMs: number | null;
+        }>;
+    };
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * tracewatch types.
+ *
+ * tracewatch is the Security Wave's memory: it ingests the JSON reports of
+ * hookcheck, actionpin, and injectcheck, stores them as timestamped scan
+ * records, and tracks every finding across scans under a stable ID so a
+ * finding can be diffed, aged, and blamed to the commit that introduced it.
+ * Every record here is plain JSON: the store is append-only JSONL files the
+ * operator can grep by hand.
+ */
+export const TOOLS = ["hookcheck", "actionpin", "injectcheck"];
+export const SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,CAAC,MAAM,KAAK,GAAe,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;AAK3E,MAAM,CAAC,MAAM,cAAc,GAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC"}

package/dist/util.d.ts

@@ -0,0 +1,16 @@
+export declare function sha256(text: string): string;
+/** Content signature for a finding: hash of its defining content parts. */
+export declare function signatureOf(parts: string[]): string;
+export declare function makeIdentity(tool: string, location: string, rule: string): string;
+export declare function makeFindingId(tool: string, rule: string, location: string, signature: string): string;
+export declare function makeScanId(repo: string, at: string, findingIds: string[]): string;
+/** Collapse all whitespace runs so trivial reflows keep one signature. */
+export declare function collapseWs(text: string): string;
+/**
+ * Normalize a file path from a tool report to repo-relative form. Reports
+ * may carry absolute paths (actionpin echoes the scanned path); anything
+ * under the scan root is relativized, separators become forward slashes.
+ */
+export declare function normalizePath(p: string, root?: string): string;
+export declare function median(nums: number[]): number | null;
+export declare function formatDuration(ms: number | null): string;

package/dist/util.js

@@ -0,0 +1,65 @@
+/**
+ * Small deterministic helpers: hashing, stable IDs, path normalization,
+ * and time math. Everything here is pure so diffs and reports built on it
+ * are reproducible from the same store state.
+ */
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, sep } from "node:path";
+export function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Content signature for a finding: hash of its defining content parts. */
+export function signatureOf(parts) {
+    return sha256(parts.join("\n"));
+}
+export function makeIdentity(tool, location, rule) {
+    return `${tool}|${location}|${rule}`;
+}
+export function makeFindingId(tool, rule, location, signature) {
+    return `tw_${sha256(`${tool}|${rule}|${location}|${signature}`).slice(0, 16)}`;
+}
+export function makeScanId(repo, at, findingIds) {
+    return `sc_${sha256(`${repo}|${at}|${[...findingIds].sort().join(",")}`).slice(0, 12)}`;
+}
+/** Collapse all whitespace runs so trivial reflows keep one signature. */
+export function collapseWs(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Normalize a file path from a tool report to repo-relative form. Reports
+ * may carry absolute paths (actionpin echoes the scanned path); anything
+ * under the scan root is relativized, separators become forward slashes.
+ */
+export function normalizePath(p, root) {
+    let out = p;
+    if (root && isAbsolute(out)) {
+        const rel = relative(root, out);
+        if (!rel.startsWith(".."))
+            out = rel;
+    }
+    return out.split(sep).join("/");
+}
+export function median(nums) {
+    if (nums.length === 0)
+        return null;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+export function formatDuration(ms) {
+    if (ms === null || !Number.isFinite(ms))
+        return "n/a";
+    if (ms < 1000)
+        return `${Math.round(ms)} ms`;
+    const s = ms / 1000;
+    if (s < 60)
+        return `${s.toFixed(1)} s`;
+    const m = s / 60;
+    if (m < 60)
+        return `${m.toFixed(1)} min`;
+    const h = m / 60;
+    if (h < 48)
+        return `${h.toFixed(1)} h`;
+    return `${(h / 24).toFixed(1)} d`;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/dist/watch.d.ts

@@ -0,0 +1,62 @@
+import { type AdaptedReport } from "./adapters.js";
+import { type IngestResult } from "./ingest.js";
+import type { Store } from "./store.js";
+import type { AlertRecord } from "./types.js";
+export interface FileMark {
+    mtimeMs: number;
+    size: number;
+    birthtimeMs: number;
+    hash?: string;
+}
+export interface RepoWatchState {
+    target: string;
+    lastHead?: string | null;
+    snapshot?: Record<string, FileMark>;
+    issuesSeen?: Record<string, string>;
+    issueNoteAt?: string;
+}
+export interface WatchStateFile {
+    repos: Record<string, RepoWatchState>;
+}
+export declare function snapshotTree(root: string): Record<string, FileMark>;
+export interface WatchDeps {
+    scanFile: (path: string) => Promise<AdaptedReport | null>;
+    ingest: (store: Store, path: string, opts: {
+        name?: string;
+        source?: "watch";
+    }) => Promise<IngestResult>;
+    ghGet: (path: string) => Promise<string | null>;
+    now: () => Date;
+    /** Tool version lookup; injectable so tests never spawn real tools. */
+    version?: (tool: "injectcheck") => Promise<string>;
+}
+export declare const defaultDeps: WatchDeps;
+export interface WatchContext {
+    store: Store;
+    deps: WatchDeps;
+    emit: (alert: AlertRecord) => void;
+}
+/** One local poll cycle. Returns the alerts emitted this cycle. */
+export declare function pollLocalOnce(ctx: WatchContext, repo: string, targetPath: string): Promise<AlertRecord[]>;
+/** One GitHub poll cycle (issues/PRs + HEAD). Returns alerts emitted. */
+export declare function pollGithubOnce(ctx: WatchContext, slug: string, opts?: {
+    path?: string;
+}): Promise<AlertRecord[]>;
+export interface WatchOptions {
+    store: Store;
+    target: string;
+    /** Repo key override (default: directory basename, or the slug itself). */
+    name?: string;
+    path?: string;
+    intervalSec?: number;
+    once?: boolean;
+    maxMinutes?: number;
+    alertsFile?: string;
+    deps?: WatchDeps;
+    stderr?: (line: string) => void;
+}
+/** Run watch until stopped (SIGINT/SIGTERM), --once, or --max-minutes. */
+export declare function watch(opts: WatchOptions): Promise<{
+    cycles: number;
+    alerts: number;
+}>;