PyGuard 🛡️

AST-based static security analysis tool for Python — with AI-powered explanations.

PyGuard scans Python source code for security vulnerabilities without executing it. It combines deterministic rule-based detection (Shannon entropy, token pattern matching, AST traversal) with optional AI-assisted remediation suggestions via Google Gemini.

Features

• 🔍 AST-based analysis — no code execution, no false runtime side effects
• 🧠 Shannon entropy detection — catches high-entropy strings that look like secrets even without obvious variable names
• 🎯 Token pattern matching — detects Stripe keys, GitHub tokens, AWS access keys, JWTs
• 🔌 Modular rule engine — add custom rules as standalone .py files, no core changes needed
• 🤖 AI explanations — optional Gemini-powered remediation suggestions per finding
• 🌐 Multi-language support — Python (AST) + generic secret/injection scanning for other languages
• 💻 VS Code integration — via vscode_bridge.py
• 📄 JSON and human-readable output

Detected Vulnerability Classes

Installation

git clone https://github.com/eenverylmz/PyGuard.git
cd PyGuard
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Set up your .env file for AI features (optional):

GEMINI_API_KEY=your_api_key_here

Usage

# Basic scan
python cli.py path/to/your_file.py

# JSON output
python cli.py path/to/your_file.py --json

# With AI explanations
python cli.py path/to/your_file.py --ai

Writing Custom Rules

Rules are standalone Python files in the rules/ directory. Each file exports a check(node) or check(node, ctx) function that receives an AST node and returns a list of Vulnerability objects.

# rules/my_custom_rule.py
import ast
from core.result import Vulnerability

def check(node, ctx=None):
    findings = []
    # your logic here
    return findings

Drop the file in rules/ — PyGuard picks it up automatically. No registration needed.

Project Structure

PyGuard/
├── ai/               # Gemini AI explainer
├── core/             # AST parser, analyzer, scanner, result model
├── engine/           # Rule engine (dynamic rule loading + AST walking)
├── rules/            # Individual vulnerability check modules
├── output/           # Output formatters (human-readable, JSON)
├── samples/          # Test files for scanning
├── src/              # Additional source utilities
├── cli.py            # CLI entry point
└── vscode_bridge.py  # VS Code extension bridge

How It Works

1. Source code is parsed into an AST via core/AST_parser.py
2. Import aliases are resolved (e.g. import subprocess as sp → tracked)
3. The rule engine walks every AST node and applies all loaded rules
4. Each matching rule returns a Vulnerability with location, severity, CWE, and code snippet
5. Results are formatted and optionally enriched with AI explanations

Example Output

[HIGH] PYG001 - Hardcoded Credential
  File: samples/test.py, Line 4
  Code: api_key = "sk_live_abc123xyz..."
  CWE: CWE-798
  Fix: Move credentials to environment variables using os.environ or a .env file.

[CRITICAL] PYG005 - Insecure Pickle Deserialization
  File: samples/test.py, Line 12
  Code: data = pickle.load(f)
  CWE: CWE-502
  Fix: Use safer alternatives like json or msgpack for deserialization.

Requirements

• Python 3.10+
• google-genai (optional, for AI explanations)
• python-dotenv

Disclaimer

PyGuard is intended for educational and defensive security purposes only. Use it to analyze code you own or have permission to scan.

Author

Enver Yılmaz LinkedIn · GitHub