Guardian

Pre-publish validation gate for repositories — QA, security, and senior-engineering review in one deterministic check.

Guardian is a standalone tool that runs the same checks a security engineer, QA engineer, and senior engineer would perform before any code is pushed to a public repository. It is designed to be shared across multiple projects without coupling them.

Why a separate repo?

You probably already have publish-time validation logic somewhere. The problem is that it lives inside the project it protects, so:

• Every project reimplements the same secret/path/binary scans
• A security fix in one project doesn't reach the others
• Each project drifts because the rules are slightly different
• AI operators (Copilot, Codex, Claude) can't cleanly call the validator as a tool

Guardian solves this by being the single, versioned source of truth that every project consumes through one of four channels — without importing it as a Python dependency.

Distribution channels

Channel	Setup	Use when
CLI	pipx install guardian	Local terminal validation
pre-commit	Add repo: URL to .pre-commit-config.yaml	Block pushes locally
GitHub Action	uses: Vytalyz/guardian@v1 in workflow	Enforce in CI
MCP server	Add to .vscode/mcp.json (or Claude config)	Let AI operators call Guardian as a tool

All four channels share the same engine in src/guardian/. Pick whichever fits the consumer repo — they can also be combined.

Quick start

Validate a project from the terminal

pipx install guardian
cd /path/to/your-repo
guardian validate --skip-tests

Exit code is 0 when clean, 1 when blocking findings exist (CRITICAL or HIGH).

Wire into pre-commit

Add .pre-commit-config.yaml to the consumer repo:

repos:
  - repo: https://github.com/Vytalyz/guardian
    rev: v1.0.0
    hooks:
      - id: guardian-publish-gate    # blocks pushes (pre-push stage)

Then install the hook locally:

pre-commit install --hook-type pre-push

Wire into GitHub Actions

Add .github/workflows/guardian.yml:

name: Guardian
on: [push, pull_request]
jobs:
  guardian:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Vytalyz/guardian@v1
        with:
          project-root: .
          skip-tests: "true"
          format: "github"

The format: github output writes inline annotations on the PR diff.

Wire as an MCP tool (agent-as-tool)

Install with the MCP optional dependency:

pipx install "guardian[mcp]"

Add to your MCP client config (VS Code Copilot example, .vscode/mcp.json):

{
  "servers": {
    "guardian": { "command": "guardian-mcp" }
  }
}

The AI operator can then call:

• guardian.validate — full validation, returns JSON findings
• guardian.check — run a single named check
• guardian.policy_info — return the resolved policy

This is the "wrap an agentic system as a tool" distribution pattern — any MCP-compatible operator can invoke Guardian without you reimplementing the integration per host.

Configuration

Each consumer repo provides its own policy at config/guardian_policy.toml. Everything is optional; omit a key to inherit the Guardian default. See templates/guardian_policy.toml for the full schema.

[guardian]
project_name = "oracle"

# Disable MT5-specific check for non-trading projects
enabled_checks = [
    "secrets", "paths", "binaries", "logs",
    "sensitive_dirs", "local_config",
    "gitignore_hygiene", "repo_completeness", "test_suite",
]

extra_allowlist = ["docs/setup-windows.md"]
extra_forbidden_tracked_prefixes = ["data/state/"]

[guardian.severity_overrides]
PATH = "MEDIUM"

Built-in checks

Check	Default severity	What it catches
secrets	CRITICAL	API keys, tokens, passwords, GitHub PATs
paths	HIGH	Absolute user paths (C:\Users\..., /home/...)
binaries	HIGH	Tracked .exe, .dll, .parquet, etc.
logs	HIGH	Tracked .log files
terminal_hashes	HIGH	MT5-style 32-char hex install identifiers
sensitive_dirs	CRITICAL	Tracked data/state/, .codex/, etc.
local_config	CRITICAL	Tracked .env, config/local.toml
gitignore_hygiene	HIGH	Missing required .gitignore patterns
repo_completeness	HIGH	Missing LICENSE, SECURITY.md, README.md
test_suite	HIGH	Project test suite fails

Run guardian checks to list every registered check.

AI operator templates

If your project uses AI operators (Copilot agent mode, Codex, Claude Code), copy these into the consumer repo:

• templates/agents/publish-guardian.md
• templates/skills/publish-validation/SKILL.md

These advise the AI operator to call Guardian rather than reimplementing the checks in-prompt.

Repository layout

guardian/
├── src/guardian/
│   ├── cli.py              # `guardian` CLI
│   ├── mcp_server.py       # `guardian-mcp` MCP server
│   ├── validator.py        # orchestrator
│   ├── policy.py           # per-project policy loader
│   ├── findings.py         # Finding model + severity
│   ├── reporters.py        # text / JSON / markdown / GitHub
│   └── checks/             # one module per check
├── templates/              # snippets to drop into consumer repos
├── action.yml              # composite GitHub Action
├── .pre-commit-hooks.yaml  # pre-commit hook registry
└── tests/                  # Guardian's own test suite

Development

git clone https://github.com/Vytalyz/guardian
cd guardian
python -m pip install -e ".[dev,mcp]"
pytest
ruff check .

License

MIT — see LICENSE.