Protect your endpoints with open-source threat detection, real-time monitoring, and automated response.
NKOSI is a Linux-native antivirus and Endpoint Detection & Response (EDR) platform built in Rust. It provides real-time file monitoring, process behavior analysis, network threat detection, YARA rule scanning, SHA-256 hash verification, and automated response actions — all running locally on your server or workstation.
The name NKOSI means "king" in Lingala. Just as a lion protects its domain, NKOSI guards your Linux endpoints with a complete, modular security pipeline.
| Feature | Description |
|---|---|
| Real-time monitoring | Filesystem, process, and network monitoring via inotify/fanotify and procfs, plus an optional eBPF sched_process_exec tracepoint (no polling race window) |
| Multiple detection engines | SHA-256 hash matching, YARA rules, static analysis (ELF/PE packer & suspicious-import detection, basic deobfuscation), behavior analysis, network IOC |
| Risk scoring | Weighted scoring engine with temporal correlation — detections spread over several steps (recon → privesc → C2) escalate even when each step alone is below threshold |
| MITRE ATT&CK mapping | Every detection is annotated with a standard technique (T1003, T1548, T1496...) |
| Automated response | Allow, alert, kill process, block IP, quarantine, restore, delete — with a Human-in-the-Loop mode (pending actions, timeout, remembered decisions) |
| Threat Intelligence | Local threat database updated from MalwareBazaar, ThreatFox, URLhaus |
| Incident management | Automatic incident creation, correlation, and explainability, with analyst-driven false-positive marking and rate tracking |
| Quarantine | Safe isolation of malicious files with restore capability |
| Firewall integration | Automatic IP blocking via iptables/ip6tables, baseline reloaded on every agent start (survives reboots) |
| Self-protection | Detects an unclean agent shutdown (kill/crash) and raises an incident; independent systemd watchdog; binary/units made immutable post-install |
| Fleet grouping | Free-form Agent.group tag (e.g. "prod-web") to filter/organize the dashboard across multiple agents |
| CLI & REST API | Full command-line interface and HTTP API |
| Central console | Multi-agent centralized monitoring API, optional shared-token auth |
| Fleet monitoring & remote response | Every agent streams host telemetry to the central (CPU/RAM/disk/network, per-process CPU & memory, network connections mapped to processes, firewall state). From the dashboard: kill/suspend processes, ban them by hash/path/name, isolate a process from the network, block/whitelist IPs, quarantine binaries, with a full per-process history and an audited action log |
| Simulation mode | Built-in threat simulation for testing and validation |
┌─────────────────────────────────────────────────────────────────┐
│ LINUX ENDPOINT │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Filesystem │ │ Process │ │ Network │ │
│ │ Monitor │ │ Monitor │ │ Monitor │ │
│ │ (inotify/ │ │ (procfs) │ │ (proc/net) │ │
│ │ fanotify) │ │ │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │
│ │ │ │ │
│ └─────────────────┴──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Event Bus │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────────┬───────────┼───────────┬────────────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Hash YARA Static Behavior Threat │
│ Engine Engine Analyzer Engine Intel │
│ │ │ │ │ │ │
│ └───────────┴───────────┴───────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌────────────────┐ │ │
│ │ Risk Engine │◄──────────────┘ │
│ └───────┬────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ CLEAN SUSPICIOUS MALICIOUS │
│ │ │ │ │
│ Allow Alert ┌──────┴──────┐ │
│ │ Response │ │
│ │ Engine │ │
│ │ │ │
│ ▼ ▼ │
│ Kill Block │
│ │ │
│ ▼ │
│ Quarantine │
│ │ │
│ ▼ │
│ Event Log │
│ │ │
│ ▼ │
│ Local Database │
│ │ │
│ ▼ │
│ CLI API Console UI │
└─────────────────────────────────────────────────────────────────┘
See doc/PREREQUIS.md for the full list.
sudo ./scripts/install-deps.shcargo build --workspace # development
cargo build --release # production./nkosi.sh start # start all components
./nkosi.sh status # check status
nkosi-cli scan /home -r # scan files
nkosi-cli simulate # run threat simulationSee doc/USAGE.md for ecosystem startup and doc/openapi.yaml for the REST API reference.
See doc/INSTALLATION.md for details.
make install
sudo systemctl enable --now nkosi-agentNKOSI alone should not be the only protection on a critical server (see
PLAN_PRODUCTION.md). scripts/install-defense-layers.sh
installs and configures the complementary layers (fail2ban, TLS reverse
proxy, auditd, AIDE, encrypted restic backups, optional lightweight SIEM):
sudo ./scripts/install-defense-layers.sh # layers 1, 2, 4, 5, 6 (all by default)
# or: make harden
# after installing the .deb package: sudo nkosi-hardenLayer 4 (Loki/Promtail/Grafana) runs as native binaries under systemd — no Docker required.
See doc/INSTALLATION.md for details.
Complements (does not replace) the procfs-polling process monitor with a
sched_process_exec tracepoint — no polling window for a process that spawns
and exits between two scans. Requires a nightly toolchain + bpf-linker
(not needed to build the rest of NKOSI):
rustup toolchain install nightly --component rust-src
cargo install bpf-linker
make ebpf # builds and installs the object
cargo build --release -p nkosi-agent --features ebpf| Component | Port | Description |
|---|---|---|
nkosi-agent |
— | Local EDR agent with monitors, engines, and response |
nkosi-cli |
— | Command-line interface for scans, firewall, quarantine, agent/actions/rules |
nkosi-api |
8080 | REST API |
nkosi-central |
50051 | Central gRPC server for multi-agent collection |
nkosi-console |
9090 | Centralized multi-agent REST API (optional shared-token auth) |
nkosi-ui |
— | Desktop graphical interface (TUI) |
nkosi-dashboard |
— | Electron desktop dashboard (REST + console + gRPC) |
Each agent started with NKOSI_CENTRAL_ADDR pushes a telemetry snapshot to
nkosi-central and polls it for actions queued from the dashboard
(Flotte de serveurs → server → Ressources / Processus / Réseau / Pare-feu /
Actions, and a per-process page with its complete history).
| Variable (agent) | Default | Effect |
|---|---|---|
NKOSI_TELEMETRY_INTERVAL |
15 |
Seconds between snapshots (min 5) |
NKOSI_COMMAND_POLL_INTERVAL |
3 |
Seconds between action polls (min 1) |
NKOSI_REMOTE_ACTIONS |
enabled | 0 = read-only monitoring: every action except "process detail" is refused by the agent |
NKOSI_CONFIG / NKOSI_AGENT_ID_FILE |
— | Run a test agent next to a system install without touching /etc/nkosi or /var/lib/nkosi |
| Variable (central) | Default | Effect |
|---|---|---|
NKOSI_CENTRAL_DB |
./data/central.db |
Central database path |
NKOSI_PROCESS_SAMPLE_TOP |
25 |
Most active processes sampled per snapshot (per-process charts) |
Safeguards enforced by the agent (the central validates too): no action on PID
0/1, kernel threads or the agent itself; protected system processes (sshd,
systemd, journald, NKOSI services…) need an explicit force; start_ticks
check rejects an action if the PID was reused since it was displayed; the
central's IP and local addresses can never be blocked. Retention on the
central: resource and process samples 24 h, ended processes 7 days, action log
30 days. Process paths, file descriptors and firewall control for other users'
processes require the agent to run as root (the systemd service does).
NKOSI includes a built-in simulation engine for testing and validation.
See doc/USAGE.md for CLI details and doc/USAGE.md for API setup.
# CLI
nkosi-cli simulate --scenario all --cycles 5
# API
curl -X POST http://localhost:8080/api/simulate \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"scenarios": ["Ransomware", "Trojan", "Backdoor"], "count": 2}'
# Automatic (daemon mode)
# Set in nkosi.toml:
# [simulation]
# enabled = true
# interval_seconds = 60
# scenarios = ["Ransomware", "Cryptominer", "Webshell"]doc/INSTALLATION.md— Full installation guidedoc/PREREQUIS.md— System prerequisitesdoc/USAGE.md— Complete usage guide (A to Z)doc/CONFIGURATION.md— Configuration guide: remediation / decision-making (consent HITL) and notification backends (email, SMS, Telegram, webhook, syslog)doc/advanced.md— Advanced features roadmap for production serversdoc/implementation-plan.md— 3-phase implementation plan for advanced featuresdoc/openapi.yaml— REST API specification (OpenAPI 3.0)doc/grpc-openapi.yaml— Central gRPC API specification (OpenAPI 3.0)
| Layer | Technology |
|---|---|
| Language | Rust (2024 edition) |
| Async runtime | Tokio |
| Database | SQLite (bundled) |
| Detection | YARA, SHA-256, regex heuristics |
| Communication | gRPC (tonic), REST (actix-web) |
| Monitoring | inotify, fanotify, procfs, optional eBPF (aya, feature ebpf) |
| Firewall | iptables / ip6tables |
| Build | Cargo workspace (18 crates) |
| Dashboard | Electron + Vue 3 (separate nkosi-dashboard/) |
NKOSI/
├── nkosi-common/ # Shared types, config, errors
├── nkosi-core/ # Config loading, DB initialization
├── nkosi-db/ # SQLite repositories and schema
├── nkosi-monitors/ # Filesystem, process, network monitors
├── nkosi-engines/ # Hash, YARA, static, behavior engines
├── nkosi-risk/ # Risk scoring engine
├── nkosi-response/ # Response engine (quarantine, kill, block)
├── nkosi-scanner/ # Rootkit, integrity, kernel, firewall scanners
├── nkosi-ti/ # Threat intelligence feeds
├── nkosi-notify/ # Notification system (email, webhook, syslog, telegram, sms)
├── nkosi-agent/ # Main agent binary + simulation
├── nkosi-cli/ # CLI binary
├── nkosi-api/ # REST API
├── nkosi-central/ # Central gRPC server
├── nkosi-console/ # Centralized multi-agent REST API
├── nkosi-dashboard/ # Electron client (Vue 3 + Tailwind + gRPC)
├── nkosi-ui/ # Desktop UI
├── nkosi-ebpf/ # eBPF program (sched_process_exec tracepoint) — own Cargo workspace
├── nkosi-ebpf-common/ # Event struct shared between nkosi-ebpf and nkosi-monitors
├── doc/ # Documentation
└── tests/ # Integration tests
NKOSI is designed with security in mind:
- No cloud dependency — All detection happens locally
- Local threat database — No file scanning via remote APIs
- Reduced privileges — UI does not run with permanent root
- Auditability — Every action is logged with timestamp, score, and details
- Configurable thresholds — Risk levels and response actions are adjustable
- Graceful degradation — Non-critical module failures do not stop the agent
- Self-protection — An unclean agent shutdown (kill/crash) raises an incident on the next
start; an independent systemd watchdog (
OnFailure=) alerts even if the agent never restarts; binary and systemd units are made immutable (chattr +i) post-install. This is friction against casual tampering, not a guarantee against a determined root attacker.
[Add your license here]
NKOSI — The lion guards your Linux.