Take the watch.

Documentation map

Nightwatch has two kinds of explanation. The dashboard’s After Hours and Behind the Rack rooms explain the product and its machinery. This site is the field manual: how to deploy it, use it safely, and decide what should become configurable.

From empty host to first round

Nightwatch is a Python 3.10+ process with no pip dependencies. It needs a matching excli binary, access to RevealX, and a tool-calling model endpoint.

1. Prepare the host

• Use a dedicated, non-root service account.
• Allow outbound HTTPS to RevealX and the configured model provider.
• Install qrencode for locally generated authenticator QR codes; manual TOTP secret entry remains available without it.
• Keep the application, database, configuration, secret files, and evidence directory on persistent storage.
• Expose the UI through TLS and authentication; the default direct bind is loopback-only.

2. Choose an authorized installation track

Packaged release (recommended for operators): obtain the platform archive and checksum from the Nightwatch distributor, verify the checksum, unpack it, and use the bundled service template. The archive includes Nightwatch and a pinned excli binary; it never includes credentials or a working site configuration.

sha256sum -c SHA256SUMS
tar -xzf nightwatch-VERSION-PLATFORM.tar.gz
cd nightwatch-VERSION-PLATFORM
cp nightwatch.example.json nightwatch.json
# Add secret-file references and environment-specific settings.
python3 nightwatch.py --doctor --config nightwatch.json
python3 nightwatch.py --config nightwatch.json

Authenticated source: maintainers and authorized users may clone the private repository with an account or token that has access, then obtain the pinned excli binary. A normal unauthenticated GitHub clone will not work while the repository is private.

gh auth login
gh repo clone aarond-eh/nightwatch
cd nightwatch
cp nightwatch.example.json nightwatch.json

Open http://127.0.0.1:8321 after startup. Put a maintained TLS reverse proxy in front of Nightwatch before allowing remote access.

3. Pass the preflight

--doctor is read-only. It checks the executable and checksum, database, target authentication, record and metric coverage, lamp groups, telemetry freshness, model tool calling and pricing, bind/auth posture, secret-file modes, and disk capacity. Treat a failed required check as an installation failure.

4. Verify the first round

1. Confirm the header shows the configured target and a successful checkpoint.
2. Run Sweep now and Check now.
3. Open Security and Performance, including their history views.
4. Confirm model use and deterministic work in the technical telemetry.
5. Trigger a test webhook if notifications are configured.

Work the board, not every alert

Overview

Overview is the shift handoff. The patrol strip reports recent jobs; the service lamps summarize current service state; priority work links into Security and Performance. Use manual round buttons to validate or investigate—not as a substitute for the scheduler.

Security

Security shows correlated campaigns, highest severity first. Open a campaign to read the analyst desk, Daylight challenge, evidence, entities, ATT&CK context, timeline, and unknowns. Use live research for bounded read-only questions. Record the outcome when the case is understood.

Performance

Each lamp corresponds to configured ExtraHop activity groups and a metric pack. Amber and red episodes show service impact, offenders, evidence, and possible cross-domain security references. History answers whether a condition is new, recurring, or worsening.

Handled

Handled is durable attention control, not deletion. Repeated benign patterns are grouped with scope and history. A new host, account, or destination is judged again. Reopen a pattern when the business context changes; disable a suppression when it is too broad.

Research, evidence, and exports

• Chat is scoped to the open campaign or episode and uses read-only tools.
• Case notes are analyst-selected; conversation exports do not automatically become case evidence.
• Markdown and JSON are portable handoffs. HTML is print-friendly. CSV flattens evidence.
• Packet capture requires a bounded window, purpose, BPF, size limit, and typed human approval. Scheduled work and the model cannot approve it.

Own the boundaries

Administrators control connectivity, identity, cost, persistence, write permissions, and the definition of “inside.” Those choices change what every analyst sees.

The administration workspace

The gear opens the authenticated control plane. People & access supports search, per-account changes, visible-row selection, and atomic bulk role or enablement updates. Disabling an account preserves authored decisions and audit history while revoking its active sessions. An administrator cannot remove their own access, and Nightwatch always retains at least one active administrator.

Configuration workflow

System configuration exposes seven validated categories: Environment & targets, Service lamps, Schedules & cadence, Notifications, Email & recovery, Authentication security, and Audience & capacity. Search locates a category; each editor saves the complete safe configuration while preserving fields outside its schema. It never resolves or returns secret values, writes a mode-600 backup, and replaces the configuration atomically. Restart Nightwatch after a saved configuration change.

Enrollment, recovery, MFA, sessions, and bot verification

Administrators can generate, replace, enable, and disable a hashed invitation code; the login page exposes account creation only while invitations are enabled. With SMTP configured, signup creates a pending account, sends a single-use 30-minute verification link, and activates a viewer only after verification. Password recovery uses an indistinguishable response for known and unknown addresses, a single-use 20-minute link, bounded request rates, and session revocation after reset.

Each user can review active sessions, revoke an individual sign-in, sign out everywhere, and enroll a standard TOTP authenticator. Nightwatch shows recovery codes once and stores only their hashes. Administrators can require MFA by role and configure session lifetime, secure-cookie behavior, login-attempt windows, lockout duration, and the accepted legal-policy version. The server-console password-reset command is the break-glass path: it re-enables the named local account, revokes its sessions, and clears MFA so the administrator can enroll again. External identity providers remain a future connector boundary.

Optional Cloudflare Turnstile can protect login, signup, and recovery. It is disabled by default and makes no Cloudflare request while disabled. When enabled, Nightwatch requires a public sitekey, secret-file or environment reference, approved hostnames, and selected forms; the backend verifies every token’s success, action, and hostname before authentication logic runs. Turnstile supplements rate limits, lockout, verified email, and MFA—it does not replace them.

Audience and shared capacity

Administrators can bound interactive requests per user and source network, manual actions per user, FIFO interactive concurrency, queue wait time, and deployment interactive cost per day and month. Quiet mode pauses analyst-triggered model work and forced rounds while deterministic scheduled measurement continues. Demo reset and viewer-export policy are disabled by default; when explicitly enabled, reset removes chats and saved notes while preserving cases, evidence, accounts, configuration, and audit history. These limits protect a shared lab and complement—not replace—upstream provider quotas and authorization roles.

Administrative checklist

• Targets: verify names, hosts, credentials, internal networks/domains, and reconciliation scopes.
• Identity: require sign-in, use TLS, set secure cookies, assign least privilege, and remove dormant users.
• Models: qualify tool calling, set primary/fallback budgets, and understand provider data policy.
• Writes: leave tuning disabled until governance and rollback ownership are established.
• Storage: monitor database, evidence, backup, and free-disk growth.
• Notifications: sign webhooks and route links to the public Nightwatch URL.

Backup and recovery

Back up the configuration, SQLite database (using a SQLite-safe snapshot while running), evidence directory, and secret references. The database contains cursors, campaigns, feedback, outcomes, suppression memory, audit records, and session state. Test restore on an isolated bind before declaring recovery complete.

Change control

Record who changed a target scope, detector threshold, model route, retention window, or write capability; why; the expected effect; validation result; and rollback point. Run doctor after infrastructure or credential changes and after every release.

What the system reads today

The example configuration is the canonical portable template. The table below groups controls by operational consequence; defaults are template defaults, not universal recommendations.

Deterministic first, explainable always

Nightwatch’s hunt rules and statistical signals run before model reasoning. Rules are currently shipped as reviewed source, not uploaded from the browser. Configuration exposes a small set of safe thresholds and resource ceilings.

Current rule contract

• A stable ID and version.
• A supported ExtraHop record type and query.
• Required fields and a coverage condition.
• Actor/entity extraction and an explicit count or threshold.
• Evidence text that can be cited without inventing telemetry.
• Tests using sanitized record contracts, including missing/truncated data.

When a new rule belongs

Add a deterministic rule when the evidence condition is precise, repeatable, cheap enough for every round, and independently testable. Use reasoning only to interpret fired evidence in context. Do not encode a vague “suspiciousness” prompt as a rule.

Proposed supported rule packs

A future rule-pack format should allow signed, versioned packs with metadata, record contracts, queries, thresholds, entity mappings, severity guidance, fixtures, and resource budgets. Packs should pass doctor validation and a dry run before activation. Arbitrary Python, shell, network calls, model prompts, and write tools should remain outside the pack format.

Teach a method, not a personality transplant

A Nightwatch skill should define a bounded investigation method: what evidence it accepts, which read-only tools it may use, what it must publish, and how success is tested. Skills should not be unscoped prompt fragments.

Proposed skill manifest

id: org.example.identity-triage
version: 1.0.0
accepts: [finding.kerberos, finding.ldap]
tools: [records.search, metrics.query]   # read-only allowlist
publisher: publish_investigation
max_tool_rounds: 6
evidence_contract: complete-or-declare-gap
tests: [fixtures/spray.json, fixtures/ordinary-sso.json]

Design requirements

• Signed/versioned origin and a compatibility range.
• Explicit input/output schemas and tool allowlist.
• Hard token, tool-round, time, and record budgets.
• Prompt-injection handling and untrusted-data boundaries.
• Positive, negative, incomplete-evidence, and cost regression tests.
• Dry-run, staged rollout, audit trail, and one-step rollback.

Tune the gates before the prose

Current operators can select model routes, set budgets, bound tool rounds and queues, and enable Daylight in the configuration file. Those controls are not yet exposed by the browser editor. Method prompts and publisher schemas remain application code. Future reasoning profiles should make safe policy choices configurable without turning the UI into a prompt editor.

What should become configurable

What should not be a free-form knob

Tool permissions, write authority, publisher schemas, evidence citation rules, secret access, tenant reconciliation, and human approval gates must remain enforced contracts. A custom prompt must never widen them.

Evaluation loop

1. Freeze a sanitized labeled set, including misses and ordinary activity.
2. Record the baseline model, method version, cost, latency, and outputs.
3. Change one policy dimension.
4. Run schema, safety, quality, and cost gates.
5. Shadow the profile without affecting the board.
6. Promote gradually with automatic rollback on contract failure.

Keep the night shift on a short leash

Hardening baseline

• Bind Nightwatch to loopback and terminate TLS at a maintained reverse proxy.
• Require authentication; use secure cookies; rotate credentials and signing secrets.
• Run as a dedicated non-root account with read-only application files.
• Restrict secret and evidence files to that account; exclude both from source and support bundles.
• Allow only required outbound destinations. Keep ExtraHop tools read-only for model use.
• Leave native tuning writes disabled unless reviewed; keep typed approvals and rollback audit enabled.

Operational symptoms

The control-plane map

The administration workspace exposes implemented controls and reserves clearly labeled locations for future safe controls, while keeping evidence contracts and authority fixed. This is the proposed order of work.

Documentation version v26.08.10. When product behavior and this site disagree, treat that as a defect: verify against the example configuration and release tests, then update both in the same change.