ICU CLI

A command-line AI supply chain firewall. Scan files and packages for prompt injection, data exfiltration, obfuscation, and other malicious patterns targeting AI development tools.

Quick Start

Install

pip install icu

Scan a file

icu scan ./suspicious-package/

Set up a project with policy + git hook

icu init

Watch for changes in real-time

icu watch ./src

Features

37 Detection Rules

Prompt injection, data exfiltration, obfuscation, suspicious commands, and network threats

Tiered Analysis

Fast hash lookup, heuristic matching, and deep analysis with entropy and deobfuscation

Watch Mode

Real-time file monitoring that scans changes as you work

Git Hooks

Pre-commit integration to block malicious code before it enters your repo

Policy Engine

Custom allow/block/warn rules per project with tool-specific overrides

Reputation DB

SQLite-backed hash tracking with known-good and known-bad lists

MCP Server

Expose scanning tools to AI assistants via Model Context Protocol

Multiple Formats

Output as table, JSON, or SARIF for CI/CD integration

Command Reference

icu scan

Scan files or directories for malicious patterns. Uses a tiered pipeline: hash reputation lookup, heuristic pattern matching, and deep analysis with entropy measurement and deobfuscation.

Usage

icu scan <file-or-directory>

Options

--depth [fast|deep|auto]Scan depth — auto escalates if suspicious (default: auto)

--format [table|json|sarif]Output format (default: table)

--max-size BYTESMax file size to scan (default: 1 MB)

--exclude PATTERNGlob pattern to exclude (repeatable)

--workers NMax worker threads for parallel scanning

--policy FILEPolicy YAML file to evaluate results against

--no-dbDisable reputation database lookup

Examples

$ icu scan ./server.py$ icu scan ./project/ --depth deep --format json$ icu scan ./src --exclude '*.test.py' --exclude 'vendor/*'

Exit codes: 0 = clean, 1 = medium risk, 2 = high/critical risk

icu watch

Monitor a directory in real-time. Scans files as they change and prints results only when findings are detected. Ctrl+C to stop.

Usage

icu watch <directory>

Options

--depth [fast|deep|auto]Scan depth (default: auto)

--policy FILEPolicy YAML file to evaluate against

--max-size BYTESMax file size (default: 1 MB)

--exclude PATTERNGlob pattern to exclude (repeatable)

--no-dbDisable reputation database

Examples

$ icu watch ./src$ icu watch ./project --depth fast --exclude '*.log'

icu hook

Manage git pre-commit hooks. When installed, ICU automatically scans staged files before each commit and blocks commits that contain high-risk findings.

Usage

icu hook install | uninstall

Examples

$ icu hook install$ icu hook uninstall

icu init

Bootstrap a project with a default policy file and pre-commit hook in one step.

Usage

icu init [options]

Options

--no-hookSkip git pre-commit hook installation

--policy-path FILEOutput path for policy file (default: .icu-policy.yml)

Examples

$ icu init$ icu init --no-hook --policy-path ./custom-policy.yml

icu rules

List and filter the 37 built-in detection rules across 5 threat categories.

Usage

icu rules [options]

Options

--category NAMEFilter by category

--severity LEVELFilter by severity (info, warning, danger, critical)

--search PATTERNRegex search against rule ID and description

Examples

$ icu rules$ icu rules --category prompt_injection --severity critical$ icu rules --search 'ssh'

icu policy

Manage security policies. Define custom allow/block/warn rules per project with severity overrides by tool.

Usage

icu policy init | check | test

Examples

$ icu policy init$ icu policy check$ icu policy test ./src --tool claude --format json

icu lookup

Look up a file or SHA256 hash in the reputation database. Shows signature info and scan history.

Usage

icu lookup <file-or-hash>

Options

--format [table|json]Output format (default: table)

--db-path PATHPath to reputation database

Examples

$ icu lookup suspicious-file.py$ icu lookup abc123def456...

icu reputation

Manage the threat signature reputation database. Add custom signatures, import/export YAML, and view statistics.

Usage

icu reputation stats | list | add | remove | import | export

Examples

$ icu reputation stats$ icu reputation list --category prompt_injection$ icu reputation add --name 'custom_rule' --category suspicious_commands --pattern 'exec\(' --severity critical$ icu reputation export --format yaml > signatures.yml$ icu reputation import signatures.yml

Configuration

ICU loads configuration with the following precedence (highest to lowest):

1. CLI flags

Command-line arguments always take priority

2. Environment variables

ICU_DEPTH, ICU_MAX_SIZE, ICU_NO_DB, ICU_POLICY

3. Project config

.icu.yml or .icu.yaml in the project directory

4. Global config

~/.icu/config.yml for user-wide defaults

Example .icu.yml

depth: auto
max_file_size: 2097152
exclude:
  - "*.log"
  - "vendor/*"
  - "node_modules/*"
no_db: false

Example .icuignore

*.log
vendor/*
build/*
test_data/*
node_modules/*

Pre-commit Framework

ICU can also be used as a pre-commit hook in any project:

.pre-commit-config.yaml

repos:
  - repo: https://github.com/LiamCYD/icu
    rev: v0.1.0
    hooks:
      - id: icu-scan

View on GitHub · Apache 2.0 License · Python 3.11+