kodachi-soc

File Information

SHA256 Checksum

a732bc91397e262c9b5fd5de0d3fe1eb0433751f2a044c3ff00154146797e725

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. Production watcher service activation and default enablement are disabled pending release approval; an authorized rollout must explicitly set KODACHI_HOST_EXPOSURE_WATCHER_ENABLED=1 during installation, 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|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
• 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

kodachi-soc exposure summary --cursor RECORD_ID --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

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. 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: Read the first bounded reverse page of retained findings

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

Step 4: 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 5: Mark one finding reviewed while retaining its evidence

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

Environment Variables

Exit Codes