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.
v9.8.2 · 5 commands · 3.7 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 | 9.8.2 |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 3.7MB |
| 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
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) |
| 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 | Every threat collector tags findings with ATT&CK technique IDs 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 | System and authentication log signals |
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 Rootkit, 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 10 cluster hubs and their nodes |
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.
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 | 3.7MB |
| 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'
# 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
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 (the Kodachi SOC hook handles this on the live system). 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, severity, 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(.severity == "critical" or .severity == "high")' /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(.severity=="high" or .severity=="critical")] | 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.
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