GitOps Drift Remediation Agent

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
• Architecture
• Features
• Installation
• Configuration
• Usage
• MCP Server
• Policy Engine
• Audit & Telemetry
• Development
• Testing
• Security Considerations
• 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

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

# 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

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

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

{
  "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

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:

{
  "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

# 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

# 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. 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.