# AgentGuard for Splunk MCP

AgentGuard is a black-box recorder, policy firewall, and investigation copilot for AI agents using Splunk MCP.

It sits between an AI agent and Splunk MCP-style tool calls, records every action, evaluates policy risk, blocks or routes suspicious requests for human approval, and forwards audit events to Splunk HTTP Event Collector (HEC). The demo includes a local operations console, a simulated malicious incident ticket, Splunk dashboard assets, and submission-ready video/storyboard documentation.

## Hackathon Positioning

- Track: Platform & Developer Experience, with a strong Security story
- Bonus target: Best Use of Splunk MCP Server
- One-line pitch: A flight recorder and safety layer for agentic operations in Splunk.
- Core demo: An AI incident agent starts a normal investigation, receives a malicious prompt injection, attempts restricted SPL queries, and AgentGuard blocks the risky calls while creating an auditable timeline.

## Submission Status

- Local demo: ready
- Public GitHub repo: ready to publish as `sauravtom/agentguard-splunk-mcp`
- Splunk Cloud trial: created as `MyInstance`, 5GB/day, June 7-22, 2026
- Live Splunk HEC ingestion: pending until the Splunk Cloud `ACCESS INSTANCE` button becomes enabled and HEC can be configured

## What Works Today

- MCP-style tool-call proxy endpoint: `POST /api/mcp/tool-call`
- Policy engine for restricted indexes, PII exfiltration, destructive actions, broad searches, and prompt injection
- Local append-only audit log
- Optional Splunk HEC forwarding
- AI-style investigation summary with evidence links and safe next actions
- React demo console with incident timeline, policy decisions, approval queue, and summary panel
- Splunk Simple XML dashboard and SPL examples
- Demo video script, narration, screenshot plan, GitHub publication checklist, and Devpost copy

## Quick Start

```bash
npm install
npm run dev
```

Open `http://localhost:5173`.

The API runs on `http://localhost:8787`. Vite proxies `/api` to the API server.

## Demo Flow

1. Click `Reset demo`.
2. Click `Run safe investigation` to show normal Splunk MCP-style usage.
3. Click `Run malicious ticket` to inject a prompt that tries to leak secrets and query restricted indexes.
4. Review the timeline, blocked calls, approval queue, and investigation summary.
5. If Splunk HEC is configured, search for `sourcetype=agentguard:mcp:audit` in Splunk.

## Optional Splunk HEC

Create `.env` from `.env.example`:

```bash
cp .env.example .env
```

Set:

```bash
SPLUNK_HEC_URL=https://localhost:8088/services/collector/event
SPLUNK_HEC_TOKEN=your-token
SPLUNK_HEC_INDEX=main
```

AgentGuard will still work without Splunk HEC. In local mode it writes audit events to `data/audit-log.jsonl`.

## Repository Requirements Covered

- Open source license: `LICENSE`
- Setup and run instructions: this README
- Example config: `.env.example`
- Example data: `data/demo-scenarios.json`
- Architecture diagram: `architecture_diagram.md`
- Demo video plan: `docs/demo-video-script.md`
- Devpost copy: `docs/devpost-submission.md`
- Submission checklist: `docs/submission-checklist.md`
- Public GitHub plan: `docs/github-publication-plan.md`

## Architecture

See `architecture_diagram.md`.

## Security Notes

Do not commit `.env`, Splunk HEC tokens, Splunk session data, downloaded support files, or recorded videos that expose credentials. Runtime audit logs are ignored through `.gitignore`.