Kodachi SOC
SECURITY TOOL
Turn your host into a live Security Operations Center.
kodachi-soc collects full host telemetry, scores your posture, annotates threats with MITRE ATT&CK, and feeds the dashboard's neural-map SOC page. Read-only by design: it observes, it never changes your system.
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.0.1 |
| Build Date | REDACTED-BUILD-TIME |
| Rust Version | 1.82.0 |
| File Size | 3.5MB |
| 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 |
|---|---|
| 16 SOC collectors | vitals, network, connections, processes, threats, auth, privacy, system, and more, gathered in a single pass |
| File Integrity Monitoring | SHA-256 FIM, SUID drift detection, ld.so.preload watch, kernel taint, and capability audit |
| 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 |
Why the SOC Page Matters
| Benefit | Description |
|---|---|
| Situational awareness | One neural map shows the whole host at a glance instead of ten separate tools |
| Read-only safety | Pure observation: no kills, no config writes, nothing to roll back |
| 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
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.
Understanding the Kodachi SOC
The Neural Map
The dashboard SOC page draws a central security score orbited by 8 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, SUID drift, preload hijacks, kernel taint, capability changes |
| auth | Login state, sessions, and authentication posture |
| privacy | Tor, VPN, DNSCrypt, and anonymity posture |
| system | Kernel, services, and configuration state |
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 8 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 | --log-level, --verbose, --quiet, and --no-color |
| Working directory | -d, --work-dir for non-default base directories |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important practices:
| Practice | Description |
|---|---|
| Read-only by design | kodachi-soc never kills processes or edits config; it only observes. 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.5MB |
| 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