@umesh_raut/ai-firewall

A security layer for AI coding assistants. Intercept, analyze, and control the actions AI tools perform on your codebase.

AI Firewall wraps any AI tool command, monitors its output in real time, and evaluates every detected action (file create, edit, delete, shell command) against a risk policy — automatically allowing safe operations, flagging risky ones for review, and blocking dangerous actions.

Installation

npm install -g @umesh_raut/ai-firewall

Or use it locally in a project:

npm install @umesh_raut/ai-firewall

Quick Start

# Initialize AI Firewall in your project
ai-firewall init

# Wrap an AI tool command
ai-firewall wrap "claude code"

# Inspect cached context for a file
ai-firewall inspect package.json

How It Works

AI Firewall operates as a 4-stage pipeline:

AI Tool Output → Intercept → Parse → Assess Risk → Decide

1. Intercept

Wraps any AI tool as a child process and monitors its stdout/stderr in real time. Detects interactive prompts (e.g. "are you sure?", "(y/n)") via pattern matching.

2. Parse

Extracts structured actions from raw AI tool output. Recognizes four action types:

| Action | Examples | |----------|---------------------------------------| | create | "Creating file utils.ts", touch x | | edit | "Editing config.json", "Modifying…" | | delete | "Deleting old-file.ts", rm -rf | | run | "Running npm install", $ git push |

3. Assess Risk

Each action is evaluated against a rule-based risk engine:

| Risk Level | Trigger | |------------|------------------------------------------------------| | HIGH | Deleting core files (package.json, .env, etc.) | | HIGH | Running destructive commands (rm -rf) | | MEDIUM | Editing core project files | | MEDIUM | Modifying files referenced in 5+ places | | LOW | Creating new files, other safe operations |

4. Decide

Risk levels map to decisions:

| Risk | Decision | Meaning | |--------|-----------|--------------------------------| | LOW | ALLOW | Action proceeds automatically | | MEDIUM | ASK | Flagged for human review | | HIGH | BLOCK | Action is blocked |

All decisions are logged to a local history for auditability.

CLI Commands

ai-firewall init

Initializes AI Firewall storage (.ai-firewall/ directory) in the current project. This stores file context cache and decision history.

ai-firewall init

ai-firewall wrap <command>

Wraps an AI tool command and monitors its actions in real time.

ai-firewall wrap "claude code"
ai-firewall wrap "copilot chat"

The firewall displays a styled decision card for each detected action, showing the action type, target file, risk level, and decision.

ai-firewall inspect <file>

Shows the cached context for a specific file — how many files reference it, whether it's considered a core file, and when the context was last computed.

ai-firewall inspect src/index.ts

Programmatic Usage

You can also use AI Firewall as a library:

import { spawnWrapped, detectPrompt } from "@umesh_raut/ai-firewall";
import type { SpawnOptions, Detection } from "@umesh_raut/ai-firewall";

spawnWrapped({
  command: "claude",
  args: ["code"],
  onOutput(chunk) {
    process.stdout.write(chunk);
  },
  onAction(action) {
    console.log("Detected action:", action.type, action.files);
  },
  onExit(code) {
    process.exit(code ?? 1);
  },
});

Core Files

The following files are considered "core" by default and receive elevated risk assessment:

• package.json
• tsconfig.json
• .env
• .gitignore
• docker-compose.yml
• Dockerfile
• Makefile

Project Structure

src/
  cli/           # CLI entry point and terminal formatting
  interceptor/   # Process spawning and prompt detection
  analyzer/      # Action parsing and project context building
  policy/        # Risk assessment and decision engine
  storage/       # File-based cache and decision history

Requirements

• Node.js >= 18

License

MIT