Metadata-Version: 2.5
Name: yamlguard
Version: 3.5.1
Summary: Validate YAML files for syntax, linting, and security issues — fast CLI tool
Project-URL: Homepage, https://github.com/pooyanazad/yamlguard
Project-URL: Repository, https://github.com/pooyanazad/yamlguard
Project-URL: Bug Tracker, https://github.com/pooyanazad/yamlguard/issues
Project-URL: Changelog, https://github.com/pooyanazad/yamlguard/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

# yamlguard

[![CI](https://github.com/pooyanazad/yamlguard/actions/workflows/docker-build.yml/badge.svg)](https://github.com/pooyanazad/yamlguard/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 your YAML files before you commit or deploy them. **yamlguard** catches syntax errors and style issues, and can scan supported infrastructure files for security problems with Checkov.

Install the `yamlguard` CLI from PyPI, or use the Docker image `pooyanazad/yaml-checker`. Both run the same validator; Docker includes Checkov. The current Docker release uses the earlier image name; future releases will use `pooyanazad/yamlguard`.

## Install and run

### Python

Requires Python 3.9 or newer. Create a virtual environment so the installation stays separate from your system Python.

**Linux / macOS:**

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install yamlguard
```

**Windows — Command Prompt:**

```bat
py -m venv .venv
.venv\Scripts\activate
python -m pip install yamlguard
```

In PowerShell, activate the environment with `.\.venv\Scripts\Activate.ps1` instead.

Then check a file:

```bash
yamlguard config.yaml
```

The base installation checks syntax with PyYAML and style with yamllint. To add security scanning, install the optional extra in the same environment:

```bash
python -m pip install "yamlguard[security]"
yamlguard deployment.yaml
```

Checkov checks supported infrastructure formats, such as Kubernetes manifests. Without Checkov, syntax and style checks still run, with a warning that security scanning was skipped.

### Docker

With Docker installed, open a terminal in the folder containing your YAML files and run:

**Linux / macOS:**

```bash
docker run --rm -v "$(pwd):/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml
```

**Windows — PowerShell:**

```powershell
docker run --rm -v "${PWD}:/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml
```

**Windows — Command Prompt:**

```bat
docker run --rm -v "%cd%:/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml
```

These commands mount your current folder read-only at `/data`. Use paths within that folder, such as `config.yaml` or `./configs/`. Files must be readable by the container's non-root user.

Images support `linux/amd64` and `linux/arm64`. The examples use the published 3.5.0 image. Use the Docker image and versioned tag shown under **Latest release** when choosing another release.

## Everyday examples

```bash
yamlguard config.yaml                        # Check one file
yamlguard config.yaml deployment.yml         # Check several files
yamlguard ./configs/                         # Check all .yaml and .yml files recursively
yamlguard "./configs/**/*.yaml"              # Let yamlguard expand the pattern
yamlguard ./configs/ --no-security            # Run syntax and style checks only
yamlguard deployment.yaml --timeout 60       # Limit each validator subprocess to 60 seconds
```

With Docker, pass these same arguments after the image name. For example, replace `config.yaml` in the Docker command with `./configs/ --no-security`.

Run `yamlguard --help` for all options. You can also run the CLI as `python -m yamlguard`. Missing paths are skipped with a warning; the command fails if no files remain.

## Reports and exit codes

Text output is the default. For CI or other tools, export a report:

```bash
yamlguard ./configs/ --format json > results.json
yamlguard ./configs/ --format junit > test-results.xml
yamlguard ./configs/ --format sarif > results.sarif
```

JSON returns one object for one file or an array for several files. JUnit XML works with test-report viewers; SARIF 2.1.0 works with compatible code-scanning tools. Upload reports through your CI configuration.

In version 3.5.0 and newer, machine-readable reports go to stdout and warnings go to stderr.

| Exit code | Meaning |
| --- | --- |
| `0` | No findings, or only Medium / Low / Info findings. |
| `1` | Critical / High findings, no matching files, or a required dependency is missing. |
| `2` | Invalid command-line arguments. |

Syntax errors are Critical. Lint errors are Medium and warnings are Low, so **lint findings alone do not fail the command**. Checkov findings without a severity default to High.

## Project links

[Releases](https://github.com/pooyanazad/yamlguard/releases) · [Report an issue](https://github.com/pooyanazad/yamlguard/issues) · [Contributing](CONTRIBUTING.md) · [Maintainer release guide](release-notes/README.md)

## Latest release

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

**Changes since `v3.5.0-20261011`** (7 non-merge commits).

- Build and maintenance: 2 commit(s).
- Fixes: 3 commit(s).
- Documentation: 2 commit(s).

[Full changelog](https://github.com/pooyanazad/yamlguard/compare/v3.5.0-20261011...v3.5.1-20261011)

**Docker image:** `pooyanazad/yamlguard:v3.5.1-20261011`

<!-- RELEASE_NOTES_END -->
