kodachi-soc

File Information

SHA256 Checksum

a10d19dd848e693cfa2b0ec845179b047432301f7ce8c4b4dfdb1db63d8a051f

Features

Security Features

System Requirements

Global Options

Commands

Cache

refresh

Run all expensive background scans and populate the cache

Usage:

kodachi-soc refresh

Options:

• (no options): refresh takes no flags. It runs the expensive scans and writes the cache, then exits

Examples:

sudo kodachi-soc refresh

sudo kodachi-soc refresh && sudo kodachi-soc snapshot

Host Exposure

watch

Run the service-owned always-on host exposure watcher

Usage:

kodachi-soc watch

Options:

• (no options): watch is service-owned and takes no command-specific flags. systemd owns restart, resource limits, runtime and state directories, and target-specific enablement
• (coverage contract): The system service owns backend selection, signed target qualification, storage profile, reconciliation, and resource limits. The watcher is off by default: turn it on from the SOC page or with sudo kodachi-soc exposure watcher --enable. Identity alerts and the real-time scan's warnings need it on. An installer turns it on for you only when KODACHI_HOST_EXPOSURE_WATCHER_ENABLED=1 is set, and invalid flag values fail closed. Enabling the unit does not bypass qualification: a target that lacks an exact signed qualification remains visibly unsupported and continuous capture stays disabled. A qualified target must match an approved kernel, architecture, boot and storage profile, provide BTF and cgroup v2, keep io_uring disabled, and provide CAP_BPF, CAP_PERFMON, CAP_NET_ADMIN, and CAP_SYS_ADMIN. The installer persists kernel.io_uring_disabled=2 before watcher activation; inability to apply it leaves coverage visibly unsupported. The unit enforces MemoryHigh=192M, MemoryMax=256M, CPUQuota=100%, CPUWeight=20, OOMScoreAdjust=500, TasksMax=64, LimitNOFILE=4096, and an 8192-record or 8 MiB userspace queue. Active deduplication state retains at most 384 noncritical and 128 critical finding contexts or 4 MiB, restores that bounded state from the journal after restart, prefers critical contexts under pressure, and reports any eviction as degraded evidence without deleting journal history. systemd readiness is announced only after target qualification, backend attachment or honest unsupported selection, runtime capability drop, bounded journal restoration, and initial reconciliation complete. Healthy means the qualified metadata backend and reconciliation are current with no loss. Degraded means qualified coverage lost events or a recoverable backend input. Untrusted means policy, sensor, journal, permission, or evidence integrity failed. Unsupported means the target never qualified and continuous capture is disabled. All visible TCP listeners and established inbound or outbound TCP flows, UDP binds and connected endpoints, and Unix-domain listeners are normalized across discovered network namespaces. Behavior-first rules cover reverse and bind shells, SSH and SFTP forwarding, FTP and FTPS control plus passive or data relationships, VNC and RFB, arbitrary web servers, renamed or random-port netcat-style listeners, SOCKS, relays, reverse proxies, and local-exposure tunnels without relying on a product name or famous port. A PTY contributes to shell confidence only after a stable socket-to-stdio descriptor bridge is proven. Deleted or memfd-backed execution raises shell confidence and remains in bounded evidence. Package ownership and authentication evidence are tied to fixed process and endpoint identity; missing, duplicated, stale, incompatible, or ambiguous evidence remains unknown or unavailable and degrades health visibly. Bare outbound flows stay bounded in-memory correlation context unless proven shell, relay, forwarding, fan-out, authentication, persistence, service, or risky-executable evidence promotes them. The command writes schema-versioned local health and findings and does not stream raw events or read socket payloads. Unsupported targets fail visibly and do not start reconciliation as a substitute for continuous coverage. The separately signed, unprivileged kodachi-soc-notifier consumes only the bounded local summary and delivers visual warning, critical, degraded, untrusted, and unsupported alerts while the dashboard is closed; it never scores or acknowledges findings. Host-only metadata cannot prove absence of kernel compromise or a tunnel hidden inside an approved process.

Examples:

sudo kodachi-soc watch

exposure

Read host exposure findings, qualification, and acknowledgement state

Usage:

kodachi-soc exposure <summary|history|qualification|watcher|realtime|acknowledge> [options]

Options:

• summary [--cursor RECORD_ID]: Read the bounded critical-first live window, full aggregate counts, health, and advisory polling cursor
• history --limit COUNT [--before-sequence SEQUENCE --before-finding-id FINDING_ID]: Read one bounded reverse page of up to 32 retained findings; the optional paired cursor reads older records without skipping findings that share an event sequence
• qualification: Read the exact signed target match for kernel, architecture, boot, storage, hardening, and BTF evidence without changing state
• qualification --explain: Explain the decision: when unqualified, name the nearest signed registry row and every differing field with both values, plus the masked boot command line; read-only, the raw command line is never printed
• watcher (--enable | --disable | --status): Turn continuous host exposure monitoring on or off, or read its state; --enable and --disable need root, --status is a read
• realtime (--status | --update | --enable | --disable | --set-key | --remove-key | --serve): The warn-only real-time file scan, all root: --set-key reads your free personal abuse.ch Auth-Key (sign up at https://auth.abuse.ch/) from standard input, --update fetches the last 48 hours of MalwareBazaar hashes over Tor and adds them to the list, --enable and --disable turn the scan on and off, --status reports it, --remove-key overwrites and removes the key
• acknowledge --finding-id FINDING_ID: Mark one finding acknowledged without changing authorization or deleting evidence

Examples:

kodachi-soc exposure summary --json

sudo kodachi-soc exposure history --limit 32 --json

sudo kodachi-soc exposure history --limit 32 --before-sequence 18446744073709551615 --before-finding-id FINDING_ID --json

kodachi-soc exposure qualification --json

sudo kodachi-soc exposure qualification --explain --json

kodachi-soc exposure summary --cursor RECORD_ID --json

kodachi-soc exposure watcher --status --json

sudo kodachi-soc exposure watcher --enable --json

sudo kodachi-soc exposure realtime --set-key

sudo kodachi-soc exposure realtime --update --json

sudo kodachi-soc exposure realtime --enable --json

sudo kodachi-soc exposure realtime --status --json

sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json

policy

Review, approve, revoke, list, and explain host exposure policy

Usage:

kodachi-soc policy <list|approve|revoke|renew|explain> [options]

Options:

• list: List reviewed defaults and explicit approvals without changing policy
• approve --finding FINDING_ID [--expires-hours HOURS] --confirm: Authorize only the persisted finding's exact executable and network scope
• revoke --approval APPROVAL_ID --confirm: Revoke one explicit approval without deleting audit history
• renew --approval APPROVAL_ID --expires-hours HOURS --confirm: Revoke the old record and create a renewed record with a new expiry
• explain --finding FINDING_ID: Show the exact current approval decision and scope mismatches

Examples:

sudo kodachi-soc policy list --json

sudo kodachi-soc policy approve --finding FINDING_ID --expires-hours 24 --confirm

sudo kodachi-soc policy revoke --approval APPROVAL_ID --confirm

sudo kodachi-soc policy renew --approval APPROVAL_ID --expires-hours 24 --confirm

sudo kodachi-soc policy explain --finding FINDING_ID --json

Identity Alerts

identity

Show the account, sudo rule, SSH key, SSH server and setuid changes the SOC watcher has seen (read-only)

Usage:

kodachi-soc identity alerts [--json]

Options:

• alerts: Print the status (watching, watching_partial, off or unreadable), its fixed sentence, a Detail line naming what is not covered and any error, and the alerts and quiet rows

Examples:

kodachi-soc identity alerts

kodachi-soc identity alerts --json

LAN Attack Watch

lan-watch

Watch the local network for attacks on this machine (ARP spoofing, rogue DHCP or IPv6 router, port scans) for a bounded time; read-only

Usage:

kodachi-soc lan-watch [--duration <SECONDS>] [--interface <IFACE>] [--json]

Options:

• --duration <SECONDS>: How long to watch, 10 to 3600 seconds
• --interface <IFACE>: Interface to watch (default: the default-route interface). Only Ethernet or Wi-Fi interfaces: a loopback, tunnel or other link type, named or as the default route, is refused with the list of physical interfaces

Examples:

sudo kodachi-soc lan-watch

sudo kodachi-soc lan-watch --duration 300 --interface wlan0

sudo kodachi-soc lan-watch --duration 120 --json

Published Onion Services

published-services

List the onion services this machine publishes and whether each local service is listening; read-only, no root needed

Usage:

kodachi-soc published-services [--json]

Examples:

kodachi-soc published-services

kodachi-soc published-services --json

Telemetry

snapshot

Collect all SOC telemetry and emit DATA JSON

Usage:

kodachi-soc snapshot [--json | --json-pretty | --json-human | --text]

Options:

• (no flag): Default. Emits the DATA JSON pretty-printed. Every form except --text emits JSON, and the default form is a machine contract other tools read
• --json: Compact single-line DATA JSON, for piping into jq or the dashboard
• --json-pretty: Indented DATA JSON
• --json-human: jq-style colorized DATA JSON for reading in a terminal
• --text: Readable text instead of JSON, for a person or a GUI output pane. Opt-in: it does not change any other form
• (host exposure): The additive watcher field contains schema_version, generated_at_epoch_ms, health, finding_count, unread_count, critical_unread_count, findings, and cursor when authoritative host-exposure evidence is available. findings is a critical-first live window bounded to at most 64 records; finding_count, unread_count, and critical_unread_count describe the full retained journal rather than only that window. Each finding carries bounded policy_observations and health_observations from evaluation time; unavailable evidence remains explicit and later state changes do not rewrite historical context. The protected exposure history --limit 32 --json command reads the first retained reverse page; older pages require both --before-sequence <exclusive> and --before-finding-id <exclusive> and remain bounded to 32 without changing state. When the watcher is healthy, snapshot consumes its authoritative host-exposure summaries and does not rescore listeners, inbound flows, relays, shells, remote access, proxies, or tunnels. Bare outbound flows remain bounded correlation context unless promoted by higher-signal metadata. If continuous monitoring is unsupported or unavailable, one-shot reconciliation feeds the same engine and reports snapshot_only coverage. Onion services this machine publishes (tor-switch's saved list, never its key directories) appear in NETWORK as one informational node each, since anyone with the address can reach them from anywhere. A service whose local target does not accept a connection (the same 3 s check tor-switch onion-service-status makes) is a warning node and adds one to the warnings; a list that cannot be read is reported as unknown, never as no services. Only the first 6 characters of an address are shown. Snapshot-only inspection cannot prove capture of short-lived activity, socket payload classification, kernel compromise, or a tunnel hidden inside an approved process.

Examples:

sudo kodachi-soc snapshot

sudo kodachi-soc snapshot --json

sudo kodachi-soc snapshot --json-pretty

sudo kodachi-soc snapshot --json-human

sudo kodachi-soc snapshot --text

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Telemetry Snapshot

snapshot is the whole point of this binary: it runs every SOC collector (vitals, network, connections, processes, threats, auth, privacy posture, system health) and prints the DATA JSON the dashboard consumes. The default form and the three JSON flags all emit that JSON and differ only in formatting; --text is the one form that renders it as readable prose instead, for a person or a GUI pane.

Step 1: Collect the full SOC telemetry set and print it

sudo kodachi-soc snapshot

Step 2: Same data as one compact line, for a script or the dashboard

sudo kodachi-soc snapshot --json

Step 3: Explicitly indented JSON

sudo kodachi-soc snapshot --json-pretty

Step 4: Colorized, jq-style JSON for reading in a terminal

sudo kodachi-soc snapshot --json-human

Step 5: The same data as readable prose, for a person or a GUI pane

sudo kodachi-soc snapshot --text

Scenario 2: Cache Warming

The expensive scans (file integrity hashing, SUID drift, persistence sweeps) run in the background and land in a cache. snapshot spawns a refresh automatically when it finds the cache cold, but that snapshot itself returns placeholders. Warm the cache first when you want the first read to be complete.

Step 1: Run the expensive scans now and populate the cache

sudo kodachi-soc refresh

Step 2: Pre-warm the cache, then take a fully populated snapshot

sudo kodachi-soc refresh && sudo kodachi-soc snapshot

Scenario 3: Automation and Dashboard Integration

snapshot --json is designed to be piped. The dashboard calls exactly this and reads the same fields you can read from the shell.

Step 1: Pull just the overall security verdict out of the snapshot

sudo kodachi-soc snapshot --json | jq '.overall'

Step 2: List every threat finding the collectors raised

sudo kodachi-soc snapshot --json | jq '.findings'

Step 3: Save a snapshot to disk so a later run can be diffed against it

sudo kodachi-soc snapshot --json > soc-baseline.json

Scenario 4: Host Exposure Policy

Approvals are explicit local authorization, never a first-run baseline. They bind the finding's executable digest, effective UID, parent or unit, namespace class, protocol, address scope, and port scope. Acknowledging a finding does not approve it. Changed, expired, revoked, corrupt, or incomplete identities fail closed.

Step 1: List reviewed defaults, explicit approvals, expiry, and revocation state

sudo kodachi-soc policy list --json

Step 2: Create a narrow approval from one persisted finding

sudo kodachi-soc policy approve --finding FINDING_ID --expires-hours 24 --confirm

Step 3: Revoke an approval without deleting its audit history

sudo kodachi-soc policy revoke --approval APPROVAL_ID --confirm

Step 4: Renew an active approval while retaining the old audit record

sudo kodachi-soc policy renew --approval APPROVAL_ID --expires-hours 24 --confirm

Step 5: Explain the policy decision and every scope mismatch for a finding

sudo kodachi-soc policy explain --finding FINDING_ID --json

Scenario 5: Host Exposure Investigation

summary is a read-only local consumer of the schema-valid critical-first live window, bounded to at most 64 findings, plus full finding_count, unread_count, and critical_unread_count aggregates. Each finding retains bounded policy_observations and health_observations captured when it was evaluated, so later policy or sensor changes do not erase the investigation explanation. Root-authorized exposure history --limit 32 --json reads the first retained page. Older pages require the symmetric --before-sequence <exclusive> and --before-finding-id <exclusive> cursor pair and return at most 32 findings without changing state. acknowledge marks one finding as reviewed but does not approve future behavior, delete evidence, terminate a process, block an endpoint, isolate networking, or alter firewall rules. Missing, stale, corrupt, or unreadable watcher evidence fails visibly.

Step 1: Read current watcher health, bounded findings, full counts, and cursor

kodachi-soc exposure summary --json

Step 2: Read the signed exact-target qualification decision

kodachi-soc exposure qualification --json

Step 3: Explain why this machine is or is not qualified

sudo kodachi-soc exposure qualification --explain --json

Step 4: Read the first bounded reverse page of retained findings

sudo kodachi-soc exposure history --limit 32 --json

Step 5: Read the next page using both exclusive cursor components

sudo kodachi-soc exposure history --before-sequence 4242 --before-finding-id finding-0000000000000000000000000000000000000000000000000000000000000000 --limit 32 --json

Step 6: Mark one finding reviewed while retaining its evidence

sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json

Scenario 6: LAN Attack Watch (public Wi-Fi)

lan-watch listens to the local network for a bounded time and reports attacks against this machine: ARP spoofing and gateway impersonation, a rogue DHCP server, a rogue IPv6 router and port scans. It is read-only: it sends nothing, never sets promiscuous mode, reads headers only and blocks nothing.

Step 1: Watch the current network for one minute

sudo kodachi-soc lan-watch

Step 2: Watch the Wi-Fi interface for five minutes, for example on arrival at a hotel or cafe

sudo kodachi-soc lan-watch --duration 300 --interface wlan0

Step 3: The same watch as JSON, for the dashboard and scripts

sudo kodachi-soc lan-watch --duration 120 --json

Scenario 7: Published Onion Services

published-services lists the onion services this machine publishes (from tor-switch's saved list) and checks that each local service is listening. It is read-only and needs no root.

Step 1: Show each published service and whether its local service answers

kodachi-soc published-services

Step 2: The same as JSON, for the dashboard's Host Exposure panel

kodachi-soc published-services --json

Scenario 8: Identity Alerts

Reads the alert file the SOC watcher writes in /var/lib/kodachi-soc/.soc-state/identity/. 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. With it off this command reports "off", not an empty list. In status-only mode (no qualification for this kernel) other users' SSH keys are not watched, and changes made by package installs cannot be verified, so they are alerted too; both are covered when the SOC watcher is qualified for this kernel. Account changes made by apt, dpkg or unattended-upgrades are listed as quiet rows, not alerted; a sudo rule or key that no package installed is always alerted. The status line is one fixed sentence per status (watching, watching_partial, off or unreadable); what is not covered and any error are on a separate Detail line, status_detail in JSON. A JSON reader shows a status it does not know as "Identity watch state unknown."

Step 1: Show whether identity changes are watched, and the alerts recorded

kodachi-soc identity alerts

Step 2: Machine-readable status and alert document for the dashboard and the notifier

kodachi-soc identity alerts --json

Scenario 9: Real-Time File Scan (warn-only)

The warn-only 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 never blocks, moves or deletes a file, and it is off by default. The list comes from abuse.ch MalwareBazaar, and abuse.ch requires a free personal Auth-Key to download it. Before you turn it on: (1) get the key: sign up at https://auth.abuse.ch/ and copy your Auth-Key; (2) 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); it is read from standard input, never from a command line; (3) fetch the list over Tor: sudo kodachi-soc exposure realtime --update; (4) turn the scan on: sudo kodachi-soc exposure realtime --enable. Then sudo kodachi-soc exposure realtime --status shows whether it is on and running. realtime --update fetches over Tor only, and each update adds the last 48 hours of MalwareBazaar additions, so the list holds only malware first seen since your first update. Any failure keeps the old list. abuse.ch terms of use (https://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".

Step 1: Store your free personal abuse.ch Auth-Key (sign up at https://auth.abuse.ch/ and copy it): paste it and press Enter (the key is not shown while you type it and is kept readable by root only)

sudo kodachi-soc exposure realtime --set-key

Step 2: Fetch the last 48 hours of MalwareBazaar hashes over Tor and add them to the list

sudo kodachi-soc exposure realtime --update --json

Step 3: Turn the scan on

sudo kodachi-soc exposure realtime --enable --json

Step 4: Read whether the scan is on and running, the list's size, age and scope, and the scan's counters

sudo kodachi-soc exposure realtime --status --json

Step 5: Turn the scan off

sudo kodachi-soc exposure realtime --disable --json

Step 6: Overwrite and remove the stored abuse.ch Auth-Key

sudo kodachi-soc exposure realtime --remove-key --json

Environment Variables

Exit Codes