VIPI

Scan images for visual indirect prompt injections.

VIPI transforms each image through a multi-view OCR pipeline, then checks the final recognized text with Jev, OpenAI Decisions or the local Prompt Guard model. The public interface is a small command-line tool that can scan files, directories and committed image changes.

Installation

VIPI requires Python 3.12 and uv. Install the CLI from PyPI with uv tool install. Choose the install path for the detector you plan to use. Both paths include the OCR dependencies; OCR runs locally and is required for every scan.

Cloud API detector

For Jev or OpenAI, install VIPI with its OCR extra:

uv tool install --python 3.12 'vipi-scanner[ocr]'
vipi setup

Set the credential for the detector you will use before scanning. Jev accepts TYPESAFE_API_KEY (or the alias JEV_API_KEY); OpenAI uses OPENAI_API_KEY. For example, set one in your shell before running vipi scan:

# macOS / Linux
export TYPESAFE_API_KEY="your-typesafe-api-key"

# Windows PowerShell
$env:TYPESAFE_API_KEY = "your-typesafe-api-key"

For OpenAI, set OPENAI_API_KEY in place of TYPESAFE_API_KEY. The default detector is Jev; select OpenAI with --detector openai.

vipi scan image.png

Local Prompt Guard detector

To run the detector locally, install the OCR and local-detector extras, then prepare Prompt Guard and its model weights:

uv tool install --python 3.12 'vipi-scanner[ocr,detector-local]'
vipi setup --detector prompt-guard
vipi scan image.png --detector prompt-guard

Prompt Guard weights require authorized access to the Hugging Face model. Set HF_TOKEN if your account needs a token to download them. OCR model setup downloads the pinned PP-OCRv6 files for both install paths; scanning does not download models.

If vipi is not found after installation, run uv tool update-shell and restart your terminal so uv's tool directory is added to PATH.

Usage

# Scan one or more images
vipi scan label.png screenshot.jpg

# Scan a directory recursively and save a JSON report
vipi scan ./images --output report.json

# Choose a speed/quality mode or a specific supported model
vipi scan ./images --ocr-mode fast
vipi scan ./images --ocr-mode balanced
vipi scan ./images --ocr-model ppocr-v6-medium

# Scan committed images added or modified on a branch
vipi scan . --diff origin/main --output report.json

# Choose a detector and adjust the finding threshold
vipi scan image.png --detector openai --threshold 90

The interface has two commands, vipi setup and vipi scan. OCR modes map fast to PP-OCRv6 Tiny, balanced to Small and quality to Medium. quality is the default to preserve the previous Medium behavior. --ocr-model selects a supported model ID directly and overrides the mode. vipi setup prepares all three models by default. The default detector is Jev with a threshold of 80 on a 0–100 score scale. A score at the threshold counts as a finding; it is not a calibrated probability of an attack.

See the CLI guide for provider configuration, GitHub Actions examples, branch-diff behavior, cache paths and report details.

Results and automation

Exit codes support CI use:

VIPI provides the CLI for GitHub Actions workflows; this repository does not currently include a packaged GitHub Action. See the PR scan example.

Documentation

• CLI usage and platform validation
• Package architecture
• Development setup and checks
• Research workbench and datasets
• Decision records

A built wheel contains the vipi package. Research tools, datasets, model weights and run artifacts remain outside the runtime package.

License

VIPI's original code, documentation and project assets are licensed under the Apache License, Version 2.0. Third-party models, dependencies, datasets and other third-party material retain their own license terms; see their respective notices and source projects.