Projects

Knock Access Log Monitor

A lightweight service for access logs, event tracking, and security boundary checks

Status
MVP
Type
Infra
Updated

A server-side monitoring module for recording access events, parsing logs, and validating basic authentication boundaries on public endpoints.

Verifiable entry points

Demo and source

No public demo

The monitor depends on real access logs and can expose IPs, request paths, and runtime timelines, so there is no public demo.

Source evidence

Review log parsing, incremental ingest, SQLite schema, aggregation API, authentication, and the static dashboard.

Evidence

MVP shape

The module covers access event recording, log parsing, and a basic authenticated surface

Test boundary

Node 22 and the native module ABI are explicit local verification constraints

Operations value

It can become a runtime summary source for Dashboard Console

Asset status

Only repository-backed product mocks, public documentation, or an explicit no-public-image explanation appear here.

Asset type: Architecture diagram

Architecture diagramOpen full-size diagram
Current Knock architecture: an Nginx log flows through incremental ingest, parsing, SQLite WAL storage, and an Express API into a protected monitoring interface
Architecture diagram: only the implemented single-machine data flow and Basic Auth boundary are shown, with no real IPs, request paths, or logs. Dashboard summaries and alert signals are explicitly marked as roadmap work.

Asset type: Documentation

Read the Knock runbook

The public runbook records log input, configuration, authentication requirements, build tests, and Windows deployment.

Read the Knock runbook

Problem

Personal projects often go live without minimal access visibility, making abnormal traffic, configuration mistakes, and exposed endpoints hard to diagnose.

Solution

Collect, parse, and present key access events through a Node service, with optional Basic Auth for the monitoring surface.

My role

  • Node service implementation
  • Log parsing
  • Basic Auth integration
  • Runbook maintenance

Stack

  • Node.js
  • TypeScript
  • better-sqlite3
  • node:test

Highlights

  • Low deployment cost
  • Clear authentication configuration
  • Ready to feed Dashboard summaries

Architecture

Knock reads Nginx access logs incrementally and writes parsed records to local SQLite. An Express API aggregates time windows, status codes, and suspicious requests, with Basic Auth protecting the monitoring surface.

  1. Step 01

    Nginx access log

    The service reads from a saved file offset and detects truncation or rotation on a best-effort basis.

  2. Step 02

    Parse and classify

    Request fields and suspicious signals are parsed and written inside one transaction.

  3. Step 03

    SQLite WAL

    A local database stores indexed requests and data covered by the configured retention window.

  4. Step 04

    Express API

    The API returns overview, time series, top IP, top path, and suspicious-request data for 1h, 24h, or 7d windows.

  5. Step 05

    Protected monitor

    A static dashboard calls the same-origin API; public exposure requires Basic Auth or equivalent access control.

Key decisions and impact

  1. Decision 01

    Read appended log bytes instead of rescanning the file

    Rationale
    Offset state lets each polling pass process only new data and recover best-effort from truncation or rotation.
    Impact
    Continuous single-machine ingest stays inexpensive, but the state file and configured log path must remain aligned.
  2. Decision 02

    Store monitoring data in SQLite WAL mode

    Rationale
    A personal server benefits from queryable local storage without operating a separate database service.
    Impact
    Deployment is simple and aggregation stays fast enough for this scope, but the design remains single-machine and single-writer.
  3. Decision 03

    Protect the monitoring surface with Basic Auth

    Rationale
    Access logs expose IPs, paths, and user agents and must not become an unprotected public page.
    Impact
    The boundary fits a personal operations surface but is not a multi-user permission and audit system.

Trade-offs

  • SQLite keeps deployment simple, but it is not meant for high-concurrency or multi-writer deployments.
  • Basic Auth is enough for a personal monitoring surface, but it is not a full permissions system.
  • Retention cleanup runs with ingest, which is simple but means cleanup does not run independently when ingest is disabled.

Roadmap

  • Connect Dashboard summary cards
  • Observe log rotation and retention at runtime
  • Improve deployment health checks and alert signals

Current limitations

  • Full tests depend on the Node 22 native module ABI
  • Still a single-machine SQLite setup

Next steps

  • Connect Dashboard summaries
  • Verify log-rotation recovery
  • Improve deployment health checks

Keep exploring

Related entry