KynSec AI Guard
Security auditing for the local AI stack.
Find dangerous MCP servers, hardcoded credentials, exposed host paths, and prompt-injection payloads before they reach production.
Why AI-Guard? · Quickstart · Usage · Rules · CI integration · Architecture · Contributing
AI agent configuration is executable configuration. An MCP server entry can launch a shell, mount the host filesystem, or expose an unauthenticated network listener. A system prompt can instruct an agent to hide actions from its user. A dotfile can contain a live cloud key.
KynSec AI Guard is a fast, offline, read-only static analyzer for that entire surface:
- Claude Desktop, Claude Code, Cline, Cursor, Windsurf, OpenCode, and VS Code MCP configuration
- Model Context Protocol (MCP) server definitions
- System prompts, instruction files, and Markdown policies
- Local LLM deployment and tool configuration
.envfiles and other credential-bearing text files
No telemetry. No network calls. No secrets in reports.
Why AI-Guard?
| Risk | What AI-Guard does |
|---|---|
MCP servers that wrap bash, inline interpreters, or privilege commands |
Flags executable entry points and recommends fixed, allow-listed binaries |
| Remote MCP endpoints with no authentication or plaintext transport | Detects unauthenticated, cleartext, and wildcard-bound listeners |
| Blanket auto-approval of tools | Identifies auto-approval lists that include file, shell, network, or wildcard capabilities |
| Container breakout primitives | Detects privileged containers, Docker socket mounts, host mounts, and sandbox bypass flags |
| Secrets pasted into agent config | Recognizes major provider token formats plus high-entropy assignments, and redacts values |
Agent access to /, /etc, home credentials, or Windows system directories |
Reports dangerous mounts and traversal sequences with line numbers |
| Prompt-injection payloads and hidden Unicode | Runs heuristic analysis over prompts and every string value in structured configs |
| Malformed or hand-edited JSON/YAML/TOML | Keeps scanning, reports the parse failure, and still checks raw text for secrets |
Quickstart
Install from PyPI
KynSec AI Guard is distributed as kynsec-ai-guard on PyPI:
pipx install kynsec-ai-guard
# or
python -m pip install kynsec-ai-guard
Install from source
git clone https://github.com/KynSec/kynsec-ai-guard.git
cd kynsec-ai-guard
python -m pip install .
Verify the installation:
ai-guard --version
ai-guard --help
Run your first scan
# Audit a single Claude Desktop config
ai-guard scan ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Audit a project, only failing CI on HIGH and CRITICAL findings
ai-guard scan . --min-severity HIGH
# Specialized MCP audit for a config or directory
ai-guard audit-mcp ./mcp.json
# Machine-readable report for automation
ai-guard scan . --format json --output ai-guard.json
Example terminal output:
╭──────────────────── AI-Guard scan summary ────────────────────╮
│ Target ./mcp.json │
│ Files 1 scanned │
│ Findings 2 │
│ By severity CRITICAL 1 HIGH 1 │
╰──────────────────────────────────────────────────────────────╯
Security findings (2)
┏━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Severity ┃ Rule ┃ Location ┃ Finding ┃
┡━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ CRITICAL │ MCP002 │ mcp.json:12 │ MCP server 'local' │
│ │ │ │ exposes a listener │
│ │ │ │ on all interfaces │
│ HIGH │ MCP001 │ mcp.json:4 │ MCP server 'shell' │
│ │ │ │ launches a raw shell │
└───────────┴──────────┴────────────────────┴───────────────────────┘
Usage
ai-guard scan <path>
Scans a file or directory. Directory scans recursively discover supported configuration, prompt, and environment files while skipping dependency, virtual-environment, and VCS directories.
ai-guard scan <path> [OPTIONS]
| Option | Default | Description |
|---|---|---|
--min-severity, -s |
info |
Report only findings at or above critical, high, medium, low, or info |
--format, -f |
table |
Output format: table, json, or sarif |
--output, -o |
stdout | Write the report to a file. Use - for stdout |
--verbose, -v |
off | Add evidence, remediation, and references to terminal output |
--quiet, -q |
off | Disable the progress bar |
ai-guard audit-mcp <config-path>
Runs the MCP-focused rule set: MCP security, secrets, and path exposure. This is useful when reviewing a new server before adding it to an agent.
ai-guard audit-mcp ./claude_desktop_config.json
ai-guard audit-mcp . --format sarif --output ai-guard.sarif
ai-guard rules
Lists every built-in rule with its identifier, severity, and category.
ai-guard rules
Exit codes
AI-Guard is designed for CI/CD pipelines and shell automation.
| Exit code | Meaning |
|---|---|
0 |
Scan completed with no findings at or above the selected severity |
1 |
One or more findings at or above the selected severity |
2 |
Operational or usage error, such as a missing path or unwritable report file |
if ai-guard scan . --min-severity HIGH --quiet; then
echo "AI configuration passed security review"
else
echo "AI configuration requires review" >&2
exit 1
fi
Severity model
| Severity | Meaning | Typical examples |
|---|---|---|
CRITICAL |
Immediate path to host compromise or credential theft | Filesystem root mount, Docker socket, AWS/Stripe key, private key, unauthenticated wildcard listener |
HIGH |
Dangerous capability that should block most deployments | Raw shell execution, remote endpoint without auth, auto-approval, SSH credential path, provider API key |
MEDIUM |
Requires review or hardening | Path traversal, unpinned package execution, JWT exposure, weak approval settings |
LOW |
Hygiene and defense-in-depth issues | Reserved for lower-confidence checks |
INFO |
Contextual observations | Reserved for informational checks |
Findings are sorted by severity, then file and line. The process exit code is based on the findings that survive --min-severity.
Rules reference
AI-Guard ships with 27 security rules plus a parse-diagnostic rule.
MCP server security
| Rule | Severity | Detects |
|---|---|---|
MCP001 |
High/Critical | Raw shell interpreters, inline code execution, and privilege-escalation commands in MCP servers |
MCP002 |
High/Critical | Remote endpoints without declared authentication, plaintext HTTP/WS transport, and wildcard listeners |
MCP003 |
High/Medium | MCP auto-approval of dangerous tools or blanket * approval |
MCP004 |
Critical/High | Privileged containers, host mounts, Docker socket access, and sandbox-disabling flags |
MCP005 |
Medium | Unpinned npx, pnpx, bunx, uvx, or pipx package execution |
Secrets and credentials
| Rule | Severity | Detects |
|---|---|---|
SEC001 |
High | OpenAI API keys |
SEC002 |
High | Anthropic API keys |
SEC003 |
High | Hugging Face access tokens |
SEC004 |
Critical | AWS access key IDs and secret access keys |
SEC005 |
High | GitHub and GitLab tokens |
SEC006 |
High | Google API keys |
SEC007 |
High | Slack bot, app, and user tokens |
SEC008 |
Critical | PEM and PGP private key blocks |
SEC009 |
High/Medium | High-entropy values assigned to credential-like keys |
SEC010 |
Medium | JSON Web Tokens |
SEC011 |
Critical | Stripe secret and restricted keys |
Secret evidence is always redacted. Reports include a short fingerprint and metadata such as token type and entropy, never the full value.
Filesystem and path exposure
| Rule | Severity | Detects |
|---|---|---|
PATH001 |
Critical | Filesystem root as a path, mount, workspace, or tool argument |
PATH002 |
High/Critical | Sensitive system paths such as /etc, /proc, /sys, /boot, and /var data directories |
PATH003 |
Critical | SSH, cloud, container, Kubernetes, and GPG credential directories, or an entire home directory |
PATH004 |
Medium | Parent-directory traversal sequences |
PATH005 |
High | Windows drive roots, C:\Windows, and Windows credential directories |
PATH006 |
Critical | Docker daemon socket exposure |
Prompt and instruction heuristics
| Rule | Severity | Detects |
|---|---|---|
PROMPT001 |
High | Instruction-override language, jailbreak personas, and system-prompt disclosure requests |
PROMPT002 |
Critical | Secret exfiltration, remote script execution, encoded payload execution, reverse shells, and destructive commands |
PROMPT003 |
High | Requests to hide activity, suppress warnings, disable safeguards, or avoid auditing |
PROMPT004 |
High | Invisible and bidirectional Unicode control characters |
PROMPT005 |
Medium | Automatic approval, confirmation bypass, privileged commands, and requests for unrestricted access |
Diagnostics
| Rule | Severity | Detects |
|---|---|---|
AI-GUARD-000 |
Medium | Malformed, unreadable, non-UTF-8, or oversized configuration files |
# Show evidence, remediation, and references
ai-guard scan . --verbose
# List every rule from the installed version
ai-guard rules
Supported files and detection scope
AI-Guard parses:
- JSON and JSON with comments/trailing commas (
.json,.jsonc,.json5) - YAML (
.yaml,.yml) - TOML (
.toml) - Markdown instructions (
.md,.markdown,.mdx) - Text and prompt files (
.txt,.prompt,.system,.instructions) - Dotenv files (
.env,.env.local, and similar)
It recognizes common agent layout shapes, including top-level mcpServers, servers, and mcp maps used by Claude Desktop/Code, Cline, VS Code, OpenCode, and compatible clients. MCP servers may use string or list commands, environment blocks, headers, URLs, transports, and auto-approval lists.
Directory scans skip common irrelevant or vendored locations such as .git, .hg, .svn, node_modules, .venv, venv, __pycache__, .tox, .mypy_cache, .pytest_cache, .ruff_cache, dist, build, and site-packages. Agent directories such as .claude, .vscode, and .github are not skipped.
Explicit file targets are always scanned, even with an unfamiliar suffix. Individual files larger than 5 MiB are skipped. Scans are capped at 25,000 discovered files.
Output formats
Table
The default, human-readable Rich table with severity colors, summary panel, optional progress bar, and --verbose detail panels.
JSON
Stable, versioned JSON with the tool version, target, timestamp, summary, findings, rule catalog, parse errors, and internal rule warnings.
{
"schema_version": "1.0",
"tool": { "name": "KynSec AI Guard", "version": "0.1.0" },
"summary": {
"files_scanned": 3,
"findings_total": 4,
"findings_reported": 4,
"by_severity": { "critical": 1, "high": 2, "medium": 1 }
},
"findings": []
}
SARIF v2.1.0
SARIF output is compatible with GitHub code scanning and other SARIF consumers. It includes rule metadata, security severities, stable fingerprints, physical locations, and parse/rule execution notifications.
ai-guard scan . --format sarif --output ai-guard.sarif
GitHub Actions + SARIF
Upload findings to the repository Security tab:
name: KynSec AI Guard
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
security-events: write
jobs:
ai-guard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
with:
python-version: "3.12"
- name: Install AI-Guard
run: python -m pip install git+https://github.com/KynSec/kynsec-ai-guard.git
- name: Generate SARIF
run: ai-guard scan . --format sarif --output ai-guard.sarif --min-severity MEDIUM
continue-on-error: true
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: ai-guard.sarif
Keep the SARIF upload step separate from the gating step so results are published even when the scan fails the build.
Architecture
ai-guard scan <path>
|
+-----------v------------+
| core/parser.py |
| JSON / JSONC / YAML |
| TOML / dotenv / text |
+-----------+------------+
|
+-----------v------------+
| core/engine.py |
| discovery, orchestration,
| dedupe, severity filter,
| progress, diagnostics |
+-----------+------------+
|
+---------------------+---------------------+
| | |
+---------v---------+ +---------v---------+ +---------v---------+
| MCP security | | Secrets + entropy | | Path exposure |
| Prompt heuristics | | Rule registry | | Shared finding |
+---------+---------+ +---------+---------+ +---------+---------+
| | |
+---------------------+---------------------+
|
+-----------v------------+
| core/reporter.py |
| Rich table |
| JSON / SARIF 2.1.0 |
+------------------------+
Repository layout
ai_guard/
├── __init__.py # Package version
├── cli.py # Typer + Rich CLI, exit codes, progress
├── core/
│ ├── engine.py # Discovery, orchestration, aggregation
│ ├── parser.py # Robust JSON/YAML/TOML/dotenv parsing
│ └── reporter.py # Table, JSON, and SARIF reports
└── rules/
├── base.py # Rule ABC, Finding and Severity models
├── mcp_security.py # MCP capability and network analysis
├── secrets_leak.py # Regex + Shannon entropy credential detection
├── path_Traversal.py # Host filesystem and credential path exposure
└── prompt_injection.py # Prompt and instruction heuristics
tests/
├── test_parser.py
├── test_engine.py
├── test_rules.py
└── test_cli.py
.github/workflows/ci.yml
Design principles
- Read-only: AI-Guard never modifies scanned files and never executes agent configuration.
- Offline by default: No telemetry, analytics, or remote API calls.
- Fail-soft parsing: A malformed file produces a diagnostic finding; the rest of the scan continues.
- Redaction by default: Credential values are masked before they reach terminal, JSON, or SARIF output.
- Evidence with location: Findings carry file paths and line numbers whenever the format permits.
- Deterministic output: Findings are sorted and deduplicated for stable CI diffs.
- Pluggable rules: Every rule implements a small abstract interface and declares machine-readable metadata.
Development
git clone https://github.com/KynSec/kynsec-ai-guard.git
cd kynsec-ai-guard
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
# Run the test suite
pytest
# Coverage
pytest --cov=ai_guard --cov-report=term-missing
# Lint and formatting
ruff check .
ruff format --check .
CI runs the test suite on Python 3.10, 3.11, and 3.12, checks formatting, and lints with Ruff.
Releasing
KynSec AI Guard publishes to PyPI through GitHub Actions and PyPI Trusted Publishing. Configure a PyPI trusted publisher for kynsec-ai-guard with workflow release.yml and environment pypi, then bump __version__, commit, and push a vX.Y.Z tag:
git tag v0.1.0
git push origin v0.1.0
The release workflow builds the wheel and source distribution, validates them with twine, and publishes them without storing a PyPI token.
Adding a rule
- Create or extend a rule module in
ai_guard/rules/. - Subclass
Ruleand implementscan(document) -> list[Finding]. - Declare metadata for every emitted rule ID in the rule's
catalog. - Register the rule in
ai_guard/rules/__init__.py. - Add positive, negative, and false-positive tests in
tests/test_rules.py. - Run
pytestandruff check ..
Rules must never raise for malformed input and must not include unredacted secrets in findings, evidence, or metadata.
Contributing
Contributions are welcome, especially new detection patterns, additional MCP client layouts, false-positive reductions, and SARIF interoperability fixes.
- Fork the repository and create a focused branch.
- Add tests before or alongside the implementation.
- Keep public behavior documented in the README and rule catalog.
- Run
pytest,ruff check ., andruff format --check .. - Open a pull request describing the threat model and verification steps.
For security issues in AI-Guard itself, please use the repository's private vulnerability reporting instead of a public issue.
Limitations
AI-Guard is a static heuristic analyzer. It reduces risk; it does not prove an agent configuration is safe.
- Heuristics can produce false positives, especially in security documentation and test fixtures.
- Prompt analysis cannot fully model model behavior or multi-turn attacks.
- A clean scan does not replace a sandbox, least-privilege OS accounts, runtime monitoring, or secret rotation.
- MCP configuration layouts evolve quickly; please report new shapes so detection can be extended.
Acknowledgements
KynSec AI Guard's rule design is informed by the OWASP Top 10 for LLM Applications, MITRE CWE, SARIF, and the excellent Python open-source ecosystem: Typer, Rich, Pydantic, PyYAML, and pytest.
License
MIT License. See LICENSE.
Built by KynSec.
Metadata
Release files for kynsec-ai-guard 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kynsec_ai_guard-0.1.0.tar.gz | 55.8 kB | With provenance | Details for kynsec_ai_guard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kynsec_ai_guard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for kynsec_ai_guard-0.1.0-py3-none-any.whl |
Total release size: 101.8 kB
Release files / kynsec_ai_guard-0.1.0.tar.gz
| Download URL | kynsec_ai_guard-0.1.0.tar.gz |
|---|---|
| Size | 55.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c3a53cd9fdb1e9e80ae9dc8557bd1957fb3aeb7b818a96d7d294da55f0439738
|
|
BLAKE2b-256 checksum How to use checksums |
e0e99261ab3202dd309c5ab21e473012c0e399237687ba556d295d3197330910
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / kynsec_ai_guard-0.1.0-py3-none-any.whl
| Download URL | kynsec_ai_guard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 46.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd050a6839b01a5b160e2a476abc67053ec961a341f8aecd22c2b864fa307ad1
|
|
BLAKE2b-256 checksum How to use checksums |
7271a528d789e3651b8583bf72b1f9842a6c39852042b6db9f8bdb51eb37e0d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for kynsec-ai-guard 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kynsec_ai_guard-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.