# AI Incident Response Copilot

A portfolio-ready, multi-agent system that investigates simulated cloud incidents and keeps humans in control of remediation.

![Node.js](https://img.shields.io/badge/Node.js-20%2B-11130f?logo=node.js)
![MCP](https://img.shields.io/badge/MCP-compatible-d7ff43)
![CI](https://img.shields.io/badge/tests-node:test-ff5a45)

## Why this project

The copilot demonstrates the operating patterns required for production AI in cloud operations: specialist-agent orchestration, tool boundaries, role-based access, approval gates, and tamper-evident accountability. Its remediations are deliberately simulated, making the full workflow safe to explore.

## Architecture

```mermaid
flowchart LR
  U["Analyst / Commander"] -->|JWT| API["HTTP API"]
  API --> T["Triage agent"]
  T --> L["Log-analysis agent"]
  T --> M["Metrics agent"]
  T --> R["Runbook agent"]
  L & M & R --> E["Evidence + recommendation"]
  E --> H{"Human approval"}
  H -->|Approved| X["Simulated remediation tool"]
  H -->|Rejected| N["No action"]
  API -.-> A[("Hash-chained audit log")]
  MCP["MCP client"] --> TOOLS["Incident MCP server"]
  TOOLS --> T
```

## Included scenarios

| Incident | Signals | Recommended remediation |
|---|---|---|
| High CPU | CPU 97%, heap pressure, queue backlog | Scale checkout deployment |
| Failed deployment | CrashLoopBackOff, missing secret | Roll back release |
| Database timeout | Pool saturation, slow queries | Restart orders deployment |
| API latency | High p95, upstream retries | Open circuit breaker |

## Quick start

Requires Node.js 20 or later; there are no third-party runtime dependencies.

```bash
npm start
```

Open [http://localhost:3000](http://localhost:3000). The dashboard uses these intentionally public demo identities:

- `analyst` / `analyst-demo` — investigate incidents
- `commander` / `commander-demo` — investigate and approve/reject remediation
- `auditor` / `auditor-demo` — inspect audit data via the API

For anything beyond local demonstration, set a strong `JWT_SECRET` and connect a real OAuth2/OIDC identity provider. Demo passwords are not production authentication.

## API

```bash
TOKEN=$(curl -s http://localhost:3000/api/auth/token \
  -H 'content-type: application/json' \
  -d '{"username":"analyst","password":"analyst-demo"}' |
  node -pe 'JSON.parse(fs.readFileSync(0)).access_token')

curl http://localhost:3000/api/incidents -H "authorization: Bearer $TOKEN"
curl http://localhost:3000/api/investigations \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"incidentId":"INC-1001"}'
```

## MCP server

The newline-delimited JSON-RPC server exposes `list_incidents`, `investigate_incident`, and `list_approvals`:

```bash
npm run mcp
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "incident-copilot": {
      "command": "node",
      "args": ["/absolute/path/to/ai-incident-response-copilot/src/mcp-server.js"]
    }
  }
}
```

Read-only MCP tools intentionally cannot approve or execute remediation. Approval remains behind the commander-only HTTP boundary.

## Security model

- HMAC-SHA256 JWT verification with expiration checks
- RBAC roles: analyst, commander, and auditor
- Explicit pending approval object for every proposed remediation
- Commander-only approve/reject endpoints
- No direct remediation method exposed over MCP
- Hash-chained JSONL audit events for authentication, agents, tools, approvals, and execution
- UI output escaping and request size limits

This is a demonstration architecture, not a production control plane. Production hardening should add an external OIDC provider, asymmetric JWT verification/JWKS, durable transactional storage, secret management, rate limiting, policy-as-code, and real cloud APIs with least-privilege service identities.

## Development

```bash
npm test
npm run check
docker compose up --build
```

## License

MIT