nano-rs/nano

A lightweight, opinionated SIEM. Search, detection, and triage for security analysts who want to ship signal — not babysit a data lake.

Website · Docs · Discord · Hosted

---

nano is built around a small set of beliefs:

• The UDM is the contract. Logs land in 75+ explicit columns; ad-hoc fields go in ext. Searches stay fast because the schema does the work.
• nPL beats SQL for hunting. A piped query language (error | stats count by src_ip | where count > 10) keeps analyst muscle memory portable.
• Detections have a lifecycle. Rules move Staging → Live → Alerting. Match counts and signals are visible at every step.
• Restraint over decoration. 1px borders, 11–13px text, mono for IDs and timestamps. The UI is the same density a terminal user expects.

This repository is the open-core engine, licensed under AGPL-3.0. Hosted plans, the pivt AI assistant, Cases, incidents, and risk scoring are available from nano.rs.

Install

One command on any host with Docker:

curl -fsSL https://get.nano.rs | bash

One command. 45 seconds. Working nano instance. ▶ Watch on YouTube

The installer clones this repo to ~/nano, generates secrets, pulls the prebuilt images from ghcr.io/nano-rs, brings up the stack (postgres + clickhouse + api/search/jobs/web + vector + nginx), and walks you through creating the first admin account. Open http://localhost when it finishes.

Prereqs: Docker, docker compose v2, git, openssl, curl.

Minimum host: 2 vCPU, 4 GB RAM — the lowest stable spec, suitable for up to ~10 GB/day of ingest. Below this, ClickHouse and the API will OOM under load.

Hardware sizing: install.sh detects CPU and RAM on every install or rerun and scales ClickHouse query/merge/insert settings, PostgreSQL, Vector, and the containers while reserving host headroom. The 2 vCPU / 4 GB floor keeps ClickHouse at 2 GB with the NAN-4988 admission limits. Add any setting after the installer-owned sizing block in .env to pin an operator override.

ClickHouse memory: without enrichment, 2–4 GB for ClickHouse is fine for small and test tenants. Enrichment (the IPinfo, Tor and ThreatFox feeds, on by default) requires 6 GB: use a larger host or set CLICKHOUSE_MEM_LIMIT=6G in .env, or turn the feeds off with PLATFORM_FEEDS_AUTO_UPDATE=false. Plan for 6 GB if you enrich. With too little memory the IP dictionary cannot load: events get no geo/ASN, ingest keeps working, and SIEM Health shows the dictionary failing and how much memory the dictionaries take. install.sh prints a notice when feeds are on and the limit is below 6 GB.

For non-interactive installs, pre-set NANO_ADMIN_EMAIL, NANO_ADMIN_NAME, NANO_ADMIN_PASSWORD, NANO_BASE_URL, and optionally NANO_SCHEMA_PROFILE (udm | ocsf, see below) before piping. See .env.opensource.example for the full env-var surface.

Setup token. Until the first admin exists, creating it needs the setup token that install.sh generates (NANO_SETUP_TOKEN in ~/nano/.env). The installer uses it itself, so a normal install asks for nothing. If an install stops before the admin is created, re-run ./install.sh, or open the web UI and enter the token on the setup page. An install that already has an admin never needs it.

Deploy with your AI agent (nano Self-run)

The nano-deploy agent skill lets Claude Code, Codex or another coding agent size, install, verify and operate nano Self-run (the licensed enterprise edition) on your own hosts: single node, 3-node HA or Helm. It runs a read-only preflight first, asks before every change and never prints secrets. See skills/ for install lines.

HTTPS / TLS

The default stack serves plain HTTP on port 80. To serve HTTPS, bring your own certificate — drop a cert chain and private key into config/nginx/ssl/:

config/nginx/ssl/fullchain.pem   # certificate (leaf + intermediates)
config/nginx/ssl/privkey.pem     # private key

Get them however you like — Let's Encrypt/certbot, your own CA, or a self-signed pair for testing (./config/nginx/generate-ssl.sh). Both *.pem files are gitignored. Then bring the stack up with the TLS overlay:

docker compose -f docker-compose.opensource.yml -f docker-compose.tls.yml up -d

nginx serves HTTPS on :443 and redirects :80 → :443. Set BASE_URL=https://your.domain in .env so login cookies get the Secure flag. Renew certs out of band and docker compose ... restart nginx to pick them up. See config/nginx/ssl/README.md for details.

Schema profile: OCSF or UDM

New installs store events in OCSF (Open Cybersecurity Schema Framework 1.9), the open, vendor-neutral standard schema. Fields are OCSF paths (src_endpoint.ip, actor.user.name, process.cmd_line, metadata.log_source, …), and the official parsers and detection rules follow the OCSF content channel (main in nano-rs/parsers and nano-rs/rules).

UDM (Unified Data Model), nano's earlier native schema with short field names (src_ip, dest_ip, process_name, …), stays supported for existing installs. Its content stays on the legacy/clickhouse branch of both repositories. Existing installs keep the profile they were installed with; moving one to OCSF is a separate, planned migration.

# Interactive install prompts for this (default: ocsf). To preset it:
NANO_SCHEMA_PROFILE=ocsf curl -fsSL https://get.nano.rs | bash
# Legacy UDM schema:
NANO_SCHEMA_PROFILE=udm curl -fsSL https://get.nano.rs | bash

Pick once. The schema profile is fixed at first install and recorded in .env. It selects the ClickHouse tables, parsers, and fields the whole stack runs against, so it can't be switched after you've ingested data without a full re-ingest into a fresh deployment. A new install defaults to ocsf; an .env with no NANO_SCHEMA_PROFILE predates the choice and keeps udm.

What's in the box

• Ingestion — Vector-based collectors with VRL parsers (HTTP push, syslog, S3 pull). Parser content is published separately under Apache-2.0.
• Storage — ClickHouse for events (daily partitions, 90-day default TTL), PostgreSQL for metadata.
• Search — nPL parser, ClickHouse SQL generator, field-stat sidebar, bloom-filter-aware tokenization.
• Detection — scheduled (cron) + real-time (materialized view) rules, signal logging, prevalence-based noise reduction.
• Alerts — lifecycle (new → triaged → resolved), grouping, dedup.
• Marketplace — install + configure out-of-the-box enrichment providers (threat intel, identity, asset inventory, geolocation). Coverage indicator across UDM fields.
• Web UI — React SPA, lazy-loaded, runs in any modern browser.

Detection rule editor — Staging → Live → Alerting lifecycle, MITRE ATT&CK tagging, baseline impact, validation, and version history.

Hunting in nPL — sourcetype="windows_sysmon" event_id=1 | timechart span=10m count by parent_command_line limit=8. Stacked per-series visualization, top-N split-by, results table inline.

Marketplace — out-of-the-box enrichment catalog (threat intel, identity, asset inventory, geolocation). Coverage indicator tracks which UDM fields have a provider behind them.

Develop from source

The Install flow above is the right path if you just want to run nano. To hack on the engine itself:

• Prereqs: Rust stable, Node 20+, PostgreSQL 18+, ClickHouse 24+
• Bring up Postgres + ClickHouse via your usual local tooling
• ./scripts/start-microservices-dev.sh — launches nanosiem-api (3000), nanosiem-search (3002), and nanosiem-jobs with sane local defaults
• cd nanosiem-web && npm install && npm run dev (port 5173)

See CONTRIBUTING.md for the day-to-day dev workflow and what env vars to override.

Full documentation: nano.rs/docs.

Architecture

+------------+     +------------+     +-------------+
|  Vector    | --> | nanosiem-  | --> | ClickHouse  |
|  parsers   |     | api  :3000 |     | (events)    |
+------------+     +------------+     +-------------+
                         |                   ^
                         v                   |
                   +------------+     +------+------+
                   | PostgreSQL |     | nanosiem-   |
                   | (rules,    |     | search:3002 |
                   |  alerts,   |     +-------------+
                   |  audit)    |             ^
                   +------------+             |
                                       +-------------+
                                       | nanosiem-   |
                                       | web (SPA)   |
                                       +-------------+

• nanosiem-api — rules, alerts, settings, ingestion, OpenAPI at /swagger-ui
• nanosiem-search — query execution, field stats, log fetch
• nanosiem-jobs — scheduled detection runner, repository sync
• Both Postgres + ClickHouse are required. The DualPool abstraction wires the two together; boot fails fast if either is unreachable.

Documentation

• Getting Started — bring up nano and ingest your first feed
• Search Commands (nPL) — pipe commands, eval functions, syntax reference
• Detection Authoring — write rules, manage lifecycle, tune for noise
• UDM Reference — the 75+ explicit columns the schema is built around
• Coding Agents — manage searches, parsers, and detections via Claude Code / Codex pointed at your nano instance. The hosted plan ships an in-app AI assistant (pivt); coding-agents brings equivalent leverage to open-core deployments, locally.

Ecosystem

The engine works on its own, but a small set of companion repos ships the content layer most teams want on day one:

• nano-enrichments — threat-intel feeds, identity providers, and asset-inventory adapters wired into the in-app marketplace
• parsers — Vector + VRL parsers for common log sources (proxy, EDR, cloud audit, Windows)
• rules — curated detection rules, importable into nano via the rule library
• nanodac — detection-as-code: define rules in Git, sync to nano via GitOps
• models — LiteLLM model catalog backing pivt's AI features

What's open vs. hosted

This repository is the open-core engine — functionally complete for ingestion, search, detection, and alerting. Some platform features ship only in the hosted distribution at nano.rs:

• Cases — investigation management, collaborative notebooks
• Incidents — multi-case orchestration, queue routing
• pivt — ambient AI assistant covering detection generation, rule tuning, query review, parser editing, and shadow investigation
• Risk scoring — entity-level risk across users, hosts, and cloud accounts
• Auto-tuning — AI-driven false-positive reduction

Self-hosting nano with these features requires a commercial license — [email protected].

Roadmap

• Public detection-rule library (community-contributed)
• OpenTelemetry log/trace ingestion
• Parser SDK for community-authored VRL parsers
• Saved-query API + CLI client
• See open issues for the active backlog

Community

• Star this repo if nano is useful to you — it helps others find it
• Discord — questions, design discussions, show-and-tell
• Good first issues — curated entry points for new contributors
• Discussions — longer-form Q&A and proposals

Contributing

We accept community contributions under a CLA — see CONTRIBUTING.md and .github/ICLA.md. DCO is not sufficient because nano is open-core; the CLA grants nano, LLC the sublicensing right needed to keep parts of the platform proprietary while still accepting your patches.

Bug reports and feature requests: issue templates.

Security

Found a vulnerability? Please don't open a public issue. See SECURITY.md — short version: email [email protected] with a 90-day disclosure window.

License

The engine in this repository is licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.

If AGPL doesn't fit your deployment, a commercial license is available — get in touch at [email protected].