feat: CSPM AI agent - ReAct loop, 6 tool functions, MCP server, and CLI #396

Overview

Add a ReAct-based AI agent layer to OpenShield that lets security operators query their Azure environment in plain English. The agent reasons over real scan evidence using 6 CSPM tool functions built on top of the existing rule engine, attack graph, and finding lifecycle.

Access channels

• REST API: POST /api/agent/query
• MCP Server: connects Claude Desktop, Copilot, or any MCP-compatible LLM host
• CLI: openshield ask "your question"

Implementation phases

• Phase 1: Tool layer (api/agent/tools.py) - 6 tool functions wrapping existing intelligence stack
• Phase 2: Agent loop (api/agent/agent.py) - ReAct loop, max 8 iterations, uses ai_provider.py and ai_guard.py
• Phase 3: API route (api/routes/agent.py) - JWT auth, tenant isolation, 20 req/min rate limit
• Phase 4: MCP server (mcp/server.py) - exposes tools to Claude Desktop and Copilot
• Phase 5: CLI command - openshield ask "..." calling the API

6 CSPM tools

1. scan_subscription - trigger scan, return scan_id
2. get_findings - filtered findings with context
3. get_compliance_posture - MCSB / CIS / ISO 27001 score and gaps
4. get_attack_paths - BFS-ranked attack paths (wired after feat(graph): evidence graph foundation - resource inventory schema and scan wiring #352 feat(graph): evidence graph node and edge population #353 feat(graph): BFS attack path traversal and API endpoints #354 merge)
5. explain_finding - full finding detail and risk context
6. suggest_remediation - step-by-step fix for a specific resource

Dependencies

Depends on: #352 #353 #354 (attack graph) and #326 (finding lifecycle)

Branch

feat/355-cspm-ai-agent