soc-assist-agent

An AI SOC copilot that walks a junior analyst from Splunk alert to verdict in plain English - querying read-only, gated on human sign-off, logging every move it makes

Comment

soc-assist — Project Story

Inspiration

I'm new to SOC/SIEM work myself. I installed Splunk, looked at an alert, and felt the "...where do I even start?" paralysis every junior analyst hits on day one. That confusion is the spine of this project. The thing that would have unstuck me was a senior engineer next to me — someone who brings judgment (a playbook, triage, a severity call with a reason) and guardrails (least privilege, sign-off, an audit trail). So the thesis became: the harness is the senior engineer. The judgment is the value; the guardrails are the proof an AI can be trusted to act in production.

What it does

Given an alert context, soc-assist runs a guided, plain-language investigation:

  • It investigates read-only — running corroborating SPL through the Splunk MCP server and explaining each query in plain English.
  • It returns a verdict with a severity and a stated reason — citing the rubric, and honest about evidence gaps rather than confidently guessing.
  • To publish evidence it must clear a human approval gate; on yes, it renders a native Splunk Dashboard Studio view and returns the URL.
  • Every query, gate decision, and write lands in a dedicated Splunk audit index — the watcher is watched.

Slack is the doorway; a generated Splunk dashboard is the room. It assists a real analyst through Splunk's own surfaces — it doesn't replace or reinvent them.

How we built it

On the Claude Agent SDK (Python), with the whole architecture mapping 1:1 onto SDK primitives — no web framework, no inbound server, no database. Splunk is the datastore and the audit log. Four planes, separated by privilege:

  • READ — the native Splunk MCP server as an external client (read-only).
  • WRITE — the only elevated capability: one in-process tool that can physically only POST a dashboard to a single app. The LLM never holds write credentials.
  • NOTIFY — Slack, with zero Splunk privilege.
  • AUDIT — every action appended to a Splunk index, with its own dashboard.

The security core is the can_use_tool gate: on every write it (a) hard-rejects out-of-scope targets before any human is asked — so a persuaded human can't bless an escape — and (b) requires an explicit human yes, defaulting to deny.

Challenges we ran into

  • Silent failures, not errors. Wrong MCP tool names and a too-narrow allowed_tools entry made the agent quietly do nothing instead of erroring. Only live calls caught it.
  • The gate's footgun. Any tool in allowed_tools bypasses the gate entirely, so the write tool is deliberately not pre-allowed — pre-allowing it would silently disable the whole security story.
  • Least-privilege leaks by default. The SDK loads global settings and injects ambient MCP servers into a "confined" agent; pinning it down was required for a clean boundary.

Accomplishments that we're proud of

  • A least-privilege model that holds even against a fully prompt-injected agent, with a runnable offline proof that the gate can't be exceeded.
  • Verdicts that cite their reasoning — severity with a rationale, and honesty about gaps.
  • An audit plane where the agent that watches the SIEM is itself observable inside it.
  • A genuinely environment-agnostic, public repo — the offline demo needs zero config.
  • An elegant coincidence: the approval gate and the "junior makes a decision" teaching moment are the same beat. Security control is pedagogy.

What we learned

  • Verify against the live system; never advance on assumption. Plausible-but-wrong docs bit us repeatedly — a unit was only done when its behavior was observed.
  • Governance is the product. The AI-specific threat is a compromised or prompt-injected agent, not just a leaked credential — and most agentic tooling over-privileges and doesn't notice. We're the governance layer you wrap around an agent, not a competitor to one.

What's next for soc-assist

  • Trigger on a live alert. Today the agent is pointed at an alert context manually; next is firing automatically when a Splunk detection (saved search / alert) does.
  • Integrate institutional knowledge — runbooks, past incidents, and internal docs as retrieval context, so the agent reasons with the org's own playbooks, not just generic SOC knowledge.
  • Splunk-side role IAM as defense-in-depth — scoping the write to one app at the credential layer, not just the harness.
  • Deeper integration with Splunk-native AI features like the Splunk AI Assistant for SPL (saia_*) — dropping it in behind the same governance gate as a swappable reasoning backend.
  • Richer detections and playbooks beyond the demo, each with its own investigative rubric.

Built With

  • claude
  • claude-agent-sdk
  • httpx
  • python
  • slack
  • slack-bolt
  • spl
  • splunk-dashboard-studio
  • splunk-enterprise
  • splunk-hec
  • splunk-mcp
  • splunk-rest-api
Share this project:

Updates