Configuration Change Validation Tool

Configuration Change Validation Tool is a Python CLI for reviewing planned configuration changes before implementation. It compares current and planned YAML configuration files, applies YAML-defined engineering rules, calculates operational risk, and generates a Markdown report with an approval checklist and rollback recommendation.

The examples model change-control concerns that appear in telecom, railway infrastructure, industrial networks, and system integration work: recovery access, gateway consistency, maintenance-window readiness, backup status, approval requirements, and rollback planning.

Why This Project Exists

Manual configuration reviews often rely on repeated checks: has recovery access been preserved, are gateway and subnet changes consistent, is a rollback plan documented, and does the change need senior approval? In large change windows, many parameters may be reviewed by hand. This project turns that review pattern into a reproducible CLI workflow.

Problem Statement

Configuration changes can be technically valid YAML while still being operationally risky. A planned file may parse correctly but remove NTP, change a management address without approval, break gateway reachability, or miss a maintenance window. The goal is to detect those risks before implementation and produce a report that supports a clear change-review discussion.

Architecture

The tool follows a simple validation pipeline: it loads current and planned configurations, computes changes, applies rule-based checks, scores operational risk, and generates an approval-ready Markdown report.

flowchart LR
    A[Current Configuration<br/>YAML] --> C[Config Parser]
    B[Planned Configuration<br/>YAML] --> C
    R[Validation Rules<br/>YAML] --> E[Rule Engine]

    C --> D[Diff Engine]
    D --> E
    E --> F[Risk Scoring]
    F --> G[Approval Decision]
    F --> H[Approval Checklist]
    F --> I[Rollback Recommendation]

    G --> J[Markdown Report]
    H --> J
    I --> J

Loading

Features

• YAML-based current and planned configuration parsing
• Recursive diff engine for nested configuration fields
• Rule files stored in YAML rather than hardcoded into one script
• Validation categories for schema, safety, network consistency, change risk, operational readiness, and rollback
• Risk score and approval decision mapping
• Markdown report generation with change tables and rule results
• uv-native dependency management with pyproject.toml and uv.lock
• CLI entry points using uv run python -m change_validator and uv run change-validator
• Synthetic examples for network, RAN-like, and industrial controller domains
• Ruff, mypy, pytest-cov, and GitHub Actions CI

Example Configuration Domains

Network configuration:

• device_id, site, device_type, management_ip
• Interfaces with VLAN, MTU, and IP address
• Default gateway and static routes
• SSH, SNMP, and NTP settings

Telecom / RAN-like configuration:

• cell_id, site, band, pci, tac
• max_tx_power_dbm, handover_margin_db
• Neighbor cell list

System / industrial controller configuration:

• system_id, environment, redundancy settings
• Backup requirement and maintenance window
• Logging level and rollback plan

Validation Rule Examples

Network rules:

• NET-001: Management IP must not change without approval. Severity: critical.
• NET-002: MTU must stay between 1280 and 9000. Severity: high.
• NET-003: Default gateway must be reachable in the same subnet. Severity: high.
• NET-004: SSH must remain enabled for remote recovery. Severity: critical.

RAN rules:

• RAN-001: PCI must be between 0 and 1007. Severity: critical.
• RAN-002: TX power change above 3 dB requires high-risk approval. Severity: high.
• RAN-003: Neighbor cell list must not be empty. Severity: high.
• RAN-004: TAC change requires rollback plan. Severity: critical.

Operational/system rules:

• OPS-001: Production changes require a maintenance window. Severity: critical.
• OPS-002: Backup must be confirmed before change. Severity: critical.
• OPS-003: Rollback plan must exist for high-risk changes. Severity: critical.

Implemented check types:

• range
• must_equal
• not_empty
• max_delta
• no_change_without_approval
• subnet_consistency
• required_if_environment_production
• requires_rollback_plan
• required_if_risk_high

Risk Scoring Logic

Severity points:

• critical = 40 points
• high = 25 points
• medium = 10 points
• low = 5 points

Risk levels:

• 0-20 = Low Risk
• 21-50 = Medium Risk
• 51-90 = High Risk
• 90+ = Critical Risk

Approval decision:

• Low Risk -> Approved
• Medium Risk -> Approved with review
• High Risk -> Requires senior approval
• Critical Risk -> Rejected / blocked

CLI Usage

Install uv if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create the project environment from pyproject.toml and uv.lock:

uv sync

Run the network validation example:

uv run python -m change_validator validate \
  --current configs/current/router_site_a.yaml \
  --planned configs/planned/router_site_a.yaml \
  --rules rules/network_rules.yaml \
  --output reports/router_site_a_change_report.md

The console script is also available through uv:

uv run change-validator validate \
  --current configs/current/router_site_a.yaml \
  --planned configs/planned/router_site_a.yaml \
  --rules rules/network_rules.yaml \
  --output reports/router_site_a_change_report.md

Report Preview

The failed router example shows how the tool escalates a risky planned change before implementation. It identifies a management IP change without approval, a default gateway/subnet mismatch, and an empty NTP server list.

Validation completed.

Changed fields: 6
Passed checks: 14
Failed checks: 3
Risk score: 75
Risk level: HIGH
Decision: REQUIRES SENIOR APPROVAL

Report saved to:
reports/router_site_a_change_report.md

Preview assets:

• CLI output: docs/assets/cli-output-router-site-a.txt
• Report excerpt: docs/assets/router-site-a-report-preview.md
• Full generated report: reports/router_site_a_change_report.md

Sample Failed Validation Explanation

The sample router change fails because the management IP changes without approval, the planned gateway is no longer reachable from the planned uplink subnet, and the NTP server list is empty. These are not syntax errors; they are operational risks that could affect recovery access, routing reachability, and event correlation during an incident.

Failed example report: examples/failed_change_example.md

Sample Approved Validation Explanation

The sample RAN change adjusts PCI, handover margin, TX power, and neighbor relations while staying inside the defined validation limits. It keeps the neighbor list populated, maintains backup and maintenance-window readiness, and has an available rollback plan.

Approved example report: examples/approved_change_example.md

Development and QA

Linting and Formatting

Run linting and formatting checks:

uv run ruff check .
uv run ruff format --check .

Format code before committing:

uv run ruff format .

Static Type Checking

Run mypy against the source package:

uv run mypy src

Tests and Coverage

Run tests locally:

uv run pytest -v

Generate terminal and XML coverage reports:

uv run pytest --cov=src/change_validator --cov-report=term-missing --cov-report=xml

This writes coverage.xml locally and in CI.

The GitHub Actions workflow in .github/workflows/ci.yml installs uv, syncs dependencies from uv.lock, runs Ruff lint and format checks, runs mypy, runs pytest with coverage reporting, and performs CLI smoke tests on every push and pull request.

Regenerate Sample Reports

Generate the included sample reports:

uv run change-validator validate \
  --current configs/current/router_site_a.yaml \
  --planned configs/planned/router_site_a.yaml \
  --rules rules/network_rules.yaml \
  --output reports/router_site_a_change_report.md

uv run change-validator validate \
  --current configs/current/ran_cell_001.yaml \
  --planned configs/planned/ran_cell_001.yaml \
  --rules rules/ran_rules.yaml \
  --output reports/ran_cell_001_change_report.md

uv run change-validator validate \
  --current configs/current/controller_01.yaml \
  --planned configs/planned/controller_01.yaml \
  --rules rules/system_rules.yaml \
  --output reports/controller_01_change_report.md

Engineering relevance

“This project demonstrates how manual configuration review logic can be translated into a reproducible validation workflow. The focus is not only on parsing files, but on identifying operational risks before implementation: recovery access, rollback readiness, maintenance-window discipline, parameter consistency, and approval requirements.”

This is relevant to engineering work where configuration changes need to be reviewed consistently, documented clearly, and approved based on operational impact rather than file syntax alone.

German Keywords

• Konfigurationsvalidierung
• Change Management
• Qualitätssicherung
• Systemintegration
• Fehlervermeidung
• Rollback-Planung
• Netzwerkbetrieb
• Technische Dokumentation

Known Limitations

This project focuses on demonstrating change-validation logic and operational risk analysis concepts rather than implementing a full production orchestration platform.

• Configuration data is synthetic and intentionally limited to representative network, RAN-like, and controller examples.
• Validation logic is simplified and rule-driven; it does not model every operational dependency, vendor behavior, or environment-specific exception.
• The tool does not connect to live routers, OSS platforms, industrial controllers, ticketing systems, approval systems, or deployment pipelines.
• Rollback output is advisory documentation only; the tool does not execute transactional rollback or device configuration changes.
• Vendor-specific parsers are not implemented. Inputs are normalized YAML examples rather than native device configuration formats.
• Schema normalization is limited to the fields used by the example domains and YAML rule files.
• The YAML rule engine is intentionally compact and transparent, with a small set of supported check types.
• Approval workflow support is local to the generated report. There is no distributed approval state, authentication, RBAC, or audit-log backend.
• The project does not include large-scale configuration inventory management, concurrent batch execution, or historical drift tracking.
• It is not intended for direct production deployment without substantial integration, validation, security review, and environment-specific policy work.

The goal of the project is to model realistic change-control thinking and validation workflows in a reproducible engineering environment.

Future Improvements

• Add JSON input support alongside YAML.
• Add stricter schema validation for each domain.
• Add rule tags for change windows, technology owner, and approval group.
• Export reports to HTML or PDF.
• Add batch validation for a folder of planned changes.
• Add baseline health checks from synthetic pre/post-change telemetry files.

Disclaimer

“This project uses synthetic configuration data and simplified validation rules. It is inspired by real production change-control workflows, but it is not connected to any live operator, railway, or industrial system.”