cfgdrift — Semantic-Level Configuration Drift Detection

Detect configuration drift at the semantic level: parse JSON, YAML, TOML, INI, XML, Java properties, .env and nginx into structured semantic trees, ignore comments / indentation / key order, and report only the changes that actually matter — then enforce consistency constraints and, optionally, roll the drifted key back to its baseline value.

CRITICAL / WARN / INFO exit 0 / 1 / 2 Python 3.8+ MIT License

One command line tool for config change audits, security compliance checks, CI gates and routine ops inspection. Cross-platform on Windows / Linux / macOS, with a C-core parser accelerator and a pure-Python fallback.

Why cfgdrift?

Precise detection — added / removed / modified / type-changed drift, graded by severity, with near-zero false positives.
Closed loop, actionable — collect → parse → baseline → diff → report in one command; versioned, rollback-able baselines in SQLite.
Unattended — daemon scans on a schedule and alerts via webhook / email / script with debounce and rule-level retry.
Engineering-friendly — exit-code 0/1/2 contract plugs straight into CI/CD; JSON and single-file offline HTML reports.
Extensible — pluggable parser interface (cfgdrift.parsers) for arbitrary custom formats.
Self-healing — key-level precise rollback that preserves every other byte of the file.

Get started

Installation

One-line pip install, [web]/[dev] extras, dual-wheel model.

Quick Start

5-minute init → scan → baseline → diff minimal loop.

CLI Reference

Every command, its syntax and typical output.

Gallery

Three reproducible end-to-end demos you can run locally.

Reproducible examples

nginx config drift

Plugin parser + range constraint + remediation hint + self-healing.

K8s ConfigMap simulation

Multi-env compare + correlation constraint + sensitive-value masking.

CI gate

Exit-code contract + JSON report + offline HTML artifact.

K8s Secret collection (v0.19.0)

--source k8s gathers ConfigMaps (v0.14.0) and Secrets (v0.19.0) through a read-only kubectl subprocess (zero SDK). Select the resource with --kind configmap|secret|all (default configmap — zero-noise). Secret data (base64) and stringData values are fingerprinted (sha256:<16hex>) at the collector exit: baselines store fingerprints only, and every display exit (terminal / JSON / CSV / HTML / alert / Web / hint) shows ******. Plaintext never leaves the collector.

Project links

README (feature list & detailed semantics): README.md · README.en.md
GitHub repository: github.com/Dongzhiyu0402/cfgdrift
PyPI: pypi.org/project/cfgdrift
License: MIT