{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:29Z", "binary_name": "kodachi-soc" }, "binary": { "name": "kodachi-soc", "path": "/opt/kodachi/dashboard/hooks/kodachi-soc", "timestamp": "2026-07-21T01:54:29Z", "file_info": { "size": 6868752, "sha256": "103106956433f91ac76f1252ec0a7654979096615f1dc01676322df26b7c3310" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Kodachi OS", "description": "Kodachi SOC host-security monitor: full telemetry collector with MITRE ATT&CK annotations", "features": [ "Default-disabled watcher service activation requiring explicit release authorization and exact signed target qualification", "Always-on metadata-only host exposure watcher on qualified targets", "All visible TCP listeners and established flows, UDP binds and connected endpoints, and Unix-domain listeners across discovered namespaces", "Behavior-first reverse and bind shell, SSH, FTP, VNC, web, netcat-style, SOCKS, relay, reverse-proxy, and local-exposure findings", "PTY evidence only after a proven socket-to-stdio bridge, with higher confidence for deleted or memfd-backed execution", "Fail-visible package-ownership and authentication evidence tied to fixed process and endpoint identity", "Bare outbound flows remain bounded correlation context until higher-signal evidence promotes them", "One authoritative watcher engine; snapshot consumes summaries or uses labeled snapshot_only input", "Explicit approvals with digest, UID, parent or unit, namespace, protocol, address, port, expiry, and revocation", "Fail-visible healthy, degraded, untrusted, and unsupported coverage states", "Bounded finding-time policy and sensor-health observations retained for investigation", "Readiness only after backend selection, capability drop, journal restoration, and initial reconciliation", "Installed 25 MiB and live 4 MiB bounded local retention with no payload capture or telemetry", "Investigation and acknowledgement only; no terminate, block, isolate, routing, or firewall action", "Separately signed unprivileged session notifier for dashboard-independent visual alerts without a second scoring engine" ], "license": "Proprietary", "name": "kodachi-soc", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 15, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.200801265Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "kodachi-soc", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 13, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.389536915Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Cache", "commands": [ { "description": "Run all expensive background scans and populate the cache", "examples": [ "sudo kodachi-soc refresh", "sudo kodachi-soc refresh && sudo kodachi-soc snapshot" ], "name": "refresh", "options": [ { "description": "refresh takes no flags. It runs the expensive scans and writes the cache, then exits", "flag": "(no options)" } ], "requires_sudo": true, "usage": "kodachi-soc refresh" } ] }, { "category": "Host Exposure", "commands": [ { "description": "Run the service-owned always-on host exposure watcher", "examples": [ "sudo kodachi-soc watch" ], "name": "watch", "options": [ { "description": "watch is service-owned and takes no command-specific flags. systemd owns restart, resource limits, runtime and state directories, and target-specific enablement", "flag": "(no options)" }, { "description": "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=48M, MemoryMax=64M, CPUQuota=10%, 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.", "flag": "(coverage contract)" } ], "requires_sudo": true, "usage": "kodachi-soc watch" }, { "description": "Read host exposure findings, qualification, and acknowledgement state", "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" ], "name": "exposure", "options": [ { "description": "Read the bounded critical-first live window, full aggregate counts, health, and advisory polling cursor", "flag": "summary [--cursor RECORD_ID]" }, { "description": "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", "flag": "history --limit COUNT [--before-sequence SEQUENCE --before-finding-id FINDING_ID]", "required": true }, { "description": "Read the exact signed target match for kernel, architecture, boot, storage, hardening, and BTF evidence without changing state", "flag": "qualification" }, { "description": "Mark one finding acknowledged without changing authorization or deleting evidence", "flag": "acknowledge --finding-id FINDING_ID", "required": true } ], "requires_sudo": false, "usage": "kodachi-soc exposure [options]" }, { "description": "Review, approve, revoke, list, and explain host exposure policy", "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" ], "name": "policy", "options": [ { "description": "List reviewed defaults and explicit approvals without changing policy", "flag": "list" }, { "description": "Authorize only the persisted finding's exact executable and network scope", "flag": "approve --finding FINDING_ID [--expires-hours HOURS] --confirm", "required": true }, { "description": "Revoke one explicit approval without deleting audit history", "flag": "revoke --approval APPROVAL_ID --confirm", "required": true }, { "description": "Revoke the old record and create a renewed record with a new expiry", "flag": "renew --approval APPROVAL_ID --expires-hours HOURS --confirm", "required": true }, { "description": "Show the exact current approval decision and scope mismatches", "flag": "explain --finding FINDING_ID" } ], "requires_sudo": true, "usage": "kodachi-soc policy [options]" } ] }, { "category": "Telemetry", "commands": [ { "description": "Collect all SOC telemetry and emit DATA JSON", "examples": [ "sudo kodachi-soc snapshot", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc snapshot --json-pretty", "sudo kodachi-soc snapshot --json-human" ], "name": "snapshot", "options": [ { "description": "Default. Emits the DATA JSON pretty-printed. snapshot ALWAYS emits JSON, there is no plain-text mode", "flag": "(no flag)" }, { "description": "Compact single-line DATA JSON, for piping into jq or the dashboard", "flag": "--json" }, { "description": "Indented DATA JSON", "flag": "--json-pretty" }, { "description": "jq-style colorized DATA JSON for reading in a terminal", "flag": "--json-human" }, { "description": "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 512 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 and --before-finding-id 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.", "flag": "(host exposure)" } ], "requires_sudo": true, "usage": "kodachi-soc snapshot [--json | --json-pretty | --json-human]" } ] } ], "description": "Kodachi SOC host-security monitor: full telemetry collector with MITRE ATT&CK annotations", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter " }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" } ], "name": "kodachi-soc", "usage": "kodachi-soc [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 20, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.533156929Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "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. It ALWAYS emits JSON. The four forms below differ only in how that JSON is formatted.", "examples": [ { "command": "sudo kodachi-soc snapshot", "description": "Collect the full SOC telemetry set and print it", "expectedOutput": "A pretty-printed DATA JSON object with host, generated, overall, counts, load, score, findings, posture and clusters", "notes": "Needs root: the collectors read /proc, auth logs, SUID bits and file hashes that an unprivileged user cannot see. Without sudo the scan runs but the threat sections come back empty or incomplete. On a cold cache the first call returns placeholder values and kicks off a background refresh, so run 'refresh' first if you need complete data on the first shot." }, { "command": "sudo kodachi-soc snapshot --json", "description": "Same data as one compact line, for a script or the dashboard", "expectedOutput": "The same DATA JSON on a single line, no indentation" }, { "command": "sudo kodachi-soc snapshot --json-pretty", "description": "Explicitly indented JSON", "expectedOutput": "The DATA JSON indented. Same content as the default form" }, { "command": "sudo kodachi-soc snapshot --json-human", "description": "Colorized, jq-style JSON for reading in a terminal", "expectedOutput": "Syntax-highlighted DATA JSON" } ], "id": "0_telemetry_snapshot", "title": "Telemetry Snapshot" }, { "description": "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.", "examples": [ { "command": "sudo kodachi-soc refresh", "description": "Run the expensive scans now and populate the cache", "expectedOutput": "Runs to completion, then exits. The cache under the SOC state directory is rewritten", "notes": "Needs root. This is the slow path: it is exactly the work snapshot avoids doing inline. A refresh spawned in the last 30 seconds is deduplicated by a lock file, so back to back calls will not stack up." }, { "command": "sudo kodachi-soc refresh && sudo kodachi-soc snapshot", "description": "Pre-warm the cache, then take a fully populated snapshot", "expectedOutput": "The scans run first, then a DATA JSON with real threat findings rather than cold-cache placeholders", "notes": "This is the sequence to use before the first dashboard open, or in a boot script." } ], "id": "1_cache_warming", "title": "Cache Warming" }, { "description": "snapshot --json is designed to be piped. The dashboard calls exactly this and reads the same fields you can read from the shell.", "examples": [ { "command": "sudo kodachi-soc snapshot --json | jq '.overall'", "description": "Pull just the overall security verdict out of the snapshot", "expectedOutput": "The overall posture value from the DATA JSON", "notes": "Requires jq. Use --json (not the default form) when piping, so the payload is a single line." }, { "command": "sudo kodachi-soc snapshot --json | jq '.findings'", "description": "List every threat finding the collectors raised", "expectedOutput": "The findings array, each entry carrying its MITRE ATT&CK annotation" }, { "command": "sudo kodachi-soc snapshot --json > soc-baseline.json", "description": "Save a snapshot to disk so a later run can be diffed against it", "expectedOutput": "A file holding the full DATA JSON for this moment in time" } ], "id": "2_automation", "title": "Automation and Dashboard Integration" }, { "description": "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.", "examples": [ { "command": "sudo kodachi-soc policy list --json", "description": "List reviewed defaults, explicit approvals, expiry, and revocation state", "expectedOutput": "A JSON policy summary with no automatically trusted observations", "notes": "Unknown or incomplete identity is never rendered as approved." }, { "command": "sudo kodachi-soc policy approve --finding FINDING_ID --expires-hours 24 --confirm", "description": "Create a narrow approval from one persisted finding", "expectedOutput": "A JSON approval bound to the finding's exact process and network scope", "notes": "This is authorization. The separate acknowledge action is not authorization." }, { "command": "sudo kodachi-soc policy revoke --approval APPROVAL_ID --confirm", "description": "Revoke an approval without deleting its audit history", "expectedOutput": "A JSON revocation record and updated policy version" }, { "command": "sudo kodachi-soc policy renew --approval APPROVAL_ID --expires-hours 24 --confirm", "description": "Renew an active approval while retaining the old audit record", "expectedOutput": "A new approval ID and expiry; the previous record is revoked", "notes": "A revoked approval cannot be renewed." }, { "command": "sudo kodachi-soc policy explain --finding FINDING_ID --json", "description": "Explain the policy decision and every scope mismatch for a finding", "expectedOutput": "A JSON PolicyDecision with approval, mismatch, expiry, or revocation reason" } ], "id": "3_host_exposure_policy", "title": "Host Exposure Policy" }, { "description": "summary is a read-only local consumer of the schema-valid critical-first live window, bounded to at most 512 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 and --before-finding-id 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.", "examples": [ { "command": "kodachi-soc exposure summary --json", "description": "Read current watcher health, bounded findings, full counts, and cursor", "expectedOutput": "A schema-versioned WatcherSummary with at most 512 critical-first findings", "notes": "Unavailable, corrupt, stale, untrusted, or unsupported evidence never renders as clean." }, { "command": "kodachi-soc exposure qualification --json", "description": "Read the signed exact-target qualification decision", "expectedOutput": "A qualified or unsupported decision with exact local evidence", "notes": "Generic BTF or capability availability alone never qualifies continuous coverage." }, { "command": "sudo kodachi-soc exposure history --limit 32 --json", "description": "Read the first bounded reverse page of retained findings", "expectedOutput": "A FindingHistoryPage with up to 32 findings and a symmetric next cursor", "notes": "History is read-only. It cannot acknowledge, approve, delete, or contain a finding." }, { "command": "sudo kodachi-soc exposure history --before-sequence 4242 --before-finding-id finding-0000000000000000000000000000000000000000000000000000000000000000 --limit 32 --json", "description": "Read the next page using both exclusive cursor components", "expectedOutput": "A FindingHistoryPage with up to 32 older findings and a symmetric next cursor", "notes": "History is read-only. It cannot acknowledge, approve, delete, or contain a finding." }, { "command": "sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json", "description": "Mark one finding reviewed while retaining its evidence", "expectedOutput": "The updated WatcherSummary with the finding acknowledged", "notes": "Acknowledgement is not authorization and never creates a policy approval." } ], "id": "4_host_exposure_investigation", "title": "Host Exposure Investigation" } ], "description": "Usage examples for kodachi-soc", "name": "kodachi-soc", "quickReference": [ "sudo kodachi-soc snapshot", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc refresh", "kodachi-soc --help", "kodachi-soc --version", "kodachi-soc --info --json", "kodachi-soc --examples", "sudo kodachi-soc watch", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc policy list --json", "sudo kodachi-soc policy explain --finding FINDING_ID --json", "kodachi-soc exposure summary --json", "sudo kodachi-soc exposure history --limit 32 --json", "kodachi-soc exposure qualification --json", "sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json", "kodachi-soc watch --help", "kodachi-soc policy --help" ] }, "errors": [], "metadata": { "executionTime": 14, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.815382278Z", "version": "9.8.4 (build 320)", "warnings": [] } } }