eslint-plugin-ai-guard

eslint-plugin-ai-guard

🛡️ GitHub-native guardrails for AI-generated code.

What is ai-guard?

ai-guard is an ESLint plugin and GitHub Action that catches reliability and security bugs specific to AI-generated code — the patterns Copilot, Claude, Cursor, and Gemini consistently get wrong.

It integrates directly into GitHub pull request workflows: blocking dangerous merges, generating SARIF reports for GitHub Code Scanning, and posting inline PR annotations at the exact line where the bug lives.

# Scan immediately — no config needed
npx ai-guard run

# PR-aware changed-only scan with GitHub Advanced Security
npx ai-guard changed --sarif --sarif-output results.sarif

The Problem

AI coding assistants generate code that looks correct but isn't. The patterns they get wrong are consistent, predictable, and existing linters don't catch them:

ai-guard is purpose-built to catch what AI tools consistently get wrong — before those bugs reach production.

Install

npm install --save-dev eslint-plugin-ai-guard

Requirements: Node.js ≥ 18 · ESLint ≥ 8

Quick Start

# Zero-config project scan
npx ai-guard run

# Security-focused scan
npx ai-guard run --security

# Strict mode — all 18 rules at error
npx ai-guard run --strict

# Scan only changed files (PR-aware)
npx ai-guard changed --pr

No configuration required. ai-guard ships with a production-tuned recommended preset.

GitHub Actions Integration

Drop this into any repository to get PR validation, SARIF-based Code Scanning, and GitHub Advanced Security integration in under 5 minutes:

# .github/workflows/ai-guard.yml
name: AI Guard

on: [pull_request]

permissions:
  security-events: write
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for changed-file detection

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Scan changed files
        run: |
          npx ai-guard changed \
            --pr \
            --strict \
            --sarif \
            --sarif-output ai-guard-results.sarif \
            --fail-on high

      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ai-guard-results.sarif
          category: ai-guard

This produces:

• ✅ Inline PR annotations at the exact line of each finding
• ✅ GitHub Advanced Security summary ("17 new alerts including 3 high severity")
• ✅ Persistent alerts in Security → Code scanning
• ✅ PR status check that blocks merges on high-severity findings

Inline PR Annotations

GitHub Advanced Security Summary

GitHub Code Scanning Alerts

See docs/github-actions.md for the complete workflow reference including full-scan mode, baseline mode, and SARIF debugging.

CLI Commands

Fail Strategies

--fail-on errors   # Fail on any error-level finding (default)
--fail-on high     # Fail only on high-severity findings
--fail-on none     # Never fail — always continue
--max-warnings 0   # Fail on any warning

Example Output

  AI GUARD

  Files scanned:  142  ·  Issues in:  7 files  ·  Duration:  312ms  ·  Preset:  strict

  ── Summary by Category ──

  🔴  Security            3 errors
  🟠  Reliability         2 errors
  🟡  Async Stability     2 warnings

  Total: 5 errors · 2 warnings

  ── By Rule ──
    • no-hardcoded-secret: 3
    • no-empty-catch: 2
    • no-floating-promise: 2

  ── Next Steps ──
  ℹ  Run ai-guard baseline to save these issues and track only new ones
  ℹ  Run ai-guard report   to generate a shareable HTML report

Rules

🔴 Security

🟠 Reliability

🟡 Async Stability

🔵 AI Patterns

*Enabled at error in the strict preset.

Full rule documentation: docs/rules/

Presets

ESLint Flat Config

// eslint.config.mjs
import aiGuard from 'eslint-plugin-ai-guard';

export default [
  {
    plugins: { 'ai-guard': aiGuard },
    rules: { ...aiGuard.configs.recommended.rules },
  },
];

AI Agent Integration

Generate instruction files so Claude Code, Cursor, and GitHub Copilot automatically avoid the 18 most common AI-generated anti-patterns at generation time:

npx ai-guard init-context

This writes:

• CLAUDE.md — loaded automatically by Claude Code
• .cursorrules — loaded automatically by Cursor
• .github/copilot-instructions.md — loaded automatically by GitHub Copilot

Your AI tools will avoid these patterns before you even run the linter.

See docs/ai-agents.md for the complete integration guide.

Real-World Example

// ❌ Typical AI-generated code — 4 issues in one function
async function processUserOrders(userId: string) {
  const apiKey = 'sk-prod-1234567890abcdef';  // no-hardcoded-secret

  const orders = await db.query(
    'SELECT * FROM orders WHERE id = ' + userId  // no-sql-string-concat
  );

  for (const order of orders) {
    await sendEmail(order.email);  // no-await-in-loop
  }

  updateAnalytics(userId);  // no-floating-promise
}

// ✅ After ai-guard fixes
async function processUserOrders(userId: string) {
  const apiKey = process.env.API_KEY;

  const orders = await db.query(
    'SELECT * FROM orders WHERE id = $1', [userId]
  );

  await Promise.all(orders.map(async (order) => sendEmail(order.email)));

  void updateAnalytics(userId);
}

Autofix Support

npx eslint src --fix

Philosophy

• Precision over recall — we'd rather miss a bug than create noise
• Low false positives — a rule that fires on valid code goes to warn or gets disabled
• Gradual adoption — recommended is safe for day-one; strict is opt-in
• Self-validating — ai-guard scans its own source in CI with the strict preset
• GitHub-native — SARIF output, Code Scanning, PR annotations are first-class features

Development

git clone https://github.com/ai-guard-dev/eslint-plugin-ai-guard.git
cd eslint-plugin-ai-guard
npm install
npm run test         # 678 tests across 39 test files
npm run build        # Build CJS + ESM bundles
npm run typecheck    # TypeScript strict check
npm run lint:self    # Scan own source with ai-guard
npm run lint:full    # Strict scan of src/ + cli/

See CONTRIBUTING.md for the full development guide.

Documentation

FAQ

Troubleshooting

License

MIT — free forever. No rules behind a paywall.

Built to make AI-assisted development reliable and trustworthy. ⚡