kodeblue is a Go-based defensive agent that gives each Linux server its own SOC, incident response and SecOps capability, using zero-token sensors with a small triage model for authorized defenders.
| Tool | Problem99-io/kodeblue — a single Go agent providing SOC monitoring, incident response and SecOps for Linux servers |
| Category | Defensive security agent / host intrusion detection and automated response |
| Primary Use | Learning a server's normal baseline, detecting changes to sensitive files like authorized_keys and ld.so.preload within seconds, investigating incidents with an agent session, and containing attacks under a root-policy helper |
| Safe Use | Deployed by administrators on servers they own or are authorized to manage; purely defensive monitoring and containment on hosts under your own administrative control |
| Telemetry Note | Every action is rate-limited, journaled via journald, and posted to Slack or Telegram; blocks, disabled keys and quarantines are logged with undo commands, giving defenders a full audit trail |
Most host-security tooling assumes a human is watching. kodeblue, from Problem99-io, inverts that premise: it puts a persistent defensive agent on every Linux server, one that performs the combined duties of a SOC analyst, an incident responder and a SecOps engineer, and — in the project's own words — never sleeps. Written in Go, Apache-2.0 licensed, and currently sitting at 67 stars with active CI and semver releases, it targets the operational gap between automated attackers scanning every public IP around the clock and defenders who go home at six. This is a blue-team tool through and through, and its architecture is worth a close read by anyone running production Linux fleets.
The core design decision is separation of compute from cognition. kodeblue runs a fast watch loop checking sensitive state every 5 seconds, feeding into deterministic sensors on a 60-second cadence that cost zero LLM tokens. Deterministic filters then strip baseline noise — package upgrades, routine worker restarts — before anything reaches a model. The README's pipeline diagram makes the economics explicit: of 1,284 changes seen in an illustrative day, only 4 survive filtering at medium or high severity and reach the small triage model, at roughly $0.001 in spend, and just 1 becomes an incident with a full agent session. A small, cheap model behind any OpenAI-compatible API is enough; without a model configured at all, sensors, detection and monitors still run.
The learning phase is the piece that distinguishes kodeblue from classic file-integrity monitors. Over roughly 30 minutes the agent takes snapshots of the host, then runs an exploration session and a vulnerability assessment, each up to 45 minutes, producing a server profile, host-specific monitors and written skills. Critically, the README addresses the classic poisoning failure mode: indicators that are never legitimate — a new uid 0 account, ld.so.preload tampering, a deleted or in-memory executable, a package checksum mismatch, an outbound shell — are flagged even while baseline learning is in progress, so an already-compromised box is not silently learned as normal. That detail signals real design maturity.
Detection scope focuses on the persistence mechanisms attackers actually touch. authorized_keys, user accounts, sudoers, cron jobs, systemd units, PAM configuration and ld.so.preload are checked on the 5-second loop, and a change triggers a sweep immediately. A critical change — a key planted for root, for instance — becomes an incident within seconds; lower-severity changes are confirmed on the next sweep a minute or two later. The example incident transcript in the README shows the investigation style: host_read on the modified key file, host_exec last -i deploy to correlate a login from a new /24 three minutes before the change, host_exec ss -tnp revealing an outbound connection to port 4444 from a deleted binary under /tmp, and a verdict of true_positive at 0.94 confidence.
Privilege separation is handled more carefully than in most agent projects. The agent runs as its own non-root kodeblue user; it can read every file and process on the host, but its sandbox restricts writes to its own state, and all containment actions pass through a separate root helper. Containment primitives include blocking an IP, disabling an SSH key, quarantining a file, stopping a systemd unit, locking an account or killing a process. The default recommend mode holds each action for human approval, while contain mode executes immediately — a policy choice made in /etc/kodeblue/kodeblue.toml alongside response mode, protected users, IP allowlists and budget.
Guardrails around administrator assets are explicit. Root, uid 0 accounts, sudo/wheel/admin members and anything in protected_users are never touched autonomously; for those the agent only recommends, and the operator decides. Every action is rate-limited, journaled and posted to Slack, and most are reversible — the README shows an undo path (sudo kodeblue respond undo act_…) for disabled keys, blocks and quarantines. The one-way door is process termination, so the binary is preserved for forensics before the kill; note also that locking an account kills its processes, which do not return on undo. These edge cases being documented in the README rather than discovered in production is a good sign.
Fleet deployment comes through an optional kodeblue-hub, which gives one console for every server's incidents, reports, agent reasoning and tool calls streamed live, monitors, findings and pending approvals. The network model is conservative: servers only dial out, always over TLS, with plain HTTP permitted only for a hub on the same machine. Enrollment uses a single-use token passed on stdin so it never appears in process arguments, installer binaries are verified against release SHA256SUMS, and the hub supports certificate pinning via --pinnedpubkey sha256//…. For internet-facing hubs the README suggests a cloudflared tunnel with Cloudflare Access guarding the console, while acknowledging the trade-off that Cloudflare then sees server-to-hub traffic — an honest disclosure that reviewers should appreciate.
The SecOps leg completes the triad. Beyond detection and response, the agent runs a daily review session that finds each service's vulnerabilities and coverage gaps, tunes its own detections, and posts updates to Slack or Telegram. This creates a feedback loop where monitors written during the learning phase are continuously refined against observed host behavior, rather than being static rules shipped by a vendor. The README's example profile for an nginx + node API host with a postgres replica even flags the database listening on 0.0.0.0:5432 as a risk finding — the kind of contextual, host-specific assessment generic scanners miss.
Installation is a one-liner per the README: curl -fsSL https://github.com/Problem99-io/kodeblue/releases/latest/download/install.sh | sudo sh -s -- --inference-url https://openrouter.ai/api --model <model> on any Linux host with systemd on amd64 or arm64. The installer prompts for the API key, optional Slack webhook and Telegram credentials with secret input not echoed, then starts the agent; expect full operation within one to two hours after snapshots and learning complete. Configuration review is via sudoedit /etc/kodeblue/kodeblue.toml, and operations are observable through sudo journalctl -fu kodeblue. A Docker image (ghcr.io/problem99-io/kodeblue-hub:latest) covers hub deployments, and docs/deploy.md plus docs/hardening.md carry the deeper operational detail.
For defenders, the telemetry story is unusually clean: every action is journaled, rate-limited and mirrored to Slack or Telegram, with the hub capturing agent reasoning and tool calls live. That makes kodeblue itself auditable — you can reconstruct not just what the agent did but why, which is exactly the accountability bar autonomous response tooling needs to meet before anyone should trust it in contain mode. The remaining caution is inherent to the category: an LLM-driven responder with root-helper access is a powerful agent, and teams should run it in recommend mode until they've watched its verdicts on their own workloads. As an educational and operational reference for how to architect token-efficient, least-privilege defensive agents on Linux, kodeblue is one of the more thoughtfully documented projects in the space.
Problem99-io/kodeblue.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.