eslint-plugin-ai-guard

v1.3.1

Published

17 hours ago

GitHub-native guardrails for AI-generated code. ESLint plugin and GitHub Action for detecting async reliability issues, floating promises, empty catch blocks, hardcoded secrets, SQL injection, and more. SARIF-based GitHub Code Scanning integration with PR

What is AI Guard?

AI Guard (eslint-plugin-ai-guard) is a deterministic ESLint plugin, CLI, and GitHub Action engineered to detect reliability bugs, async hazards, security vulnerabilities, and code-scaffolding defects frequently introduced during AI-assisted development (GitHub Copilot, Cursor, Claude Code, Gemini Code Assist, etc.).

AI Guard analyzes Abstract Syntax Trees (AST) using ESLint's native engine. It runs locally in your editor, in your terminal via the zero-config CLI, and in your CI/CD pipelines via native SARIF 2.1.0 integration with GitHub Code Scanning.

What AI Guard is NOT

[!IMPORTANT]
AI Guard is NOT an AI detector. It does not attempt to predict whether code was authored by an LLM or a human.
AI Guard detects dangerous or fragile code patterns that LLMs repeatedly introduce due to incomplete context, hallucinated patterns, or probabilistic generation.
AI Guard does NOT replace ESLint. It extends ESLint with 18 specialized, high-impact rules that core ESLint and standard configurations omit.

Why AI Guard?

AI coding assistants write code at remarkable velocity, but generated code repeatedly suffers from predictable reliability and security anti-patterns that conventional linters miss:

| Pattern | Why AI Assistants Generate It | Real-World Impact | | :--- | :--- | :--- | | Floating Promises | Omits await, return, or .catch() on async calls | Unhandled promise rejections, silent failures in background jobs | | Async Array Iteration | Passes async callbacks into array.map() or .filter() | Returns unawaited Promise[] instead of resolved values | | Sequential Awaits in Loops | Loops over items with sequential await | Significant latency bottlenecks; blocks event loop execution | | Empty Catch Blocks | Inserts generic try { ... } catch (e) {} blocks | Swallows production exceptions silently without telemetry | | Hardcoded Secrets | Injects placeholder or real API keys/tokens | Credential leakage in version control and deployment bundles | | Dynamic eval() | Generates dynamic function compilation | Arbitrary code execution and code injection | | Raw SQL Concatenation | Concatenates query strings with variables | Severe SQL injection vulnerabilities | | Unsafe Deserialization | Calls JSON.parse(req.body) directly without schema checks | Denial of service and unhandled runtime crashes | | Missing Route Auth & Authz | Emits boilerplate endpoints without auth middleware | Unprotected API endpoints and IDOR privilege escalations | | Dead Branches & Scaffolding | Leaves if (true) or conflicting conditions from prompt iterations | Bloated bundles and dead code paths |

AI Guard provides an instantaneous, deterministic feedback loop that catches these issues before they reach pull requests or production.

Architecture & Workflow

flowchart TD
    subgraph Dev["1. Development & Prompt Phase"]
        A["Developer + AI Coding Assistant\n(Copilot, Cursor, Claude Code)"] --> B["JavaScript / TypeScript Code"]
    end

    subgraph ShiftLeft["Shift Left — Context Injection"]
        SL["npx ai-guard init-context"] -.-> CTX["CLAUDE.md\n.cursorrules\ncopilot-instructions.md"]
        CTX -.-> A
    end

    subgraph Analysis["2. Deterministic AST Analysis"]
        B --> C["ESLint Parser\n(espree / @typescript-eslint/parser)"]
        C --> D["AST Representation"]
        D --> E["AI Guard Rules Engine\n(18 Deterministic Rules)"]
    end

    subgraph Tiers["3. Classification & Presets"]
        E --> F{"Active Preset\n(recommended | strict | security)"}
        F --> G["Confidence Tiering & AST Filtering"]
    end

    subgraph Outputs["4. Output & Remediation"]
        G --> H["Local CLI Scanning\n(ai-guard run / changed)"]
        G --> I["Autofix Remediation\n(eslint --fix)"]
        G --> J["HTML Dashboard\n(ai-guard report)"]
        G --> K["SARIF 2.1.0 Artifact\n(ai-guard --sarif)"]
    end

    subgraph CI["5. GitHub Pull Request & CI/CD"]
        K --> L["GitHub Action\nai-guard-dev/eslint-plugin-ai-guard@v1"]
        L --> M["GitHub Code Scanning Alerts"]
        L --> N["Inline PR Code Annotations"]
        L --> O["PR Status Check (Blocks Merge)"]
    end

Rules Catalog

AI Guard includes 18 deterministic rules divided into four specialized categories. Every rule is engineered with low false-positive heuristics and validated against real-world production codebases:

🔴 Security (6 Rules)

🟠 Reliability (4 Rules)

| Rule | Recommended | What It Catches | Fixable? | | :--- | :---: | :--- | :---: | | no-empty-catch | error | Empty catch (e) {} blocks that silently swallow exceptions without logging or rethrowing. | Yes (inserts /* TODO: handle error */) | | no-broad-exception | warn | Catching broad exception types like catch (e: any) that mask system faults and typing. | No | | no-catch-log-rethrow | off* | Catch blocks that only log to console and rethrow without adding context or diagnostic info. | No | | no-catch-without-use | off* | Caught error variables that are declared in catch parameters but never referenced. | No |

🟡 Async Stability (5 Rules)

🔵 AI Patterns (3 Rules)

| Rule | Recommended | What It Catches | Fixable? | | :--- | :---: | :--- | :---: | | no-dead-branch | warn | Unreachable or tautological branches (if (true), if (false), x && !x) left behind from LLM code synthesis. | No | | no-duplicate-logic-block | off* | Consecutive duplicate code blocks or repeated conditional branches duplicated during AI edits. | No | | no-console-in-handler | off* | Unstructured console.log statements left in HTTP route handlers instead of production loggers. | No |

* Enabled at error level in the strict preset.

Presets

AI Guard exports four official configurations ready for flat config or legacy setups:

| Preset | Description | Configuration Focus | | :--- | :--- | :--- | | recommended | Default. Balanced adoption preset. Enables 4 high-confidence critical rules at error, 9 context-sensitive rules at warn, and disables 5 noisy rules. Zero noise on day one. | Production codebases, new teams | | strict | Enforces all 18 rules at error. Designed for zero-tolerance CI gates, high-assurance software, and mature teams. | Strict CI/CD quality gates | | security | Focuses exclusively on the 6 security rules (no-hardcoded-secret, no-eval-dynamic, no-sql-string-concat at error; remainder at warn). | AppSec auditing & security scans | | agent | 5 high-signal rules at error. Optimized for AI-agent editing workflows where lint feedback runs immediately after each file edit (e.g., PostToolUse hooks). | Claude Code, Cursor, real-time agent loops |

Quick Start & Installation

Install the package as a development dependency using your package manager:

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

# pnpm
pnpm add -D eslint-plugin-ai-guard

# yarn
yarn add -D eslint-plugin-ai-guard

# bun
bun add -d eslint-plugin-ai-guard

Requirements

Node.js: >= 20.0.0
ESLint: >= 8.0.0 (Supports both Flat Config and legacy configs)
TypeScript (optional): @typescript-eslint/parser >= 6.0.0 for TypeScript AST parsing

ESLint Configuration

1. Modern Flat Config (`eslint.config.mjs` / `eslint.config.js`)

AI Guard exports full native support for modern ESLint Flat Config:

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

export default [
  {
    plugins: {
      'ai-guard': aiGuard,
    },
    rules: {
      ...aiGuard.configs.recommended.rules,
      // Custom overrides if desired:
      'ai-guard/no-floating-promise': 'error',
    },
  },
];

To use the strict or security preset in flat config:

// Strict preset — all 18 rules at error
rules: {
  ...aiGuard.configs.strict.rules,
}

// Security preset — security rules only
rules: {
  ...aiGuard.configs.security.rules,
}

2. Legacy Config (`.eslintrc.js` / `.eslintrc.json`)

// .eslintrc.js
module.exports = {
  plugins: ['ai-guard'],
  extends: ['plugin:ai-guard/recommended'],
};

CLI Reference

AI Guard includes a full-featured CLI binary (ai-guard) that runs out of the box with zero ESLint configuration files required:

npx ai-guard <command> [options]

Core Commands

CLI Usage Examples

# 1. Immediate scan of current directory
npx ai-guard run

# 2. Strict CI scan failing only on high-confidence issues
npx ai-guard run --strict --fail-on high

# 3. Pull Request scan (diffs against PR target branch)
npx ai-guard changed --pr --sarif --sarif-output results.sarif

# 4. Generate AI agent guardrails for Cursor, Claude Code, and Copilot
npx ai-guard init-context --all

# 5. Generate interactive HTML diagnostic report
npx ai-guard report --output ai-guard-report.html

# 6. Save existing issues as baseline and only fail on new regressions
npx ai-guard baseline --save
npx ai-guard baseline --check

AI Agent Integration (`init-context`)

Standard linters only run after code has already been written. The init-context command shifts your guardrails left by embedding AI Guard's rules directly into the instruction files loaded by your AI coding tools:

npx ai-guard init-context --all

This generates three targeted context files:

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

How Shift-Left Works

AI Guard (init-context)
       ↓
Generates project guardrail files (CLAUDE.md, .cursorrules, copilot-instructions.md)
       ↓
AI coding assistant reads safety rules before generating code
       ↓
Model avoids floating promises, empty catches, and hardcoded secrets at prompt time
       ↓
AI Guard CLI & GitHub Action deterministically verifies the output in CI

This dual-layer defense minimizes review friction and ensures generated code meets your security standard on the first pass.

Claude Code Integration

AI Guard integrates directly with Claude Code as a PostToolUse validation hook. Every time Claude Code edits or writes a JS/TS file, AI Guard automatically scans it for common issues.

# One-command setup
npx ai-guard init-claude

This configures a PostToolUse hook in .claude/settings.json that runs AI Guard's fast agent preset (5 high-confidence rules, ~50-200ms per file) after every file edit. Claude Code reads the diagnostics and can fix issues automatically.

# Preview before applying
npx ai-guard init-claude --dry-run

# Use per-machine settings (gitignored)
npx ai-guard init-claude --local

Agent preset rules: no-hardcoded-secret, no-eval-dynamic, no-empty-catch, no-sql-string-concat, no-floating-promise

→ Full documentation

GitHub Action

The official AI Guard GitHub Action runs on PRs, detects changed files, provides step summaries, outputs SARIF 2.1.0, and posts inline PR annotations directly on GitHub:

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

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  ai-guard-scan:
    name: AI Guard Code Review
    runs-on: ubuntu-latest

    permissions:
      contents: read
      security-events: write
      actions: read

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for git diff comparison

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Run AI Guard
        uses: ai-guard-dev/eslint-plugin-ai-guard@v1
        with:
          preset: 'recommended'
          fail-on: 'high'
          changed-only: 'true'
          upload-sarif: 'true'

Action Inputs (`action.yml`)

Action Outputs

SARIF & GitHub Code Scanning

AI Guard natively outputs SARIF 2.1.0 (Static Analysis Results Interchange Format). When uploaded via the GitHub Action or github/codeql-action/upload-sarif@v3, findings integrate directly with GitHub Advanced Security:

Inline PR Annotations: Direct comments on the exact source lines where flaws exist.
Security Dashboard: Persistent alerts under your repository's Security → Code scanning tab.
Merge Protection: Block merges automatically when high-confidence security or async bugs are detected.

Visual Previews

Inline Pull Request Annotations

GitHub Advanced Security Summary

Persistent Code Scanning Dashboard

Rule Examples (Before & After)

1. `no-floating-promise` (Unhandled Promises)

// ❌ BAD: Floating promise. Errors are dropped silently.
async function syncUserProfile(user: User) {
  sendTelemetryEvent('user_sync', user.id);
  database.save(user);
}

// ✅ GOOD: Awaited, explicitly handled, or marked with void
async function syncUserProfile(user: User) {
  await database.save(user);
  void sendTelemetryEvent('user_sync', user.id); // Explicitly unhandled
}

2. `no-hardcoded-secret` (Committed Credentials)

// ❌ BAD: Secret committed inline
const client = new PaymentGateway({
  apiKey: 'sk-prod-983427598273498273948273',
});

// ✅ GOOD: Read from environment variable (Autofixable!)
const client = new PaymentGateway({
  apiKey: process.env.API_KEY,
});

3. `no-await-in-loop` (Sequential Latency Trap)

// ❌ BAD: Consecutive awaits block each iteration sequentially
async function fetchAllUsers(ids: string[]) {
  const users = [];
  for (const id of ids) {
    users.push(await fetchUser(id));
  }
  return users;
}

// ✅ GOOD: Concurrently fetched with Promise.all (Autofixable!)
async function fetchAllUsers(ids: string[]) {
  return await Promise.all(ids.map((id) => fetchUser(id)));
}

4. `no-empty-catch` (Swallowed Errors)

// ❌ BAD: Exception swallowed without trace
try {
  parseConfiguration(rawConfig);
} catch (e) {}

// ✅ GOOD: Logged, rethrown, or documented (Autofixable!)
try {
  parseConfiguration(rawConfig);
} catch (e) {
  logger.error('Configuration parsing failed', { error: e });
  throw e;
}

5. `no-sql-string-concat` (SQL Injection)

// ❌ BAD: Dynamic string interpolation in SQL
const query = `SELECT * FROM users WHERE organization_id = '${orgId}' AND role = '${role}'`;
await db.query(query);

// ✅ GOOD: Parameterized query binding
const query = 'SELECT * FROM users WHERE organization_id = $1 AND role = $2';
await db.query(query, [orgId, role]);

Automatic Remediation (Autofix)

Rules that have deterministic solutions provide automatic autofix handlers. Run ESLint's native --fix flag to automatically resolve them:

npx eslint . --fix

| Rule | Automatic Fix Behavior | | :--- | :--- | | no-hardcoded-secret | Replaces hardcoded string literal with process.env.VARIABLE_NAME | | no-empty-catch | Inserts /* TODO: handle error */ comment to prevent silent swallowing | | no-floating-promise | Prepends void expression to intentionally unawaited calls | | no-await-in-loop | Rewrites straightforward sequential loops to await Promise.all(...) |

Benchmarks & Empirical Evaluation

AI Guard has been empirically evaluated across multiple benchmarks comparing runtime scan performance, coverage gaps vs. standard tooling, and detection accuracy across real-world codebases.

1. What AI Guard Catches vs. Conventional Linters

Conventional linters either omit AI-specific hazards entirely or require heavyweight TypeScript type-checking (parserOptions.project) that significantly slows down CI:

[!TIP] Minimal Type-Information Dependency: 17 of 18 AI Guard rules operate in pure syntax/scope-analysis mode without projectService or tsconfig.json. The no-floating-promise rule optionally uses TypeScript parser services for higher recall on cross-module Promise calls, with syntax/scope-based heuristics as a zero-config fallback.

2. Runtime Performance

Benchmark: scanning 196 TypeScript / JavaScript files (algorithm-automata-simulator, Windows 11, Node.js 20, median of 3 runs):

AI Guard executes 4x–6x faster than type-aware linting suites because it leverages deterministic AST heuristics rather than reconstructing the full TypeScript symbol graph.

3. Empirical Bug Detection & Precision Study

Two comprehensive empirical benchmark evaluations were conducted to measure real-world precision and detection yields:

A. Accuracy & False Positive Audit (4 Real-World Repositories, 378 Files)

| Category | Findings | True Positives | False Positive Rate | | :--- | :---: | :---: | :---: | | Security (no-hardcoded-secret, no-eval-dynamic, etc.) | 15 | 15 | 0% | | Reliability (no-empty-catch, broad exceptions) | 53 | 53 | 0% | | Async Stability (no-floating-promise, async callbacks) | 43 | ~40 | ~7% | | AI Patterns (duplicate logic, dead branches) | 58 | 43 | 26% (reduced in v1.2.8+) |

B. Dual-Mode Detection Study (48 Call Sites & Real Production Target)

Audited across a controlled multi-file test corpus (13 files, 48 call sites) and a real-world Express + MongoDB production application (Truvita New):

High Precision: 100% precision on type-aware exclusive findings (26 of 26 verified True Positives; 0 false alarms on synchronous controls).
Critical Detection: Detected 1 critical database startup race condition in production (server/index.ts connectDB()) where an unawaited connection call allowed requests to hit the database before initialization.
Single-File Actionability: 100% of findings were resolvable locally at the call site (await, .catch(), or void).

For the complete methodology, raw findings, and benchmark harness, see docs/benchmarks.md.

Performance & Philosophy

Zero LLM Overhead: AI Guard does not call external APIs, does not incur token costs, and does not add LLM latency. A scan of 100+ files executes in milliseconds.
100% Deterministic: Every finding is derived strictly from Abstract Syntax Tree analysis. No probabilistic drift, no non-deterministic hallucinated findings.
Low False Positives: Built with precision-first design. Context-sensitive rules are configured at warn or off in the recommended preset so developers are never blocked by noise.
Self-Scanning: AI Guard enforces its own rules on its own codebase in CI using the strict preset.

Learn More & Ecosystem

Visit getaiguard.dev to explore interactive documentation, rule catalogs, benchmarks, and deep-dive engineering articles.

Official Links

Website: https://getaiguard.dev
GitHub Organization: https://github.com/ai-guard-dev
Repository: https://github.com/ai-guard-dev/eslint-plugin-ai-guard
npm Registry: https://www.npmjs.com/package/eslint-plugin-ai-guard
GitHub Action: ai-guard-dev/eslint-plugin-ai-guard@v1

Contributing

We welcome contributions, new rule ideas, bug reports, and false-positive reports!

Check out our Contributing Guide for local setup and testing standards.
Review our Security Policy to report vulnerabilities responsibly.
Check open issues or submit new ones on our Issue Tracker.