# GitOps Drift Remediation Agent

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org)

> A production-grade autonomous agent that connects to Kubernetes clusters and GitOps repositories, identifies unauthorized state drift, generates safe remediation strategies, and executes automated API patches or Pull Requests.

---

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [MCP Server](#mcp-server)
- [Policy Engine](#policy-engine)
- [Audit & Telemetry](#audit--telemetry)
- [Development](#development)
- [Testing](#testing)
- [Security Considerations](#security-considerations)
- [Contributing](#contributing)

---

## Overview

The **GitOps Drift Remediation Agent** is an autonomous, policy-driven platform that continuously monitors the live state of Kubernetes resources against their declared GitOps source of truth. When drift is detected, the agent evaluates applicable remediation policies, computes minimal JSON Patch operations, and either applies them directly via the Kubernetes API or opens Pull Requests against the GitOps repository — all with full audit trails.

### Core Principles

- **Minimal blast radius**: patches are computed as the smallest possible diff, never full resource replacements
- **Policy-first**: every remediation action is gate-kept by configurable, versioned policies with risk tiers
- **Immutable audit log**: every decision, detection and mutation is recorded with cryptographic context
- **GitOps-native**: the agent is itself managed by GitOps and emits PRs back to the repository
- **MCP-ready**: exposes all capabilities as MCP tools for LLM-agent integration

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                    GitOps Drift Remediation Agent                   │
│                                                                     │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────────────────┐ │
│  │  AST Differ │───▶│ Policy Engine│───▶│    Patch Engine        │ │
│  │             │    │              │    │                        │ │
│  │ • Deep diff │    │ • Risk tiers │    │ • JSON Patch RFC 6902  │ │
│  │ • Field     │    │ • Allow/deny │    │ • K8s API apply        │ │
│  │   tracking  │    │ • Dry-run    │    │ • PR generation        │ │
│  │ • Severity  │    │ • Approvals  │    │ • Rollback support     │ │
│  └─────────────┘    └──────────────┘    └────────────────────────┘ │
│         │                  │                       │                │
│         └──────────────────┴───────────────────────┘                │
│                            │                                        │
│                   ┌────────▼────────┐                               │
│                   │  Audit Logger   │                               │
│                   │                 │                               │
│                   │ • Structured    │                               │
│                   │   JSON logs     │                               │
│                   │ • Event chain   │                               │
│                   │ • Pino backend  │                               │
│                   └─────────────────┘                               │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                      MCP Server                              │  │
│  │  detect_drift │ list_policies │ remediate │ get_audit_trail  │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
         │                                          │
         ▼                                          ▼
  ┌─────────────┐                          ┌───────────────┐
  │  Kubernetes │                          │  GitOps Repo  │
  │  Cluster(s) │                          │  (Git/GitHub) │
  └─────────────┘                          └───────────────┘
```

---

## Features

| Feature | Description |
|---|---|
| **Drift Detection** | Deep AST-based diffing of live vs desired Kubernetes resource state |
| **Risk Classification** | Automated severity scoring (critical / high / medium / low) per field path |
| **Policy Engine** | Declarative, versioned policies with allow/deny rules, dry-run, and approval gates |
| **Patch Engine** | RFC 6902 JSON Patch computation with K8s server-side apply support |
| **GitOps PRs** | Automated Pull Request generation with drift diff and remediation rationale |
| **Audit Trail** | Immutable structured audit logs with full decision chains |
| **MCP Server** | All agent capabilities exposed as MCP tools for AI agent orchestration |
| **CLI** | Full-featured CLI for interactive and automated operation |

---

## Installation

### Prerequisites

- Node.js >= 20.0.0
- kubectl configured with target cluster access
- Git credentials for GitOps repository (for PR mode)

### Install from source

```bash
git clone https://github.com/your-org/gitops-drift-remediation-agent.git
cd gitops-drift-remediation-agent
npm install
npm run build
npm link   # optional: makes `drift-agent` available globally
```

---

## Configuration

All configuration is passed via environment variables or a config file.

### Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `KUBECONFIG` | No | `~/.kube/config` | Path to kubeconfig file |
| `KUBECONTEXT` | No | current-context | Kubernetes context to use |
| `GITOPS_REPO_URL` | No | — | GitOps repository URL for PR mode |
| `GITOPS_BRANCH` | No | `main` | Target branch for PRs |
| `GITOPS_TOKEN` | No | — | Git provider token (GitHub/GitLab) |
| `POLICY_CONFIG_PATH` | No | `./policies.yaml` | Path to remediation policy config |
| `AUDIT_LOG_PATH` | No | `./audit.log` | Audit log output path |
| `AUDIT_LOG_LEVEL` | No | `info` | Log level (debug/info/warn/error) |
| `DRY_RUN` | No | `false` | Global dry-run mode |
| `MCP_PORT` | No | `3000` | MCP server HTTP port |
| `NAMESPACE_FILTER` | No | `*` | Comma-separated namespace filter |

---

## Usage

### CLI Commands

```bash
# Detect drift across all namespaces
drift-agent detect --namespace production --output json

# Detect and auto-remediate with policy gate
drift-agent remediate --namespace production --policy strict --dry-run

# List active policies
drift-agent policy list

# Show audit trail for a resource
drift-agent audit --resource deployments/my-app --namespace production

# Start MCP server
drift-agent mcp-server --port 3000
```

### Programmatic API

```typescript
import { AstDiffer } from './src/detector/ast-differ';
import { RemediationPolicy } from './src/policy/remediation-policy';
import { PatchEngine } from './src/remediator/patch-engine';

const differ = new AstDiffer();
const drifts = await differ.detectDrift(liveResource, desiredResource);

const policy = new RemediationPolicy(policyConfig);
const decision = await policy.evaluate(drifts, resourceContext);

if (decision.approved) {
  const engine = new PatchEngine(k8sClient);
  await engine.applyRemediation(decision.patches, resourceRef);
}
```

---

## MCP Server

The agent exposes an MCP (Model Context Protocol) server that makes all agent capabilities available as tools for LLM-based agents (Claude, GPT-4, etc.).

### Starting the Server

```bash
drift-agent mcp-server --port 3000
# or
npm run mcp:server
```

### Available MCP Tools

| Tool | Description |
|---|---|
| `detect_drift` | Detect drift for a resource or namespace |
| `list_policies` | List all configured remediation policies |
| `evaluate_policy` | Evaluate drift against a specific policy |
| `apply_remediation` | Apply computed remediation patches |
| `get_audit_trail` | Retrieve audit events for a resource |
| `generate_pr` | Generate a GitOps PR for drift remediation |
| `rollback_remediation` | Roll back a previously applied remediation |

### MCP Client Configuration

```json
{
  "mcpServers": {
    "gitops-drift-agent": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}
```

---

## Policy Engine

Policies are defined declaratively and control every aspect of the remediation lifecycle.

### Policy Structure

```yaml
apiVersion: drift.gitops.io/v1
kind: RemediationPolicy
metadata:
  name: production-strict
spec:
  riskTier: high
  autoRemediate: false
  requireApproval: true
  dryRunFirst: true
  rules:
    - field: "spec.replicas"
      action: restore
      severity: high
    - field: "spec.template.spec.containers[*].image"
      action: block
      severity: critical
  excludeFields:
    - "metadata.annotations['kubectl.kubernetes.io/last-applied-configuration']"
    - "metadata.resourceVersion"
    - "metadata.uid"
```

---

## Audit & Telemetry

Every agent action is recorded in structured JSON format:

```json
{
  "timestamp": "2024-06-01T12:00:00.000Z",
  "eventId": "evt_01J0ABC123",
  "eventType": "DRIFT_DETECTED",
  "severity": "high",
  "resource": {
    "kind": "Deployment",
    "name": "my-app",
    "namespace": "production",
    "apiVersion": "apps/v1"
  },
  "drift": {
    "field": "spec.replicas",
    "desired": 3,
    "live": 1,
    "changeType": "edited"
  },
  "policy": {
    "name": "production-strict",
    "decision": "remediate",
    "riskTier": "high"
  },
  "actor": {
    "agentVersion": "1.0.0",
    "kubeContext": "prod-cluster"
  }
}
```

---

## Development

```bash
# Install dependencies
npm install

# Run in development mode (ts-node)
npm run dev -- detect --namespace default

# Type check only
npm run typecheck

# Lint
npm run lint

# Format
npm run format

# Build
npm run build
```

---

## Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch
```

Tests are organized under `tests/` and use Jest with ts-jest. Mocks are provided for the Kubernetes client and file system operations.

---

## Security Considerations

1. **Least privilege**: The agent requires only `get`, `list`, `watch`, and `patch` permissions on target resources — never `delete` or `create`
2. **Dry-run by default**: All policy tiers default to dry-run until explicitly enabled
3. **Approval gates**: High and critical risk changes require explicit approval via policy
4. **Audit immutability**: Audit logs are append-only; log rotation is handled externally
5. **Secret masking**: Secret resource values are always redacted in logs and PRs
6. **Kubeconfig isolation**: The agent never mutates the kubeconfig

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions require:

- Passing test suite with >= 80% coverage
- No new lint warnings
- Audit log entries for any new mutation paths
- Policy evaluation for any new remediation actions

---

## License

Apache 2.0 — see [LICENSE](LICENSE).