GuardedSOC Agent

GuardedSOC Agent is a compact, end-to-end cybersecurity AI project that demonstrates agentic investigation, MCP-style tool orchestration, policy enforcement, auditability, and a small full-stack SOC dashboard.

The demo investigates a suspicious PowerShell alert, queries local telemetry through safe tools, blocks unsafe actions, and produces an incident timeline with IOCs, MITRE ATT&CK-style mappings, risk scoring, and containment recommendations.

The Goal

Modern security teams are adopting AI agents, but agents with tools create a new risk surface: goal hijacking, tool misuse, excessive agency, identity abuse, unsafe local execution, and weak audit trails. This project shows how to build a useful cyber agent while treating the agent itself as a system that needs security controls.

Features

• Agentic SOC investigation planner with deterministic, reviewable execution.
• LLM adapter layer with deterministic default and optional OpenAI-compatible planning.
• MCP-style stdio server exposing cybersecurity tools.
• Tool policy engine with risk tiers, scope checks, human approval gates, and audit logs.
• Mock endpoint, process, DNS, email, and identity telemetry.
• Incident report generation with timeline, IOCs, ATT&CK-style mapping, severity, and recommendations.
• Browser dashboard for end-to-end demo storytelling.
• Standard-library Python implementation with tests.

Architecture

flowchart LR
    UI["SOC Dashboard"] --> API["HTTP API"]
    CLI["CLI Demo"] --> Agent["GuardedSOC Agent"]
    API --> Agent
    Agent --> Policy["Policy Engine"]
    Policy --> Tools["Cyber Tool Registry"]
    Tools --> Data["Local JSONL Telemetry"]
    MCP["MCP-style stdio server"] --> Tools
    Agent --> Audit["Audit Log"]

Loading

Quick Start

Run the tests:

python3 -m unittest discover -s tests

Run a CLI investigation:

python3 -m cyberops.cli investigate "Suspicious PowerShell encoded command on FIN-WS-014"

Run the same investigation through the explicit deterministic LLM adapter:

python3 -m cyberops.cli investigate "Suspicious PowerShell encoded command on FIN-WS-014" --llm-provider deterministic

Use a local config file for deterministic or API-based planning:

cp guardedsoc.env.example guardedsoc.env

Edit guardedsoc.env:

GUARDSOC_LLM_PROVIDER=deterministic

Or for an OpenAI-compatible chat endpoint:

GUARDSOC_LLM_PROVIDER=openai-compatible
GUARDSOC_LLM_MODEL=your-chat-model
GUARDSOC_LLM_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=your-api-key

Then run:

python3 -m cyberops.cli investigate "Suspicious PowerShell encoded command on FIN-WS-014"

Environment variables can also be used and take precedence over guardedsoc.env:

export GUARDSOC_LLM_PROVIDER=openai-compatible
export GUARDSOC_LLM_MODEL=your-chat-model
export OPENAI_API_KEY=your-api-key
python3 -m cyberops.cli investigate "Suspicious PowerShell encoded command on FIN-WS-014" --llm-provider openai-compatible

For non-OpenAI compatible endpoints, also set:

export GUARDSOC_LLM_BASE_URL=https://your-provider.example/v1

Start the web app:

python3 -m cyberops.api

Then open:

http://127.0.0.1:8080

If port 8080 is already in use, stop the old local server:

lsof -nP -iTCP:8080 -sTCP:LISTEN
kill <PID>
python3 -m cyberops.api

Try the MCP-style tool server:

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n' | python3 -m cyberops.mcp_server

An example local client configuration is included in mcp_config.example.json.

Demo Scenario

The demo includes three copy-paste alert scenarios:

Suspicious PowerShell encoded command on FIN-WS-014
OAuth consent grant and mailbox forwarding rule on HR-WS-007
NPM package postinstall script opened outbound connection on ENG-WS-022

The default alert models a realistic SOC triage path:

1. Suspicious email attachment lands in a finance mailbox.
2. The endpoint launches an encoded PowerShell command.
3. PowerShell spawns a network connection to a suspicious host.
4. The agent enriches IOCs, builds a timeline, maps techniques, and recommends containment.
5. Unsafe actions such as live payload execution are denied by policy and recorded in the audit trail.

Security Controls Demonstrated

• Least-privilege tool scopes.
• Risk-tiered tool execution.
• Explicit denial for destructive or live-execution tools.
• Prompt-injection resistant tool inputs through structured parameters.
• Complete audit events for allowed and blocked tool calls.
• Local-only telemetry to avoid accidental exposure of real data.

Repository Layout

cyberops/
  agent.py          Agent planner and investigation workflow
  api.py            Standard-library HTTP API and static web server
  audit.py          Structured audit trail
  cli.py            Command-line demo
  data_store.py     JSONL telemetry loader/query helpers
  llm.py            Deterministic and OpenAI-compatible planner adapters
  mcp_server.py     MCP-style JSON-RPC stdio server
  models.py         Core dataclasses
  policy.py         Tool execution policy
  tools.py          Cyber tool registry
data/
  security_events.jsonl
docs/
  architecture.md
  security-controls.md
  threat-model.md
guardedsoc.env.example
mcp_config.example.json
tests/
  test_agent.py
  test_llm.py
  test_mcp_server.py
  test_policy.py
web/
  index.html
  styles.css
  app.js

Notes

This project is kept intentionally small, but it covers a clear SOC workflow and dashboard.

On the backend, it has HTTP API, typed domain model, tool registry, and testable components. On the Agentic AI side, it covers the planning, tool use, observation synthesis, and report generation.

From the cybersecurity perspective the project tocuhes telemetry triage, IOC enrichment, technique mapping, and containment guidance. And, on the AI security side, it tocuhes upon policy gates, auditability, least privilege, and unsafe action refusal.