agentgateway-config-diff- - GitLite

KO | EN

gitlite — search

#gemini #claude-code #editor #sql #markdown #command-line #mysql #chatgpt #ai-agent #ai

agentgateway-config-diff-

(★ 9)

Diff two agentgateway configs and catch security-relevant drift before it ships: authentication removed from a route, a CORS wildcard slipping in, a dropped rate limit, backend TLS verification switched off, an admin surface leaving loopback, or a hardcoded secret introduced.

File Explorer

ZIP Download

- - baseline.yaml
  - drifted.yaml
- __init__.py
- __main__.py
- cli.py
- diff.py
- grade.py
- loader.py
- model.py
- report.py
- __init__.py
- test_diff.py
- test_grade_report_cli.py
- test_loader.py
- test_model.py
AGENTS.md
LICENSE
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Catch security-relevant drift between two [agentgateway](https://github.com/agentgateway/agentgateway) configs before it ships. Point the tool at a baseline config and a candidate config, and it reports what moved that matters: a route that lost its authentication, a rate limit that got dropped, a CORS wildcard that crept in, a backend whose TLS verification was switched off, a management surface that is now reachable off-box. It grades the change A to F and returns a CI-gated exit code so a risky diff fails the build.

It is stdlib-only Python (3.9+), MIT licensed, and ships a built-in YAML reader so it runs with zero dependencies. PyYAML is used automatically if present, but is never required.

## Why

A config linter tells you whether a single file looks sane. It cannot tell you that this commit quietly removed the JWT policy from your tools route. Drift is a diff problem: the interesting signal is the delta between "what we ran yesterday" and "what this PR wants to run". `agentgateway-config-diff` is the drift half, and it pairs naturally with a static linter like `agentgateway-lint`.

## Install

```bash
git clone https://github.com/shriramkv/agentgateway-config-diff
cd agentgateway-config-diff
pip install .        # optional; the tool also runs straight from the source tree
```

## Usage

```bash
# Diff two configs
agentgateway-config-diff baseline.yaml candidate.yaml

# See it work on the bundled samples
agentgateway-config-diff --demo

# Machine-readable output
agentgateway-config-diff old.yaml new.yaml --format json
agentgateway-config-diff old.yaml new.yaml --format markdown
agentgateway-config-diff old.yaml new.yaml --format badge      # shields.io endpoint JSON
agentgateway-config-diff old.yaml new.yaml --badge-url         # a ready-made shields URL

# Run straight from the source tree
python -m agentgateway_config_diff old.yaml new.yaml
```

### CI gates

```bash
# Fail if the drift grade is worse than B
agentgateway-config-diff old.yaml new.yaml --min-grade B

# Fail if any high-or-worse regression appears
agentgateway-config-diff old.yaml new.yaml --fail-on high

# Fail on any regression at all
agentgateway-config-diff old.yaml new.yaml --fail-on-regression
```

Exit codes: `0` clean or gate satisfied, `2` a gate failed, `3` a config could not be read.

Other flags: `--only ID` (repeatable, show just the named finding types), `--no-improvements` (hide the informational and positive findings), `--prefer-stdlib` (force the built-in YAML reader), `-o FILE` (write output to a file).

## What it detects

Regressions carry a severity. Improvements and neutral facts are reported as info and never lower the grade.

| Finding | Severity |
| --- | --- |
| `auth-removed` (route lost all authentication) | critical |
| `cors-credentialed-wildcard` (any origin plus credentials) | critical |
| `admin-exposed` (management surface left loopback) | critical |
| `auth-weakened` (strong scheme downgraded to a weak one) | high |
| `auth-made-optional` (authentication no longer required) | high |
| `cors-wildcard-introduced` | high |
| `rate-limit-removed` (denial-of-wallet risk) | high |
| `authz-removed` (authorization rules deleted) | high |
| `tls-verification-disabled` (backend cert checks off) | high |
| `new-exposed-route` (new route with no auth) | high |
| `hardcoded-secret-introduced` (value redacted in output) | high |
| `authz-weakened` (fewer authorization rules) | medium |
| `backend-auth-removed` | medium |
| `new-port-exposed` | medium |
| `new-backend-target` (existing route reaches something new) | low |

Positive and neutral changes such as `auth-strengthened`, `rate-limit-added`, `cors-wildcard-removed`, `tls-verification-enabled`, `new-authed-route`, `port-removed`, and `route-removed` are reported for context only.

## Grading

The score starts at 100 and subtracts a weighted penalty per regression (critical 45, high 20, medium 8, low 3). Two caps encode the idea that some drift is disqualifying regardless of the arithmetic: any critical regression caps the grade at F, and any high regression (with no critical) caps it at C. A clean diff is A / 100.

## Matching, not line diffing

The tool does not compare raw text. It builds a normalized security model of each config first (routes keyed by name or by listener and host, with auth kind, CORS posture, rate limiting, authorization, backend TLS, and backends), then compares the two models. Reordering routes or reformatting the file does not register as change. Only meaning does.

## How routes are read

Configs are walked as `binds -> listeners -> routes`, with tolerance for top-level `listeners:` or `routes:` and for a few policy-key spellings. Each route yields one normalized view. Secrets are detected as inline string values on secret-like keys (`key`, `password`, `token`, `secret`, and similar) that are not environment, file, or vault references.

## Development

```bash
python -m unittest discover -s tests -v
```

No dependencies are required to run the tests. CI runs the suite on Python 3.9 through 3.12.

## License

MIT. See [LICENSE](LICENSE).