Take the watch.

Documentation map

Nightwatch has four Back-of-House rooms. After Hours explains the night shift, At the Chalkboard exposes the static V3 reasoning contract, Behind the Rack shows evidence plumbing and method receipts, and The Cost owns model accounting and comparison. This field manual covers installation, current deployment, operation, administration, extension, and safety.

From empty host to first round

Nightwatch is a Python 3.10+ process with no pip dependencies. It needs at least one compatible evidence connector and a tool-calling model endpoint. The current distribution can use its wire-data adapter; the core is not tied to that source.

1. Prepare the host

• Use a dedicated, non-root service account.
• Allow outbound HTTPS to source system 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, verify the checksum, unpack it, and use the bundled service template. A connector may be packaged separately or included by the distributor. Releases never include credentials, customer data, endpoints, 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
# Install the connector, then add target/model endpoints and private secret-file references.
python3 nightwatch.py --doctor --config nightwatch.json
python3 nightwatch.py --config nightwatch.json --db nightwatch.db

Source installation: clone the repository, copy the credential-free example configuration, install a compatible connector, and run the read-only preflight before initializing the service.

gh auth login
git clone <nightwatch-repository>
cd nightwatch
cp nightwatch.example.json nightwatch.json
# Install the connector and configure target/model endpoints plus private secret files.
python3 nightwatch.py --config nightwatch.json --doctor
python3 nightwatch.py --config nightwatch.json --db nightwatch.db

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 Cases and inspect All Cases, Needs You, On Watch, Services, and Connected.
4. Confirm model use and deterministic work in the technical telemetry.
5. Trigger a test webhook if notifications are configured.

Then bring in the rest of the team. Sign in as the first administrator, open Settings from the gear control, and read the administrator guide. V3 enrolls people through named invitations and organization join codes; there is no deployment-wide signup code to hand out.

Small by default, separable when needed

The supported small deployment is one dedicated application host with local persistent SQLite and evidence storage, fronted by a maintained TLS reverse proxy. It is inexpensive, inspectable, and appropriate for a handful of concurrent analysts.

Production baseline

• Run the committed release as a dedicated non-root service; application files are read-only to the runtime account.
• Bind the application to loopback. Only the reverse proxy accepts remote traffic.
• Keep database, evidence, exports, configuration, and secret references on persistent encrypted storage with restrictive modes.
• Allow outbound traffic only to configured connectors, model routes, mail relay, notifications, and explicitly enabled public context sources.
• Back up the database and evidence directory together. Test restore to an isolated path and record the result.
• Monitor process health, scheduler progress, connector health/backoff, model routing, disk, database integrity, mail queue, and certificate expiry.

Growth path

Do not begin with a cluster merely because one may be needed later. First move the production runtime away from the build host. Then increase CPU, memory, and disk. When real concurrency or retention requires it, separate web/API from background workers and move durable state to a transactional database and object storage behind the same repository interfaces. Case identity, audit, connector receipts, and workflow semantics must not change during that migration.

Follow the case, not the product boundary

Nightwatch is one operating desk built from shared evidence. It does not require separate SOC and NOC roles. One person may investigate an account, restore a service, decide whether the two are connected, and verify the result.

The cohesive work model

These are aspects of work, not organizational lanes, permissions, or personas. A familiar account doing something new can matter to a case; a machine where several symptoms converge can anchor an incident; a failing dependency can anchor a service. Nightwatch should name the thread and explain why it matters rather than present an inventory of accounts, hosts, addresses, and framework codes.

Overview

Overview is the morning briefing: what needs attention, what Nightwatch is doing, what it handled, and whether apparently separate symptoms may be connected. Ask Nightwatch can answer a quick wire-data question, start a durable investigation, accept a pasted brief, or independently test claims. A quick question does not become a case unless the evidence supports managed work.

A case card on Overview is deliberately a glance: urgency, state, one-sentence thesis, the thread that connects it when useful, compact scope, and the next action. Each card carries one bounded reason for the attention it is asking for, how many records it links, and whether it was reopened. Evidence, framework identifiers, investigator history, and the full card spread belong in the Case Room.

The Watch Brief Available now

The Watch Brief is the cited five-minute public-intelligence orientation immediately before Overview. One tenant-local daily run reads only the source IDs approved in that organization's Markdown profile, checks strict HTTPS, redirect, address, response-size, item-count, and freshness boundaries, and asks one bounded model pass to select one to three genuinely material developments. It separates reports published or materially updated in the last 24 hours from continuing weekly context, compares cited material with the prior verified edition, and states whether pressure is increasing, decreasing, mixed, steady, or not yet supportable across the monitored sources. Every displayed factual topic and trend cites the fetched article record that supports it. A failed source is named in coverage; a failed edition leaves the last verified edition visible rather than substituting headlines or partial prose.

Global reporting is context, not tenant evidence. For validated public indicators, Nightwatch may run only bounded, reviewed exact-match queries against configured read-only wire sources and compare cited CVEs with current case memory. Each result names its time window and coverage: a match establishes related evidence, not compromise or campaign attribution; no match is not proof of safety; missing inventory or incomplete retrieval remains an explicit gap. The Brief never creates a case, Needs You item, attention change, or notification. Investigate hands the attributed external context to Investigator for deeper work under the ordinary case criteria.

Investigations Available now

Investigations is the file cabinet for work that is not necessarily a case: a threat hunt, service diagnosis, identity review, architectural question, pasted scenario, or claim challenge. Search active or archived work, see who started it and whether Nightwatch is working, waiting, paused, incomplete, or finished, then resume it without losing the transcript or evidence cutoff. Rename and archive keep work manageable; purge is a separate explicit destructive action.

An investigation can remain research, link to one or more cases, or propose a new case when its findings support a condition that deserves ownership or action. Linking does not copy the transcript or manufacture telemetry. Case-bound research and standalone research use the same durable workspace.

The durable clock

Every scheduled round, evidence-triggered follow-up, and human Run now or Update case now request is recorded before execution with a stable identity, target, reason, due time, prerequisite versions, priority, attempts, and fenced worker lease. Recurring work is anchored to UTC slots, so a slow or failed run does not shift the whole schedule. A human-triggered review wakes immediately but does not erase or postpone the normal cadence.

Collection wakes correlation; correlation and explicit case review wake Case Manager; the exact resulting case version wakes Daylight; a current Daylight result can then wake notification delivery. Failed work retains its error and deterministic retry time. Expired leases are recovered after restart, duplicate triggers are idempotent, and stale workers cannot publish. The activity display summarizes working, ready, retrying, blocked, and completed work without exposing internal tool chatter.

Work waits for explicit reasons, and each is a distinct state: waiting for a source, waiting for a retry, waiting for budget, needing input, or paused. When a backlog grows, Nightwatch compacts routine duplicate work within a bounded, audited batch; it keeps the oldest due maintenance item, preserves analyst-triggered and critical chains ahead of newer routine work, and never discards blocked dependencies or pending Daylight and notification drains. A missed recurring slot reuses its existing slot identity rather than creating a parallel schedule.

Cases Available now

The Cases desk holds durable cases and the service evidence that may support them. Its All Cases, Needs You, On Watch, Active, Waiting, Resolved, Services, and Connected lenses are different views of the same operating desk. Active, Waiting, and Resolved make human progress and verification visible. Services can remain measured conditions without becoming cases; Connected shows meaningful case/service overlap without claiming that one caused the other.

Needs You is a security judgment, not a queue Available now

Needs You means Nightwatch has already collected, correlated, and challenged the evidence and still concludes that this is one real, material attack situation a person should look at now. It is a bounded analyst-facing judgment about the security situation. It is not every finding, not every unresolved fact, not a severity label, and not an authorization workflow.

A case reaches Needs You only when both gates pass:

A current Daylight explanation, a model disposition of watch, an analyst return to watch, an analyst benign closure, or a case state that is no longer open or reopened refutes the first gate. Every gate that fails sends the case to On Watch—Nightwatch keeps it and keeps working it. Two analyst acts override the evidence gates in the other direction and are recorded as such: a human validation keeps the case prominent until it is explicitly closed, and an explicit escalation moves it to the analyst’s desk.

On Watch Available now

On Watch holds coherent activity Nightwatch is monitoring that does not merit analyst attention now. The case is real, the evidence is retained, and Nightwatch owns the next bounded check. On Watch is the honest default: unproven, refuted, and not-yet-material stories stay here rather than being pushed at a person or quietly dropped. Each card states why—no established malicious explanation yet, a current explanation that closes the behaviour, or consequence and scope that do not yet justify an investigation.

One card per situation, not one per pass Available now

A repeated collection window, a reasoning retry, or a re-published assessment of the same behaviour on the same subject is the same situation. In both lanes a repeated window updates one current representative rather than adding a card. The representative keeps the highest severity any contributing assessment actually reached, the confidence and timeline of the most recent observation, and the earliest opening time; it carries the contributing case and workspace identifiers so nothing is lost, and reports how many contributed.

The collapse key is deliberately narrow: target, engine, exact detector signature, durable subject keys, deterministic kill-chain stages, and the structured attack hypothesis. It contains no correlation bucket, no timestamp, no title or other model prose, no severity, and no evidence count, so the same situation observed again produces the same key.

Queue counts are bounded and say so. The lane response declares the request bound it applied and whether more cards exist beyond it, and the Overview headline counts the same unit as the queue: distinct situations, not recurrences.

Cases grow; Nightwatch does not wait

A case appears as soon as the evidence supports a coherent proposition worth working. It can then gain findings, change confidence, acquire a different presentation, or receive another deterministic assessment. When exact evidence later proves that two visible cases are one story, Nightwatch collapses them into the older case, preserves which assessments joined, and explains why under Reasoning. It does not hide useful work while trying to build an ultimate campaign.

Only two kinds of evidence carry authority to merge separate cases: an exact shared occurrence identity computed by deterministic reconciliation, and an attributed analyst link. A shared detector signature, address, account, activity family, or a close time window is a visible link and nothing more. Where cases concern the same bounded subject, Nightwatch may present them as one operator decision while their identities, evidence, and lifecycles stay separate—and it says so, naming the shared subject rather than asserting one incident. A single busy host or account can gather several strands that way; read that as a recurrence group around one subject, not as an attack campaign. No grouping in V3 is an attribution claim about an adversary.

Nightwatch keeps two clocks. A one-off lead on Still on watch expires after a short complete clean window if it never develops. An established case stays active on a much longer case clock. Expiry and quiet resolution archive attention; they do not delete evidence. When new work shares exact evidence—or the same strong subject and activity family—an earlier deck can return as clearly dated historical context.

The Case Room Operational folio

Selecting a case opens its first-class working room rather than stretching the Overview card into a report. Every entry point—Overview, Cases, a connected service, or a direct link—refers to the same durable case. The left side is the case folio: title, phase, owner, priority, confidence, lifecycle, current judgment, and the next owned move. The prominent action follows the phase: accept, record progress, resume, confirm resolution, or reopen. Nightwatch drafts routine progress from the existing case so the analyst can accept or edit instead of completing a ticket form.

Details and Investigator are mutually exclusive support surfaces. Opening either replaces the other, so the proof view and research transcript never compete for the same horizontal space. Either surface can enter the full browser viewport and return to the case without losing its focus or scroll position. Details holds proof and provenance. Investigator is the case-aware research surface. Neither creates a second case or a second source of truth.

Case workflow

The operational path is On Watch → Needs You → Active → Waiting → Resolved/verification → Handled, with Reopened when new evidence changes a closed judgment. Evidence state and workflow state are deliberately separate. Every transition records actor, time, previous and next phase, summary, owner, next action, and review or resolution context in append-only history.

How Nightwatch lays out a case Available, expanding

Nightwatch presents an argument, not an evidence dump. The case composition adapts to the evidence: two sentences may be enough for a familiar recurrence; an ordered sequence may need a timeline; shared identity or device activity may need a relationship sketch; and a possible service connection may need aligned lanes. The card metaphor means “lay the useful facts on the table.” It is not a fixed deck, a game, or a requirement that every case have equal cards.

The investigation is navigable in layers: case → line of argument → contributing deck → source evidence. The case opens with Nightwatch’s plain-language conclusion, evidence spine, impact, uncertainty, and next move. “How this case came together” then exposes each narrower assessment as a deck and each observed finding beneath it as an evidence card. Nearby cases remain visibly outside the boundary until shared evidence earns a merge.

Every explanation follows the same disclosure order:

1. Meaning: what Nightwatch thinks happened, why it matters here, and the next useful action.
2. Reasoning: how the facts connect, what argues against the conclusion, what remains unknown, and what would change the call.
3. Source: records, detections, measurements, timestamps, queries, and identifiers such as ATT&CK technique IDs.

The first view contains only what is needed to understand and act. On desktop, the Case Room coordinates an adaptive canvas, an inspector for the selected card or relationship, and one persistent Case investigator. Nightwatch recreates the investigator from the current case file on every turn, carries a bounded handoff from older conversation, retains recent turns verbatim, and keeps the complete transcript for audit and export. The case can therefore grow for days without depending on an opaque provider thread or sending its entire history on every question.

Likely follow-ups that Nightwatch can already answer stay within reach—for example, “Why is this account unusual here?”, “Have we seen this before?”, or “Did the slowdown begin first?” Anything else belongs in the Case investigator. Opening stored evidence should not spend model tokens.

Mobile is a focus stack Available, expanding

Nightwatch does not squeeze a spatial desktop canvas onto a phone. Mobile leads with case identity, thesis, and next action; then it presents one active visual or card and the suggested-next cards in a deliberate vertical order. Inspector and investigator controls open focused, accessible surfaces. Mobile Investigate means selecting, comparing, pinning, and asking—not dragging tiny cards around.

Notes, conversation, and decisions

Nightwatch keeps human context separate from detections, records, and measurements. It may say “Aaron noted that this was approved maintenance”; it may not turn that note into “telemetry confirms approval.” If later evidence conflicts with a note, the case should show both rather than quietly choosing one.

Services in Cases

Each lamp corresponds to configured source activity groups and a metric pack. The selected service leads with a plain-English conclusion, why it matters, Nightwatch’s leading explanation, what changed, and what happens next. A service episode is a bounded measurement period; it becomes part of a case only when the condition needs ownership, continued observation, or action. Measurements, named hosts and clients, counter-signals, resolved checks, packet evidence, and exports remain supporting material. History answers whether a condition is new, recurring, or worsening.

Service reasoning runs only on a material episode change. The deterministic measurement remains authoritative; one bounded read-tool turn may settle a precise unanswered wire question before Nightwatch publishes. It must not hand an available evidence-source lookup back to the operator as homework. Missing endpoint, change, ownership, or human context stays explicitly missing. Services do not create a parallel investigator or duplicate the Case Room.

Connected work and causality Available now

When case evidence and service impact overlap, the Connected lens places the case and the measured service condition side by side and draws the exact shared subject and UTC window between them. A separate Nightwatch analysis explains how they connect, why it matters, and whether the relationship is direct wire confirmation, supported contribution, coincidence, or still unproven. Supporting evidence, counter-evidence, resolved checks, missing evidence, impact, and the deciding next step stay expandable. The case and service remain independently navigable; the view does not repeat one summary twice or silently turn overlap into cause. Full durable incident workflow remains in development.

Handled Available now

Handled is durable attention control. It is not deletion, and it is not proof that nothing happened. A pattern in Handled means a person or a deterministic rule decided this activity does not need the desk again; the evidence, the receipts, and the audit history all remain.

Repeated occurrences are grouped with scope, count, and history, and each group states whether its summary is exact or an estimate rather than implying precision it does not have. A suppression is bound to the evidence that justified it: a new host, account, or destination inside a suppressed pattern is judged again, and a scope change or a changed cadence fails open rather than hiding the new thing. Reopen a pattern when the business context changes; disable a suppression when it is too broad. A disabled policy is retained and visibly inactive rather than erased.

Daylight: the independent challenge Available now

Before a case reaches a person, Daylight makes a separate pass over the same frozen evidence package with one job: try to disprove the first conclusion. It asks whether ordinary operations explain every important observation, whether the claimed sequence is actually supported by time and entity links, whether attempts were mistaken for successes, whether scope is inflated by duplicates or shared infrastructure, what evidence would reverse the call, and whether the decisive check is available now.

Daylight publishes one of three outcomes—explained, survived, or in the dark—and the release enforces its evidence boundary rather than trusting the wording:

• Every signature Daylight cites must exist in the candidate evidence it was given. A review that cites anything else is discarded whole; it cannot invent a fact to close a case.
• Collection truth is deterministic. Daylight cannot upgrade a partial evidence packet by declaring it complete: an explained verdict on incomplete collection is rewritten to in the dark with that reason recorded.
• An explained verdict clears a case only at high confidence, on complete collection, citing every candidate finding, with no unresolved shadows and every stated assumption marked verified.
• A survived verdict counts as positive evidence only when the review is current, the collection was complete, and the reviewer was itself confident.
• A pending, stale, or superseded review proves nothing in either direction. Unavailable Daylight never clears a case: the first conclusion stays authoritative and the gap stays visible, with the reason—model capacity, quota, or an incomplete challenge—stated plainly.

The investigator Available now

The investigator is the conversational research surface for the work you already have open: a case, a durable investigation, or a quick question. It is rebuilt from the current case file on every turn, keeps recent turns verbatim, carries a bounded handoff from older conversation, and retains the complete transcript for audit and export. Asking a question changes nothing on its own.

Two explicit actions turn research into product state, and they are different:

Tool use is real and bounded. The investigator may call only routed, read-only evidence-source tools within its target and role, every call is audited, unapproved or cross-target calls never reach the executor, and viewers cannot use tools at all. A failed query is a failed query—not a negative result—and the investigator does not hand an available machine lookup back to you as homework. When a fact genuinely cannot be reached, it names the missing fact, why the wire cannot supply it, and who or what can answer.

Long research pauses instead of pretending to finish. When a pass reaches its tool budget, Nightwatch reports what the evidence supports so far, separates checks it can continue from facts that need an unavailable source or a human decision, saves the evidence gathered, and marks the work paused. Replying Continue resumes the remaining checks. A pass that stopped at its limit is never reported as a completed investigation.

Research, evidence, and exports

• Chat is scoped to the open work 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.

Four rooms, four honest views

Back of House explains the current V3 product from four different angles. The rooms share navigation and evidence rules, but they deliberately keep different visual identities and different responsibilities. They are explanatory and diagnostic surfaces—not alternate administration screens.

Own the boundaries

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

One Settings workspace Available now

Nightwatch has a single canonical Settings workspace. Open it from the dedicated Settings control in the header—the gear. Everyone lands in the same workspace; the sections you see depend on your role. Its sections are separated by scope, so it is always clear whose settings you are changing:

Global identity, organization membership

V3 separates who you are from what you may do where. A person has one global identity—email, display name, password, MFA, avatar, sessions—that is the same across the deployment. Access to each organization is a separate membership carrying its own local handle, role, and state. Removing someone from an organization does not delete their identity; disabling their identity removes access everywhere.

Be precise when you write runbooks: an Organization Admin cannot create organizations or list global identities, and a Global Admin grant is not an implicit membership in every organization. Support access is a separate time-bounded, organization-scoped grant.

People and access

People & access lists the current organization’s members with their handle, role, and state, and supports per-account changes and atomic bulk role or enablement updates. Every change is version-checked, so a membership that changed elsewhere cannot be silently overwritten. Disabling access preserves authored decisions and audit history while immediately revoking active sessions. An administrator cannot remove their own access, and an organization always retains at least one active administrator.

Enrollment: named invitations and join codes Available now

V3 has two enrollment paths with deliberately different authority. Both are created by an Organization Admin, both are stored only as hashes, and both are shown in plaintext exactly once.

Treat a join code as the access itself: anyone holding one can create a Nightwatch account in that organization. Both credentials can be revoked while pending or active, and both expire on their own. Visiting a link never consumes, expires, or creates enrollment state, and Nightwatch never echoes the credential back. Failed attempts are rate-limited per source and per identity, and a mistyped name or handle is rejected before it can spend a shared code’s abuse budget. The last remaining use of a join code is decided by a guarded increment inside the same transaction that creates the identity and membership, so two applicants racing for it cannot both succeed and the loser leaves no orphan account.

Join the watch: what a new person sees

The public entry is Join the watch, linked from the sign-in page and reachable at /join. The credential decides which organization is joined and with what role; the page cannot choose either. Nightwatch classifies the credential read-only before showing anything and presents the matching form.

1. Named invitation. The page names the organization, the invited email, and the access being granted. The applicant supplies a display name, a local handle, and a password—eight characters or more with a letter, number, and symbol—and confirms it. The address comes from the invitation and cannot be edited.
2. Join code. The page names the organization, the access, and the eligible email domain if one is set. The applicant supplies a display name, a local handle, their own email address, and a password with the same rule.
3. Where Turnstile is enabled it protects this form. Both forms work without JavaScript.
4. Someone who already has an identity should sign in instead and accept the invitation or redeem the code from their account; the existing global identity keeps its email, password, and MFA and simply gains a membership.

After the account exists, onboarding runs in six steps: access, identity, security, authenticator, avatar, ready. The security step reflects the organization’s policy—where MFA is required for the role, the authenticator must be set up before operational data opens; where it is optional, Not now defers it and Settings can complete it later. The authenticator step shows a QR when the host can generate one locally and always shows the manual setup key, then displays the recovery codes once, requiring an explicit acknowledgement that they were saved. The avatar step offers the Mission Identity set or an uploaded photo and can be skipped with Choose later. The final step reviews the verified email, organization, local handle, role, and authenticator state before entering Nightwatch.

Sessions, MFA, passwords, and recovery

Each person can review active sessions with their address, client, and last use, revoke an individual sign-in, sign out everywhere, change their password, and enroll a standard TOTP authenticator. Recovery codes are shown once and only their hashes are stored; each works once. Changing a password revokes every other active session.

Password recovery is deployment-wide, because identities and credentials are global. It answers identically for known and unknown addresses, sends a single-use link that expires in 20 minutes, bounds request rates per address and per source, and revokes sessions after the reset. Administrators can require MFA by role and configure session lifetime, secure-cookie behaviour, 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 sign-in, enrollment, and recovery. It is disabled by default and makes no Cloudflare request while disabled. When enabled, Nightwatch requires a public sitekey, a 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, and MFA—it does not replace them.

Configuration workflow

System configuration exposes nine validated categories: Environment & targets, Monitored services, Schedules & cadence, Source intelligence, Investigation context, 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. Model routes and budgets, retention windows, tuning, evidence storage, and the connector path are not in this editor; they remain file-configured and are preserved untouched when you save.

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 disable dormant memberships.
• Enrollment: prefer named invitations; keep join codes short-lived, use-limited, and domain-restricted; revoke a code the moment it has done its job.
• 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.

Enrichment and privacy boundary Available, expanding

Useful context comes from deterministic sources before another reasoning call. Nightwatch resolves exact typed public IPs through prefix, BGP origin, RIR registration, and RPKI, cached for seven days. An opt-in Spamhaus DROP source checks exact typed public IPs and ASNs against a 24-hour cached snapshot. A listing is supporting third-party context; no listing is not evidence of safety. Private, documentation, internal-marked, and prose-derived addresses never leave the system. ATT&CK, KEV, and EPSS context is also available. Observed DNS, configured resolvers, DHCP/IPAM, maintenance, CMDB, IdP, provider ranges, and additional governed sources remain next layers.

• Prefer customer-local truth to public inference.
• Forward-confirm reverse-DNS names and retain resolver, TTL, source, and observation time. A name is context, not proof of identity.
• Never send private addresses, internal names, accounts, or case contents to a public lookup service.
• Cache public facts, respect provider terms and limits, and show freshness and provenance.
• “Hosted by this provider” is context—not a safety verdict. “Not on this list” is not a clean bill of health.

The EDR configuration is a provider-neutral stub. It performs no endpoint query, loads no endpoint credential, and enables no response write. Any endpoint adapter must satisfy the same evidence, health, privacy, and failure contract before Nightwatch calls it available.

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.

Many witnesses, one evidence contract

Nightwatch can begin with one source without treating that source as the product. Connectors publish bounded observations with provenance, freshness, scope, completeness, sensitivity, and native identifiers. The reasoning and case layers consume that common envelope.

Required connector behavior

A new connector is complete only when contract fixtures prove cursor behavior, pagination, timeouts, rate limits, partial results, staleness, schema drift, permission loss, and secret redaction. Product-specific language and credentials belong in the optional connector package, not in the core case experience.

Current boundary: scheduled wire collection uses the executable at connector_path. It advertises JSON tool schemas and receives target credentials through NIGHTWATCH_SOURCE_* environment variables. Optional Python adapters currently serve the evidence planner and context registry; installing one does not replace scheduled wire collection. Both paths are being converged on the same manifest, envelope, health, receipt, and failure contract.

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 connector 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.

Know what belongs before judging what changed

Installed connectors supply observed network and service evidence. Nightwatch’s context layer adds the local identity, asset, history, ownership, and expectation facts needed to explain what that evidence means here. Deterministic code computes the facts and mismatches; a model explains the smallest defensible case from them.

Do not collapse the evidence labels

Priority order

1. Customer-local truth: telemetry, device identity, DNS, DHCP/IPAM, directory/IdP, CMDB/EDR/cloud inventory, maintenance, approved services, and dependency maps.
2. Locally computed history: novelty, peers, direction, volume, periodicity, account/device relationships, changes, and prior cases.
3. Cached public facts: registration and routing ownership, RPKI, official provider ranges, domain and certificate facts, ATT&CK, KEV, EPSS, and vendor advisories.
4. Optional passive DNS or exact-indicator reputation, disabled by default and queried only with an observed public key.
5. Model reasoning over the typed package—not a model doing CIDR math, date arithmetic, version comparison, or broad web searches.

Every context fact carries provenance, observation/fetch time, expiry, confidence, scope, and limitations. Failed public lookup means unknown. Learned history means “usual in the retained baseline,” never “approved.” Human notes remain attributed human context, not telemetry.

CONTEXT_REASONING_GUIDE.md contains the detailed source matrix and privacy rules. REASONING_ENGINE.md is the complete source-to-case reasoning contract.

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.

The Watch Partner

Nightwatch sounds like an experienced analyst working beside the operator: calm, candid, specific, and ready to show the evidence. That voice governs interface copy, generated analysis, deterministic fallbacks, notifications, errors, exports, and documentation.

Say what matters in this order

1. Lead with the answer.
2. Explain the effect on people, systems, risk, or the decision.
3. Show the few facts that make the answer defensible.
4. Name the strongest ordinary explanation or the missing fact that could change the judgment.
5. State what Nightwatch already checked and the one remaining move, if there is one.
6. Keep raw records, codes, identifiers, and calculations available in detail.

Personality without theater

The voice is human because it uses natural words, makes a clear judgment, and respects the reader’s time. It does not use swagger, snark, synthetic empathy, product praise, corporate filler, or dramatic metaphors. It does not soften harm or manufacture urgency. After Hours and Behind the Rack may keep their atmosphere, but a metaphor never replaces a fact or hides a limitation.

NIGHTWATCH_VOICE.md is the complete Watch Partner editorial guide for vocabulary, before-and-after patterns, uncertainty rules, interface conventions, accessibility, localization, and the release checklist.

How Nightwatch reasons

Nightwatch is an observable reasoning pipeline. The model is one replaceable specialist near the end, not the pipeline itself. Collection, provenance, normalization, memory, arithmetic, correlation, routing, Daylight, workflow, and audit belong to the harness.

What each stage actually does

Evidence boundaries and source attribution

Every claim carries where it came from, and the product keeps the categories apart in wording and in structure: the wire shows for a direct observation, the stored case shows for a persisted Nightwatch fact, a named person noted for attributed human context, a named provider listed for third-party context, Nightwatch assesses for a reasoned judgment, and Nightwatch cannot confirm for an evidence boundary. Human notes never become telemetry. Third-party reputation is never a local verdict. A negative lookup is unknown, not clean.

Every context fact also carries observation or fetch time, expiry, confidence, scope, and limitations, and a typed source registry records which sources are available, disabled, planned, unsupported, or unavailable—so a source that is switched off cannot masquerade as collected evidence.

Autonomous means doing the homework Available, expanding

Nightwatch resolves, computes, or fetches every relevant fact it is already allowed to obtain before asking the analyst. It reuses fresh case evidence, performs deterministic joins and comparisons, then makes the narrowest useful read-only connector or approved public lookup. Only genuinely inaccessible evidence, human intent, business approval, off-source events, or protected action authority should come back as a question.

Evidence, Harness, Model

Evidence is the versioned fact package from connectors, case memory, local history, public facts, and attributed human knowledge. Harness is Nightwatch: source availability, collection, normalization, caches, permissions, budgets, memory, validation, Daylight, workflow, approvals, and audit. Model is a replaceable specialist that interprets the ambiguity left in the bounded package. A model can explain evidence; it cannot grant itself a source or a write.

The dashboard’s At the Chalkboard room teaches this visually. The repository’s REASONING_ENGINE.md is the normative reasoning and Daylight contract; EVIDENCE_CONNECTORS.md defines source authority and the evidence envelope.

A proper question names the exact missing fact, why Nightwatch could not get it, which source or person can answer, and what each answer changes. “Was change CHG-1842 meant to authorize Aaron’s account on BUILD-04 at 02:10 UTC?” is useful. “Is this expected?” simply hands the investigation back to the human.

The cumulative loop

1. Frame the proposition and decision.
2. Inventory current facts, coverage, freshness, history, and human context.
3. Name precise unknowns and classify each as stored, locally computable, safely fetchable, human-only, unavailable, or prohibited.
4. Resolve local and cached facts, then run the narrowest permitted read-only queries.
5. Reconcile conflicts, test the ordinary explanation, and stop when the decision is supported or declared budgets and sources are exhausted.
6. Reason over the typed result and ask only for the inaccessible remainder.
7. Persist the trace, attribution, gaps, and material case change.

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.

Sealed exercise evaluation Library foundation

Lab exercises can test whether Nightwatch helps a person solve the case without teaching the system the answer. Nightwatch investigates blind; an evaluator freezes the case snapshot; only then does an authorized person reveal a separately stored exercise key. The key records expected campaigns, stages, entities, distractors, known limitations, and the useful action.

The answer key must remain outside the ordinary Nightwatch database and unavailable to schedulers, correlators, reasoning routes, tools, prompts, and the operator board. Saying “this is one campaign” before the snapshot would contaminate the test. After reveal, the evaluator may score evidence and stage coverage, grouping and fragmentation, contamination, story quality, prioritization, and action quality.

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.
• Treat a join code as the access itself. Keep it short-lived, use-limited, domain-restricted where possible, and revoke it when the group has joined. Prefer a named invitation whenever the person is known.
• 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 evidence-source 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 Settings workspace exposes implemented controls and reserves clearly labeled locations for future safe controls, while keeping evidence contracts and authority fixed. A reserved location states its intended contract and says Planned · not implemented; it never renders as a control you can operate. This is the proposed order of work.

Documentation version v2026.09.03, for Nightwatch v26.09.03. This manual covers V3 only. When product behavior and this site disagree, treat that as a defect: verify against the running release, the example configuration, and the release tests, then update both in the same change.