Blazing-fast security scanner for AI-generated code vulnerabilities

Quick Start • Features • Documentation • Contributing • Demo

---

🎯 What is AIShield?

AIShield is a Rust-based security scanner that detects vulnerabilities commonly introduced by AI coding assistants like Copilot, ChatGPT, and Claude. It finds high-risk patterns that look plausible in code review but are unsafe in production.

The Problem: AI tools boost developer velocity but reproduce insecure examples from public training data — timing-unsafe auth checks, weak crypto defaults, SQL injection patterns, and dangerous misconfigurations.

The Solution: AIShield provides a dedicated guardrail layer with AI-likelihood scoring, catching these issues before they reach production.

---

⚡ Quick Start

# Clone and build
git clone https://github.com/mackeh/AIShield.git
cd AIShield
cargo build --release

# Scan your project
cargo run -p aishield-cli -- scan /path/to/your/project

# Machine-readable output for CI
cargo run -p aishield-cli -- scan . --format json --output aishield.json

# Interactive fix mode
cargo run -p aishield-cli -- fix . --interactive

# Optional: start full analytics stack (Postgres + API + smoke check)
./scripts/start-analytics-stack.sh

First scan in < 2 minutes ✨

---

🚀 Key Features

🔍 AI-Focused Detection

• 237 rules across 13 languages detecting AI-prone vulnerability patterns
• AI confidence scoring: Estimates likelihood each finding came from AI autocomplete
• Context-aware risk scoring: Prioritizes findings based on severity and exploitability

🎯 Multi-Language Support

• Application languages: Python, JavaScript, Go, Rust, Java, C#, Ruby, PHP, Kotlin, Swift
• Infrastructure: Terraform/HCL, Kubernetes YAML, Dockerfiles

🛠️ Developer Workflow

• Fast scans: Sub-2-second scans on most codebases
• Interactive fix mode: TUI for reviewing and applying remediations
• Multiple output formats: JSON, SARIF, GitHub annotations, plain text
• Deduplication: Normalized and strict modes for clean CI/CD integration

🔌 Ecosystem Integration

• CI/CD: GitHub Actions, GitLab CI, Bitbucket, CircleCI, Jenkins templates
• Editors: VS Code extension with hover cards, quick fixes, and diagnostics panel
• Hooks: Pre-commit integration for local scanning
• SAST Bridge: Integrates with Semgrep, Bandit, ESLint for comprehensive coverage

📊 Analytics Dashboard

• Local web dashboard for tracking vulnerability trends
• Scan history with severity breakdown
• AI-generated code detection metrics

---

🏗️ Architecture

AIShield combines multiple detection strategies:

• Pattern matching for known vulnerability signatures
• AI classifier (heuristic + optional ONNX model) for detecting AI-generated patterns
• Cross-file analysis for context-aware auth route detection
• SAST bridge for integrating third-party security tools

---

💡 Real-World Examples

Example 1: Timing Attack in Auth

AI-generated code (insecure):

def verify_token(user_token, valid_token):
    if user_token == valid_token:  # ❌ Timing attack vulnerability
        return True
    return False

AIShield detection:

[HIGH] Timing-unsafe token comparison
  File: auth.py:42
  Rule: AISHIELD-PY-AUTH-002
  AI Confidence: 89%
  Fix: Use secrets.compare_digest() for constant-time comparison

Example 2: Weak Crypto from Autocomplete

AI-generated code (insecure):

const crypto = require("crypto");
const hash = crypto.createHash("md5").update(data).digest("hex"); // ❌ Weak hash

AIShield detection:

[HIGH] Weak hash algorithm (MD5)
  File: utils.js:15
  Rule: AISHIELD-JS-CRYPTO-001
  AI Confidence: 92%
  Fix: Use SHA-256 or SHA-3 for cryptographic hashing

Example 3: SQL Injection

AI-generated code (insecure):

query := "SELECT * FROM users WHERE id = " + userID  // ❌ SQL injection
rows, err := db.Query(query)

AIShield detection:

[CRITICAL] SQL injection via string concatenation
  File: database.go:88
  Rule: AISHIELD-GO-INJECT-001
  AI Confidence: 87%
  Fix: Use parameterized queries: db.Query("SELECT * FROM users WHERE id = ?", userID)

---

📊 Performance Benchmarks

Project Size	Files	Scan Time	Throughput
Small	50	0.3s	167 files/sec
Medium	500	1.2s	417 files/sec
Large	5000	8.5s	588 files/sec

Benchmarks on Intel i7-12700K, scanning real-world projects

---

🆚 Comparison with Alternatives

Feature	AIShield	Semgrep	Bandit	CodeQL
AI-specific patterns	✅	❌	❌	❌
AI confidence scoring	✅	❌	❌	❌
Sub-2s scans	✅	⚠️	✅	❌
Multi-language	✅ (13)	✅ (30+)	❌ (Python)	✅ (10+)
Interactive fix mode	✅	❌	❌	❌
Local-first	✅	✅	✅	❌
Cross-file analysis	✅	✅	❌	✅

AIShield is complementary: Use alongside general-purpose SAST tools via the --bridge flag for comprehensive coverage.

---

🎬 60-Second Demo

# From repository root
cargo run -p aishield-cli -- scan tests/fixtures

Example output:

AIShield scan complete: 142 findings across 13 files (237 rules loaded)
Summary: critical=8 high=98 medium=28 low=8 info=0
AI-Generated (estimated): 41 of 142 findings (29%)

Top findings:
  [CRITICAL] SQL injection via string concatenation (vulnerable.py:23)
  [CRITICAL] Hardcoded API key in source (config.js:7)
  [HIGH] Timing-unsafe password comparison (auth.go:45)
  [HIGH] Weak hash algorithm MD5 (crypto.py:12)

Run full demo suite:

bash demos/run.sh

See demos/README.md for detailed walkthrough.

---

📚 Documentation

Comprehensive documentation available in VitePress format:

npm install
npm run docs:dev  # Local preview at http://localhost:5173

Key guides:

• 📖 Getting Started
• 🛠️ CLI Reference
• 🎨 VS Code Extension
• 🔧 Configuration
• 📝 Writing Rules
• 🚀 GitHub Actions CI
• 🤝 Contributing Guide

---

🔧 Installation & Setup

Prerequisites

• Rust 1.75+ stable toolchain
• Node.js 20+ (for docs and dashboard)
• Optional: semgrep, bandit, eslint for SAST bridge

Build from Source

git clone https://github.com/mackeh/AIShield.git
cd AIShield
cargo build --release

# Optional: Install CLI globally
cargo install --path crates/aishield-cli

Scaffold Integrations

# Generate CI/CD config files
cargo run -p aishield-cli -- init --templates all

# Supported: github-actions, gitlab-ci, bitbucket-pipelines, circleci, jenkins, vscode, pre-commit

---

🎯 Core Commands

Command	Description
scan	Run security analysis with filters and output formats
fix	Print or apply remediations (--write, --dry-run, --interactive)
bench	Benchmark scanner performance
stats	Summarize scan history analytics
analytics	Interact with analytics API (migrate-history, summary)
config	Manage analytics config values (set, get, show)
init	Scaffold config and CI templates
create-rule	Generate new YAML detection rule from template
hook install	Install pre-commit scanning hook

Full reference: docs/cli.md

Analytics API snapshot with threshold gates:

cargo run -p aishield-cli -- analytics summary \
  --days 30 \
  --probes 3 \
  --max-error-rate-pct 1 \
  --max-summary-p95-ms 1500 \
  --max-compliance-p95-ms 1500 \
  --min-coverage-pct 70 \
  --fail-on-threshold

---

🛡️ Known Limitations

Pattern Matching: Uses regex and string-based detection (not AST-based). Adequate for AI vulnerability patterns with excellent performance.

Analytics: File-based analytics works out of the box (.aishield-history.log). Optional API mode with PostgreSQL/TimescaleDB is available for org/team/repo dashboards and trend reporting.

SAST Bridge: Requires manual installation of external tools (semgrep, bandit, eslint). Enable with --bridge all.

See ARCHITECTURAL_DECISIONS.md for detailed rationale.

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. 📖 Read CONTRIBUTING.md
2. 🎯 Find a good first issue
3. 🔧 Follow our development setup guide
4. ✍️ Try writing your first rule
5. 🚀 Submit a PR using our PR template

Popular contribution areas:

• 📝 Adding detection rules for new vulnerability patterns
• 🌍 Expanding language coverage
• 📚 Improving documentation and examples
• 🐛 Fixing bugs and improving performance

---

❓ FAQ

How is this different from Semgrep/Bandit/ESLint?

AIShield focuses on AI-generated code patterns with confidence scoring. Traditional SAST tools flag all matches; AIShield identifies which findings likely came from AI autocomplete. You can use AIShield alongside traditional tools via --bridge.

Why is my scan slow?

Common causes:

• Large binary files (use .aishield-ignore)
• --cross-file flag (enables expensive auth-route analysis)
• SAST bridge with slow external tools

Run cargo run -p aishield-cli -- bench . to identify bottlenecks.

Can I use AIShield in CI/CD?

Yes! Use --format json or --format sarif for machine-readable output. We provide templates for GitHub Actions, GitLab CI, and more. Run cargo run -p aishield-cli -- init --templates github-actions.

How accurate is AI confidence scoring?

Heuristic mode: ~75-85% accuracy based on pattern characteristics ONNX mode: ~85-92% accuracy with trained model

Scoring helps prioritize review, but all findings should be evaluated regardless of AI confidence.

Can I add custom rules?

Absolutely! Create YAML files in rules/<language>/<category>/. See docs/rules-authoring.md and docs/guides/writing-your-first-rule.md.

---

🐛 Troubleshooting

Scan produces no findings on known vulnerable code

Solution: Check if files are being scanned:

cargo run -p aishield-cli -- scan . --format json | jq '.files_scanned'

Add ignored extensions to config or verify .aishield-ignore.

--bridge reports tools not found

Solution: Install SAST tools manually:

# macOS
brew install semgrep
pip install bandit
npm install -g eslint

# Linux
pip install semgrep bandit
npm install -g eslint

ONNX model not loading

Solution: Build with ONNX feature:

cargo build --release --features onnx

More troubleshooting: docs/troubleshooting.md (coming soon)

---

📋 Project Status

Current Version: 0.4.0

Phase Completion:

• ✅ Phase 1 (Foundation): Complete
• ✅ Phase 2 (Intelligence): Complete
• ✅ Phase 3 (Platform/Ecosystem Core): Complete
• 🚧 Phase 4 (Ecosystem Expansion): In Progress

Recent Additions:

• 237 rules across 13 languages (all application languages at 20 rules, IaC at 15 each)
• Production-grade CI templates for GitHub Actions, GitLab CI, Bitbucket, CircleCI, Jenkins
• C#/Ruby/PHP rulepacks expanded to full 20-rule coverage
• IaC rules expanded: Terraform 15, Kubernetes 15, Dockerfile 15
• Analytics API + dashboard with compliance reporting and threshold gating
• VS Code extension GA (security lens, quick fixes, telemetry)
• ONNX classifier model path with heuristic fallback

Tracking docs: PROJECT_STATUS.md | WEEK5_TESTING.md | docs/roadmap.md

---

🔒 Security

For vulnerability disclosure, follow SECURITY.md.

Do not open public issues for undisclosed security vulnerabilities.

---

📜 License

MIT License - see LICENSE for details.

---

🌟 Acknowledgments

Built with ❤️ by the security community.

Special thanks to contributors and the open-source security tools ecosystem.

---

Star ⭐ this repo if AIShield helps secure your AI-generated code!

Report Bug • Request Feature • Discussions