Kodachi SOC Guide
kodachi-soc collects full host telemetry, scores your posture, annotates threats with MITRE ATT&CK, and feeds the dashboard's neural-map SOC page. It never kills a process, and active response is health-control's job. It does change state. Any user who runs snapshot writes its working files: a line appended to score-history.jsonl so it can show a trend, its cached scan results, and a lock file. Every write that changes what a LATER run trusts is root-only: refresh seeds the baselines that later runs compare against, covering file integrity, autostart entries, SUID binaries, file capabilities, critical paths, log sizes and kernel taint, and a cold cache makes snapshot trigger one in the background; policy approve, revoke and renew write the stored exposure policy; exposure acknowledge marks a finding acknowledged and writes a checkpoint; arming and disarming the watcher run systemctl enable --now and disable --now on the watcher unit; and arming it also applies /etc/sysctl.d/90-kodachi-host-exposure.conf, which sets kernel.io_uring_disabled=2 for the whole machine, because the watcher cannot report healthy coverage without it.
v10.0.3 · 8 commands · 8.8 MB · 10 cluster hubs · reads telemetry, writes host-exposure policy
Documentation Navigation
This page is scenario-first (what the SOC collects, how the dashboard reads it, and how to run it safely). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | kodachi-soc |
| Version | 10.0.3 |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 8.8MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Security & Authentication |
| Description | Kodachi SOC host-security monitor: full telemetry collector with MITRE ATT&CK annotations |
| JSON Data | View Raw JSON |
SHA256 Checksum
a10d19dd848e693cfa2b0ec845179b047432301f7ce8c4b4dfdb1db63d8a051f
Key Features
Telemetry and Detection
| Feature | Description |
|---|---|
| SOC collectors | vitals, network, connections, processes, threats, auth, privacy, system, gathered in a single pass |
| Host threat detection | SHA-256 FIM on sensitive files and on critical binary paths (/bin, /sbin, /usr/bin, /usr/sbin, /usr/local, stat-gated so unchanged files are never re-hashed), SUID/SGID drift, ld.so.preload and process LD_PRELOAD hijack checks, kernel-taint baseline, capability audit, /dev rootkit-artifact scan, account integrity (duplicate UID-0, empty-password accounts), log-tamper detection, and CIS/Lynis posture (mount nosuid/nodev, AppArmor enforce count, kernel lockdown) |
| LAN attack watch | Listens to the local network for a set time and reports attacks against this machine: ARP spoofing and gateway impersonation, a rogue DHCP server, a rogue IPv6 router and port scans. Read-only: it sends nothing and blocks nothing |
| Real-time file scan | Warn-only: checks files written to the home folders, /root, /tmp, /dev/shm and removable media against a known-malware hash list and raises a host exposure alert on a match. It never blocks, moves or deletes a file. Off by default: it needs a free personal abuse.ch Auth-Key first, see Before you turn it on |
| Boot-autoload monitoring | Baselines every autostart entry (systemd units and generators, cron, profile.d, MOTD, XDG autostart, udev, PAM) and alerts on NEW or changed startup items, with package-ownership suppression so routine installs never raise a false alarm |
| Hardening-aware | Recognises Kodachi's own hardening, so system-wide hardened_malloc in ld.so.preload and the tirdad out-of-tree kernel module are reported as expected, not as compromise |
| MITRE ATT&CK annotations | Threat findings carry ATT&CK technique IDs where a mapping exists, for analyst triage |
| Security score | A single 0-to-100 posture score aggregated from all clusters, cached for cheap repeat reads |
| Background refresh | Expensive scans run out-of-band with lock-file dedup so the dashboard stays responsive |
| Always-on host exposure | A qualified metadata-only watcher observes visible TCP listeners and established flows, UDP binds and connected endpoints, and Unix-domain listeners across discovered namespaces. Behavior-first rules cover reverse and bind shells, SSH and SFTP forwarding, FTP and FTPS control plus real passive/data relationships, VNC and RFB, web servers, netcat-style listeners, SOCKS, relays, reverse proxies, and local-exposure tunnels. |
| Dashboard-independent alerts | The separately signed, unprivileged kodachi-soc-notifier user service delivers visual warning, critical, degraded, untrusted, and unsupported alerts while the dashboard is closed. The watcher remains the only scoring, deduplication, journal, and unread-state authority. |
Why the SOC Page Matters
| Benefit | Description |
|---|---|
| Situational awareness | One neural map shows the whole host at a glance instead of ten separate tools |
| Bounded authority | No process kills. It appends its own score history on every snapshot. Under root it also writes host-exposure policy (approve, revoke, renew), acknowledges findings, enables or disables the watcher unit, and applies kernel.io_uring_disabled=2 machine-wide when arming the watcher |
| Findings, not noise | Threats are clustered, scored, and tagged so the worst items surface first |
| Privacy posture | Live Tor, VPN, DNSCrypt, firewall, disk-encryption, and USB-guard state in one feed |
TL;DR - Essential Commands
# Collect all SOC telemetry and emit the dashboard DATA JSON
sudo kodachi-soc snapshot
# Pretty-printed JSON for humans
sudo kodachi-soc snapshot --json-pretty
# Run the expensive background scans and warm the cache
sudo kodachi-soc refresh
# Built-in usage examples
kodachi-soc --examples
# Read current always-on watcher health and findings
kodachi-soc exposure summary --json
# Inspect exact signed target qualification
kodachi-soc exposure qualification --json
# List reviewed defaults and explicit host exposure approvals
sudo kodachi-soc policy list --json
# Run the service-owned always-on watcher in the foreground (systemd normally owns it)
sudo kodachi-soc watch
# Show notifier help and examples through the standard cli-core interface
kodachi-soc-notifier -h
kodachi-soc-notifier -e --json-pretty
The dashboard SOC page calls snapshot on a refresh interval (default 120 seconds) and renders the returned DATA JSON as the neural map. You rarely need to run these by hand; the commands above are for automation, scripting, and troubleshooting.
Coverage is fail-visible
Healthy requires exact signed target qualification, an attached metadata backend, current reconciliation, and no recorded loss. Degraded, untrusted, unsupported, stale, malformed, or unavailable evidence never renders as clean. Bare outbound browser and update traffic remains bounded correlation context unless higher-signal shell, forwarding, relay, authentication, persistence, service, or risky-executable evidence promotes it.
The watcher and notifier do not read socket payloads and do not contact reputation services. Acknowledgement records review only; it does not approve future behavior, terminate a process, block an endpoint, isolate networking, or alter firewall rules. The watcher is caged at MemoryHigh=192M, MemoryMax=256M, CPUQuota=100%, CPUWeight=20, OOMScoreAdjust=500, TasksMax=64, and an 8 MiB queue. The notifier is separately caged at MemoryHigh=24M, MemoryMax=32M, CPUQuota=5%, OOMScoreAdjust=500, and TasksMax=32.
Understanding the Kodachi SOC
The Neural Map
The dashboard SOC page draws a central security score orbited by 10 cluster hubs:
| Cluster | What it watches |
|---|---|
| vitals | CPU, memory, load, uptime, and overall host health |
| network | Interfaces, routes, leak posture, and connectivity |
| connections | Active sockets and listening services |
| processes | Running processes and anomalies |
| threats | FIM and critical-binary integrity, SUID drift, preload hijacks, kernel taint, capability changes, boot-autoload diff, /dev anomaly, account integrity, log-tamper |
| auth | Login state, sessions, and authentication posture |
| privacy | Tor, VPN, DNSCrypt, and anonymity posture |
| system | Kernel, services, configuration state, and CIS/Lynis hardening posture |
| agents | Detected AI coding agents and their workspace markers |
| logs | Per-service Kodachi log health (recent error counts), merged into the map by the dashboard rather than emitted by snapshot |
A cluster with many findings is broken into labelled sub-hubs so the map stays readable: network fans out into TCP, UDP, and Link groups, and threats into Trust, Rootkit, LAN, Persistence, Integrity, and Hardening groups. Each sub-hub shows its own count and lights up by its worst finding; hover any node to read its detail.
Nodes are colour-coded by severity, threat findings carry MITRE ATT&CK technique IDs, and a top-findings list plus a live alert feed surface the most important items first.
The DATA JSON
snapshot emits a single JSON document the dashboard consumes directly. Top-level keys:
| Key | Meaning |
|---|---|
host |
Hostname and identity of the scanned machine |
generated |
Local timestamp of the snapshot |
overall |
Overall zone (the headline posture band) |
counts |
Finding counts by severity |
load |
Host load summary |
score |
Aggregated security score |
findings |
Tagged findings, including MITRE ATT&CK annotations |
posture |
Privacy/security posture keys (Tor, VPN, DNSCrypt, Firewall, IPv6, DiskEnc, USBGuard, and more) |
clusters |
The 9 collector cluster hubs (VITALS to AGENTS) and their nodes; the dashboard adds the LOGS hub itself. An additive watcher key carries host-exposure state |
LAN Attack Watch
On a hotel, cafe or other shared network, lan-watch listens for a set time (10 to 3600 seconds, 60 by default) and reports attacks aimed at this machine.
# Watch the current network for one minute
sudo kodachi-soc lan-watch
# Watch the Wi-Fi interface for five minutes
sudo kodachi-soc lan-watch --duration 300 --interface wlan0
# The same watch as JSON
sudo kodachi-soc lan-watch --duration 120 --json
| Detection | What it means |
|---|---|
| ARP spoofing (T1557.002) | A device claims your gateway's or another host's address, the first step of a man-in-the-middle attack |
| Gateway change | The gateway's hardware address changed during the watch |
| Rogue DHCP server (T1557.003) | A second DHCP server answers on the network |
| Rogue IPv6 router (T1557) | A device announces itself as an IPv6 router |
| Port and stealth scans (T1046) | A device probes many ports of this machine |
| ICMP redirects accepted | The kernel would let a device on the network reroute your traffic |
READ-ONLY BY DESIGN
It sends no packet, never puts the interface into promiscuous mode and changes no setting. It reads packet headers only, stores and prints no payload, and nothing leaves the machine. It blocks nothing; it tells you what it saw. It needs sudo for its packet socket. When the default route goes through a VPN or Tor tunnel, name the physical interface with --interface; loopback, tunnels and other non-Ethernet links are refused. No frames means nothing arrived (the link is down or idle), which is not proof the network is clean. A watch whose capture stops partway (the link drops or the adapter is removed) says so, keeps what it saw and exits with code 2; its findings then read not checked, never none. Ctrl+C ends it early with a partial report.
Published Onion Services
An onion service you publish with tor-switch onion-service-create can be reached from anywhere by anyone who has its address, so the SOC lists it. published-services reads tor-switch's saved list (never a key directory) and checks that each local service is listening, with the same 3 second connection test the Tor page uses. It is read-only and needs no root.
# Show each published onion service and whether its local service answers
kodachi-soc published-services
# The same as JSON, for the dashboard
kodachi-soc published-services --json
| State | What it means |
|---|---|
| listening | Published by you, and the local service answers. Informational: it adds no warning. |
| NOT LISTENING | A warning: visitors reach nothing, and a program that later takes that port would be published without being chosen. Start the service or remove it with sudo tor-switch onion-service-remove --name NAME. |
| not checked | The local service could not be tested (for example, the target is not a loopback address). Never a pass. |
| unknown | The saved list could not be read. This is never the same as having no services. |
The SOC snapshot shows the same services as nodes in the Network hub, and the dashboard's Host Exposure panel lists them. Only the first 6 characters of an address are shown, so a shared SOC report does not reveal it.
Identity Alerts
The SOC watcher watches what decides who can log in and with which rights: user accounts (an account added or removed, an account with UID 0, an account added to a privileged group), sudo rules, SSH keys, the SSH server settings and new setuid programs. It also reports a write the system refused and a burst of changes. identity alerts reads what the watcher recorded. It is read-only and needs no root, and it names accounts, paths and SSH key fingerprints only, never file contents or key comments.
Identity alerts need the SOC watcher on. It is off by default: turn it on from the SOC page or with sudo kodachi-soc exposure watcher --enable.
# Show whether identity changes are watched, and the alerts recorded
kodachi-soc identity alerts
# The same as JSON, for the dashboard
kodachi-soc identity alerts --json
| Status | What it means |
|---|---|
| watching | Every item above is watched. |
| partly watched | Everything except other users' SSH keys, which are watched once the SOC watcher is qualified for this kernel. Root's SSH keys are always watched. |
| off | The SOC watcher is off, so nothing is watched. The dashboard says off and never shows an empty list, because nothing watched is not the same as nothing changed. |
| unreadable | The alert file could not be read, or was written by a different version. Never a pass. |
Account changes made by apt, dpkg or unattended-upgrades are listed as kept-quiet rows, with the package that made them, instead of alerts. A sudo rule or SSH key that no package installed is always alerted. The watcher only records: it never blocks or undoes a change. In the dashboard the SOC page shows the alerts behind its IDENTITY button, and Vitals shows the watch state in its SECURITY panel.
snapshot vs refresh
| Command | Cost | When it runs |
|---|---|---|
snapshot |
Cheap collectors run inline; expensive results are served from cache | Every dashboard refresh, or on demand |
refresh |
Runs all expensive background scans and repopulates the cache | Periodically in the background; subsequent snapshots read the warm cache |
This split keeps the SOC page fast: the heavy FIM and audit work happens in refresh, while snapshot stays responsive for the UI.
Real-Time File Scan (warn-only)
The real-time file scan checks the SHA-256 of files written to the home folders, /root, /tmp, /dev/shm and removable media against a list of known-malware hashes, and raises a host exposure alert on a match. It only warns: it never blocks, moves or deletes a file. It is off by default.
The list comes from abuse.ch MalwareBazaar and needs your own free abuse.ch Auth-Key (auth.abuse.ch). The key is read from standard input, never from the command line, and kept root-only on your machine. The list is fetched over Tor only: with no key, or with no Tor running, nothing is fetched.
Before you turn it on
The real-time file scan needs a free personal abuse.ch Auth-Key, because abuse.ch requires one to download the malware hash list.
- Get the key: sign up at https://auth.abuse.ch/ and copy your Auth-Key. It is free and personal.
- Store it:
sudo kodachi-soc exposure realtime --set-key, then paste the key and press Enter (the key is not shown while you type it and is kept readable by root only). - Fetch the list over Tor:
sudo kodachi-soc exposure realtime --update - Turn the scan on:
sudo kodachi-soc exposure realtime --enable
Then sudo kodachi-soc exposure realtime --status shows whether it is on and running. The dashboard never asks for the key.
Real-time scan commands
| Command | What it does |
|---|---|
sudo kodachi-soc exposure realtime --set-key |
Paste your Auth-Key and press Enter (it is not shown). A stored key is not replaced: run --remove-key first. |
sudo kodachi-soc exposure realtime --update |
Fetches the last 48 hours of MalwareBazaar additions over Tor and adds them to your list. Any failure keeps the old list. |
sudo kodachi-soc exposure realtime --enable |
Turns the scan on. Refused until a list exists. It starts its own service, kodachi-soc-realtime.service, and enables it at boot; if the service does not start, the scan stays off. A match becomes a host exposure alert, which needs the host exposure watcher running (kodachi-soc exposure watcher --status). |
sudo kodachi-soc exposure realtime --status |
Whether the scan is on and running, the list's size, age and scope, the scan's counters, and the next step when something is missing. It never shows the key. |
sudo kodachi-soc exposure realtime --disable |
Turns the scan off: stops kodachi-soc-realtime.service and keeps it from starting at boot. The list and the key are kept. |
sudo kodachi-soc exposure realtime --remove-key |
Overwrites and removes the stored key. |
What the list covers: each update adds the last 48 hours of MalwareBazaar additions, so the list holds only malware first seen since your first update. Update it regularly; a list older than 30 days is marked old.
What you see: while the scan is on, the Host Exposure panel on the SOC page shows the list size, the files checked, the matches, every limit the scan hit (a file over 64 MiB, a full queue, a pause for a burst of writes), and how many files it did not check while paused. A match is an ordinary host exposure alert: open nothing, check the file, and delete it yourself if unsure.
abuse.ch terms of use (abuse.ch/terms-of-use, last updated 21 October 2026): 3.1 “Authenticated Users may access the Platforms for not-for-profit purposes”; 4.1 use “with commercial or for-profit needs may require a paid subscription, which will be managed by Spamhaus”. An organisation should check whether it needs that subscription.
Advanced Commands
For the complete list of flags and output options, see the auto-generated command reference, which includes:
| Feature | Description |
|---|---|
| Output formats | --json, --json-pretty, --json-human, and --fields selection |
| Pagination | --limit and --offset for large result sets |
| Logging | --verbose, --quiet, and --no-color |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important practices:
| Practice | Description |
|---|---|
| Bounded by design | kodachi-soc never kills processes. Every snapshot appends to its own score history, whatever user runs it. Under root it also seeds the baselines refresh compares against (file integrity, autostart entries, SUID binaries, file capabilities, critical paths, log sizes, kernel taint), persists host-exposure policy (policy approve / revoke / renew), acknowledges findings, arms or disarms the watcher unit, and sets kernel.io_uring_disabled=2 for the whole machine when arming it. For active response use health-control |
| Run with root | System collectors (FIM, capabilities, kernel taint) need root/sudo for complete results |
| Trust the cache | Let refresh warm the cache on a schedule rather than forcing heavy scans on every read |
| Investigate findings | Treat high-severity, ATT&CK-tagged findings as leads to verify, not as automatic verdicts |
| Pair with integrity-check | Use integrity-check to confirm a SOC FIM finding against the signed baseline |
Performance
| Metric | Value |
|---|---|
| Snapshot time | Fast: cheap collectors inline, expensive results from cache |
| Refresh time | Heavier: full FIM and audit scans run out-of-band |
| Binary size | 8.8MB |
| Footprint | Minimal; lock-file dedup prevents overlapping refreshes |
| Dashboard interval | Default 120 seconds (configurable on the SOC page) |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Feed the Dashboard SOC Page
The dashboard drives this automatically, but you can reproduce exactly what it sees.
# Step 1: Warm the cache so expensive scans are ready
sudo kodachi-soc refresh
# Expected: Background FIM, SUID, capability, and kernel-taint scans complete
# Step 2: Produce the DATA JSON the SOC page renders
sudo kodachi-soc snapshot --json-pretty
# Expected: A document with host, score, clusters, findings, and posture
# Step 3: Read the headline score
sudo kodachi-soc snapshot --json | jq '.score.value'
# Expected: A 0-to-100 posture score
# Step 4: List the cluster hubs
sudo kodachi-soc snapshot --json | jq '.clusters[].name'
# Expected: VITALS, NETWORK, CONNECTIONS, PROCESSES, THREATS, AUTH, PRIVACY, SYSTEM, AGENTS
Cross-binary workflow: kodachi-soc + health-control
When to run: Whenever you want the same situational snapshot the dashboard SOC page shows, from the terminal.
Scenario 2: Scheduled Background Refresh
Keep the SOC cache warm so snapshots stay fast and current.
# Step 1: Run the expensive scans on a schedule
sudo kodachi-soc refresh
# Expected: Cache repopulated; lock-file prevents overlapping runs
# Step 2: Confirm a fresh snapshot reads the warm cache quickly
sudo kodachi-soc snapshot --json | jq '.generated'
# Expected: A recent local timestamp
# Step 3: Track score over time for trending
sudo kodachi-soc snapshot --json | jq '{generated, score, counts}'
# Expected: Compact record suitable for logging
Cross-binary workflow: kodachi-soc + logs-hook + workflow-manager
When to run: On a timer if you script it. On the live system no separate timer is needed: snapshot starts a background refresh itself whenever an expensive cache entry is cold or expired. Automate this with workflow-manager scheduling periodic refreshes.
Scenario 3: Triage Threat Findings with MITRE ATT&CK
Surface and investigate the worst findings first.
# Step 1: Collect findings as JSON
sudo kodachi-soc snapshot --json > /tmp/soc-snapshot.json
# Expected: Full DATA JSON saved for analysis
# Step 2: List all findings with their ATT&CK tags
jq '.findings[] | {title, sev, attack: .mitre}' /tmp/soc-snapshot.json
# Expected: Findings annotated with MITRE ATT&CK technique IDs
# Step 3: Filter to the highest severity items
jq '.findings[] | select(.sev == "crit" or .sev == "warn")' /tmp/soc-snapshot.json
# Expected: The findings that deserve immediate attention
# Step 4: Confirm a file-integrity finding against the signed baseline
sudo integrity-check check-integrity
# Expected: integrity-check confirms or clears the SOC FIM lead
# Step 5: Record the incident
sudo logs-hook log --script 'kodachi-soc' --level warn "SOC high-severity findings: $(jq '[.findings[] | select(.sev=="warn" or .sev=="crit")] | length' /tmp/soc-snapshot.json)"
# Expected: Centralized log entry created
Cross-binary workflow: kodachi-soc + integrity-check + logs-hook + health-control
When to run: When the SOC page raises high-severity or ATT&CK-tagged findings. Verify before taking any active response.
Scenario 4: Check a Public Network Before You Use It
On arrival at a hotel or cafe, watch the network for a few minutes before you sign in to anything.
# Step 1: Connect to the network, then watch it for five minutes
sudo kodachi-soc lan-watch --duration 300
# Expected: 'Findings : none', or findings with the device's address
# Step 2: If it reports ARP spoofing or a rogue DHCP server, leave the network
# Step 3: If you must stay, route everything through Tor before you continue
sudo tor-switch torrify-system-nftables
Cross-binary workflow: kodachi-soc + tor-switch
When to run: Whenever you join a network you do not control.
Related Workflows
- Health Control, System Health, Active scoring, verification, and threat response
- Integrity Check, File Integrity, Confirm SOC FIM findings against signed baselines
- Online Auth, Authentication, Auth posture feeding the SOC auth cluster
- Logs Hook, Centralized Logging, Record SOC findings and incidents
- Workflow Manager, Automation, Schedule SOC refreshes
- Full CLI Reference: kodachi-soc commands