Metadata-Version: 2.5
Name: yamlguard
Version: 3.5.0
Summary: Validate YAML files for syntax, linting, and security issues — fast CLI tool
Project-URL: Homepage, https://github.com/pooyanazad/YAML-validator
Project-URL: Repository, https://github.com/pooyanazad/YAML-validator
Project-URL: Bug Tracker, https://github.com/pooyanazad/YAML-validator/issues
Project-URL: Changelog, https://github.com/pooyanazad/YAML-validator/releases
Author: pooyanazad
License-Expression: MIT
License-File: LICENSE
Keywords: checkov,ci,devops,kubernetes,lint,security,validate,yaml,yamllint
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: colorama>=0.4.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: yamllint>=1.26.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: jsonschema; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-json-report; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: security
Requires-Dist: checkov>=3.0.0; extra == 'security'
Description-Content-Type: text/markdown

# YAML Validator · yamlguard

[![CI](https://github.com/pooyanazad/YAML-validator/actions/workflows/docker-build.yml/badge.svg)](https://github.com/pooyanazad/YAML-validator/actions/workflows/docker-build.yml)
[![PyPI](https://img.shields.io/pypi/v/yamlguard.svg)](https://pypi.org/project/yamlguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Check YAML syntax, catch style problems, and scan supported infrastructure configurations with one command. Install the **`yamlguard`** Python CLI, or run **`pooyanazad/yaml-checker`** with Docker.

## Get started

### Python CLI

Use an isolated environment such as pipx:

```bash
pipx install yamlguard
yamlguard myfile.yaml
```

Or install into your Python environment:

```bash
python -m pip install yamlguard
yamlguard myfile.yaml
```

If your package index reports that `yamlguard` is unavailable, install the tagged source instead (requires Git):

```bash
python -m pip install 'git+https://github.com/pooyanazad/YAML-validator.git@v3.4.0-20261011'
```

The base package includes **PyYAML and yamllint**. To add **Checkov security checks**, install the optional extra in the same environment:

```bash
python -m pip install 'yamlguard[security]'
# With pipx, use: pipx install 'yamlguard[security]'
```

If Checkov is unavailable, validation continues with syntax and lint checks and reports that security scanning was skipped. Python 3.12 is used in CI and Docker; the package declares Python 3.9 or newer, subject to dependency compatibility.

### Docker

Docker includes all three tools, including Checkov. Mount the directory containing your YAML files; paths inside the container are relative to `/data`.

**Linux/macOS:**

```bash
docker run --rm -v "$(pwd):/data:ro" pooyanazad/yaml-checker:latest myfile.yaml
```

**Windows PowerShell:**

```powershell
docker run --rm -v "${PWD}:/data:ro" pooyanazad/yaml-checker:latest myfile.yaml
```

**Windows Command Prompt:**

```bat
docker run --rm -v "%cd%:/data:ro" pooyanazad/yaml-checker:latest myfile.yaml
```

For repeatable runs, replace `latest` with a release tag such as `v3.4.0-20261011`. Images are built for `linux/amd64` and `linux/arm64`, use Python 3.12, and run as a non-root user. Mounted files must be readable by that user.

Optional Bash/Zsh shortcut: add this function to `~/.bashrc` or `~/.zshrc`, then reload your shell. It mounts your current directory each time you run it.

```bash
ytest() {
  docker run --rm -v "$(pwd):/data:ro" pooyanazad/yaml-checker:latest "$@"
}

ytest myfile.yaml
```

## Scan files and directories

```bash
yamlguard config.yaml                         # One file
yamlguard config.yaml deployment.yml          # Multiple files
yamlguard ./configs/                          # Recursively scan .yaml and .yml files
yamlguard './configs/**/*.yaml'               # Quote globs so yamlguard expands them
yamlguard ./configs/ --no-security             # Skip Checkov scanning
yamlguard deployment.yaml --timeout 60        # Limit each validator subprocess to 60 seconds
```

The same arguments work with Docker or `ytest`. Repeated paths are scanned once. Missing paths produce a warning and are skipped; the command fails if no files remain. The default subprocess timeout is 300 seconds; dependency probes have a separate 30-second timeout.

Run `yamlguard --help` for all options or `yamlguard --version` to check the installed version. From a source checkout, `python -m yaml_validator` provides the same CLI.

## What gets checked

| Check | Tool | Behavior |
|---|---|---|
| Syntax | PyYAML | Parses YAML, including multiple documents; reports parse and file-read errors. |
| Style | yamllint | Reports indentation, line length, trailing spaces, duplicate keys, and other lint rules. |
| Security | Checkov, when installed | Runs Checkov's checks for supported infrastructure formats, such as Kubernetes manifests. Findings depend on the file and Checkov version. |

Text reports group findings by **Critical, High, Medium, Low, and Info**. Scanning several files also produces a combined summary. Checkov is not a universal security check for arbitrary application YAML; a clean report covers only the checks that ran.

### Exit codes

| Code | Meaning |
|---|---|
| `0` | No findings, or only Medium/Low/Info findings. |
| `1` | Critical/High findings, no matching files, or a required dependency is unavailable. |
| `2` | Invalid CLI arguments (argparse). |

**Lint findings alone usually do not fail the command:** yamllint errors map to Medium and warnings to Low. Syntax errors are Critical. Checkov findings without an explicit severity default to High.

## Export reports for CI

Choose `--format` (or `-f`):

```bash
yamlguard ./configs/ --format text             # Human-readable report (default)
yamlguard ./configs/ --format json > results.json
yamlguard ./configs/ --format junit > test-results.xml
yamlguard ./configs/ --format sarif > results.sarif
```

- **JSON:** one object for a single file, an array for multiple files. Each result includes the path, syntax status, severity counts, and findings.
- **JUnit XML:** Critical/High findings become failures; less severe findings appear as skipped test cases.
- **SARIF 2.1.0:** a report you can upload to a compatible code-scanning service, including GitHub Code Scanning. Generating the file does not upload it automatically.

Reports go to stdout. In the updated source, diagnostics for machine-readable formats go to stderr; the CLI at the `v3.4.0-20261011` source tag can put missing-tool or path warnings on stdout, so check that version's redirected report before consuming it. Preserve the exit code when your CI collects a report after validation fails.

## Releases and contributing

Starting with 3.5.0, the package version in `yaml_validator/__init__.py` determines both releases: PyPI uses `X.Y.Z`, and GitHub/Docker use `vX.Y.Z-YYYYMMDD` (UTC). Older Docker tags may differ from their Python package version.

The pipeline runs checks on pushes and pull requests. Maintainers publish a new version by running **Docker Build and Push** on `main`; it builds Docker images, creates the GitHub release, and starts **Release & Publish to PyPI** automatically. Check that second workflow's result to confirm publication. Monthly runs refresh Docker `latest` without creating another release if the package version is already released.

The README's latest-release block is updated through a separate PR generated by the pipeline; merge it to update this page. **Refresh Release Notes** is optional: it repairs an existing GitHub release description and is not needed for a new release. See the [maintainer release instructions](release-notes/README.md).

See [all releases](https://github.com/pooyanazad/YAML-validator/releases), [report an issue](https://github.com/pooyanazad/YAML-validator/issues), or read the [contributing guide](CONTRIBUTING.md).

## Latest release

<!-- RELEASE_NOTES_START -->
### v3.5.0-20261011 — 2026-10-11

**Changes since `v3.4.0-20261011`** (3 non-merge commits).

- Rewrote the README around the actual CLI behavior, optional Checkov installation, report formats, exit codes, and working Docker commands.
- Replaced repeated release features with highlights for the validated previous-tag-to-current-commit range, with full commit details collapsed on GitHub.
- Kept JSON, SARIF, and JUnit output clean by sending path and dependency diagnostics to stderr and suppressing text warnings in report mode.
- Unified package and Docker/GitHub versions at 3.5.0. New release tags come from the package version; monthly rebuilds no longer invent new package releases.
- Added publication checks for matching tag/package versions, existing PyPI versions, and existing Docker tags; fixed PyPI dispatch and regenerated the packaged README before building.
- Added a manual tool to repair an existing GitHub release description, plus regression tests for release planning and machine-readable CLI output.

[Full changelog](https://github.com/pooyanazad/YAML-validator/compare/v3.4.0-20261011...v3.5.0-20261011)

**Docker image:** `pooyanazad/yaml-checker:v3.5.0-20261011`

<!-- RELEASE_NOTES_END -->
