nano SIEM
Getting Started

nano-connect CLI

Supported in:Self-hosted

Generate local collectors with the Bash nano-connect client, issue a per-source ingest token for each, and verify that events land under the right source

The Bash nano-connect client onboards data sources into nano. It generates local Vector collectors for syslog devices, Linux journald and log files, and Windows Event Log and Sysmon. It issues one ingest token per source, and checks in Search that events arrive under that source.

It works the same way on every deployment: Open and Self-run. Both expose the same Log Sources, ingest-token, parser and search APIs. The only difference is where events are sent; see Ingest destination.

Download the client

You need Bash 3.2 or later, curl and standard Unix tools. jq is optional, and Node.js isn't used. Download the script, review it, and check its version:

curl -fsSL https://github.com/nano-rs/connect/releases/latest/download/connect.sh -o connect.sh
bash connect.sh --version
bash connect.sh --help

For automation, fetch connect.sh and connect.sh.sha256 from the same versioned release. Run sha256sum --check connect.sh.sha256 before you execute it.

Before you start

Set your nano URL and supply an API key through your secret manager:

export NANO_URL="https://nano.example.com"
export NANO_API_KEY="..."   # from your secret manager

The key needs these permissions:

ActionPermission
Discover sources, tokens and the ingest destinationlog_sources:view
Issue, bind, rotate and revoke ingest tokenssettings:system
Import and publish a parser (--deploy-parsers)parser_repositories:import, log_sources:create, source_configs:edit, log_sources:deploy
Prove delivery (connect, verify)search:execute, plus visibility of the source

Alternatively, set NANO_EMAIL. The client signs in and, after you confirm, creates an API key named nano-connect with these permissions. The API key never authenticates events: each collector uses its source's ingest token.

Ingest destination

Self-run on Kubernetes receives events on a dedicated ingest frontend with its own hostname, for example https://ingest.example.com. This keeps ingest load away from the app. A dedicated ingest frontend is coming to Self-run on Docker Compose; until then, Compose installs (open core and Self-run) receive events at /ingest on the app host.

The client chooses the destination in this order:

  1. --ingest-url: the exact URL for the chosen transport.
  2. --ingest-base: your ingest frontend's origin, for example https://ingest.example.com.
  3. The ingest base your deployment reports (NANO_INGEST_PUBLIC_BASE_URL), when it differs from the app URL.
  4. The app host, only when the deployment reports no dedicated ingest base. On a Self-run deployment the client warns you when it falls back.

When a dedicated ingest base is configured, the client never sends events to the app host. It refuses an --ingest-url or --ingest-base that points there. If the key can't read the ingest endpoint on a Self-run deployment, pass --ingest-base.

bash connect.sh add-source --sources cisco_asa \
  --ingest-base https://ingest.example.com --non-interactive

Generate a collector

List the sources you can collect. The output shows the built-in syslog sources, your deployment's log sources, and syslog-capable parsers from its parser registry:

bash connect.sh list-sources

Syslog devices

bash connect.sh add-source --sources cisco_asa,palo_alto:tcp \
  --deploy-parsers --out-dir ./fw-collector --non-interactive

For each source that isn't a log source yet, --deploy-parsers imports and publishes its parser from the registry. The client then issues an ingest token bound to that source, and writes vector.toml, docker-compose.yml and a private secrets/ directory. Append :tcp, :udp or :http to choose the local listener. Built-in sources keep their usual ports, for example UDP 5514 for Cisco ASA and TCP 5515 for Palo Alto. Other sources get a stable port in 5600–5699. The generated files list them.

On the collector host, start it with --run, or review the files and start it yourself:

docker compose -f ./fw-collector/docker-compose.yml up -d

Point your devices at that host. The listeners have no authentication, so keep them on a trusted network.

Linux endpoints

bash connect.sh add-agent --os linux \
  --files '/var/log/myapp/*.log' --file-source json_generic \
  --out-dir ./linux-agent --non-interactive

The agent collects journald (linux_journald, and linux_sysmon for Sysmon for Linux) plus any files you list. --file-source names the source the files land in, and must have a parser or log source. Install Vector 0.59 on the endpoint. Copy vector.toml to /etc/nano-collector/vector.toml and secrets/ to /etc/vector/secrets (mode 0700, files 0600), then install the generated nano-collector.service. Use --no-journald to collect files only.

Windows endpoints

bash connect.sh add-agent --os windows --out-dir ./windows-agent --non-interactive

The agent reads Application, System, Security, Sysmon, PowerShell and Defender event logs. It sends Sysmon events to windows_sysmon and everything else to windows_event. Run the generated install-agent.ps1 as Administrator on the endpoint. It verifies the signed Vector MSI, restricts the secrets directory to Administrators and SYSTEM, and installs the service.

Aggregators

To fan many endpoints into one collector:

bash connect.sh add-aggregator --sources cisco_asa --out-dir ./hub --non-interactive
bash connect.sh add-agent --os linux --target hub.internal:9000 --out-dir ./linux-agent --non-interactive

Agents generated with --target need no API key. The agent-to-aggregator hop isn't authenticated, so keep it on a private network. The aggregator forwards each source with its own ingest token.

Transports

HEC and HTTP are both fully supported. Both use the source's ingest token, send the original log line, buffer to disk, and store events under the same source. HEC is the default.

TransportFlagDestinationAuth
HEC (default)--transport hecyour deployment's HEC listener, port 8088 by defaultAuthorization: Splunk <token>
HTTP--transport http<ingest>/ingestAuthorization: Bearer <token>

The token decides which source an event is stored under, whatever the sender declares.

HTTP goes through the ingest edge, which terminates TLS like the app. HEC uses whatever your deployment puts in front of the HEC listener; on open core it's plain HTTP by default. Choose HTTP if the collector crosses a network you don't trust and your HEC listener has no TLS, or if only the ingest edge is reachable.

Prove delivery

Send a test event through nano's ingest path and wait until it appears in Search under the source:

bash connect.sh connect --source cisco_asa --non-interactive

This doesn't test the hop from your device to the collector. After real events flow, check for fresh events under the source:

bash connect.sh verify --source cisco_asa --non-interactive

verify searches metadata.log_source over the last 15 minutes (--window changes this). It reports how many events arrived and how many were mapped to an OCSF class, and exits nonzero if none arrived. In Search:

metadata.log_source="cisco_asa" | stats count by class_name

To prove specific requests through a collector, send a distinct marker in each request. List them in a private file, one source marker pair per line, then run:

bash connect.sh verify --evidence-file /private/request-evidence.txt --wait-seconds 120

Tokens

Each source gets its own named ingest token. The client saves it privately in ~/.config/nano-connect-bash and reuses it on later runs. In a collector, Vector reads tokens from secrets/; they never appear in vector.toml or on screen.

  • --token-dir DIR uses tokens you already have, one file per source. An unbound token is bound to the source. A token bound to another source, or a revoked token, is refused.
  • rotate-token --source cisco_asa --out-dir ./fw-collector issues a replacement and saves it, then revokes the old token. Restart the collector afterwards.
  • revoke-token --source cisco_asa revokes the token the client issued. Vector refuses it within seconds.

You can also manage tokens in Log Sources.

OpenTelemetry exporters

bash connect.sh otlp-config --source myservice --out-dir ./otel --non-interactive

This writes a private otel.env with OTEL_EXPORTER_OTLP_ENDPOINT=<ingest>/otlp and the source's Bearer token. Use one exporter configuration for each source. See OTLP.

Troubleshoot

SymptomCheck
403 during discoveryThe key needs log_sources:view. Issuing tokens needs settings:system.
token delivery is not configuredThe deployment can't deliver tokens to Vector (NANO_INGEST_TOKENS_DELIVERY). Ask your operator.
refusing to send events to the app hostYour deployment has a dedicated ingest frontend. Drop the app-host --ingest-url or --ingest-base.
Self-run deployment asks for --ingest-baseThe key can't read the ingest endpoint. Pass your ingest frontend's origin.
No bindable source or registry parserRun bash connect.sh sync-parsers, or create the log source first.
Accepted but not searchableCheck the collector logs and the source's parser. Search for the marker without the source filter to see where it landed.
Searchable but unparsedCheck the raw format against the source's parser. Parser changes apply to new events only.

What's next

On this page