VEILSCAN

VEILSCAN is an AI/ML security scanning project with three main parts:

• A Python CLI that scans model artifacts, codebases, configs, and AI application glue code

• A Tauri desktop app that wraps the CLI in a local UI

• A website/frontend prototype area used for an alternate web experience

• The project is aimed at developers, security engineers, and researchers who want a practical way to inspect AI/ML systems for common security, privacy, supply-chain, governance, and deployment risks.

What This Project Covers

• VEILSCAN is broader than a single-file model scanner.

It can inspect:

• Model artifacts such as .pt, .pth, .bin, .safetensors, .onnx, .h5, .keras, .joblib, .pkl
• Python projects that serve, fine-tune, or integrate models
• RAG and agent-style applications
• Dependency manifests such as requirements.txt, pyproject.toml, Pipfile, and environment.yml
• Hugging Face model metadata and local snapshots
• Running model APIs through the live probe command

It does this without loading untrusted model weights during normal static scans.

Repository Layout

'''text . ├─ veilscan/ Python CLI and scanning engine ├─ app/ Tauri desktop app (React + TypeScript frontend, Rust backend) ├─ tests/ Unit tests and vulnerable/clean fixtures ├─ sample_ui 2/ Website/frontend prototype area used by launch_website.bat ├─ launch_app.bat Desktop app launcher ├─ launch_website.bat Website prototype launcher ├─ pyproject.toml Python package config and CLI entry point └─ requirements.txt Optional/dev dependency hints

### Component Status

- `veilscan/` is the core product and the most complete part of the repository.
- `app/` is a working local desktop shell over the CLI.
- `sample_ui 2/` currently looks incomplete in this checkout. The launcher exists, but the directory mostly contains generated Next.js artifacts and installed dependencies rather than a clean, source-complete web app.

## Core Capabilities

### CLI

The CLI is the main engine. It supports:

- Static scanning of local folders, single files, GitHub repos, and Hugging Face targets
- Purpose-aware scoring for different AI use cases
- Security checklist scoring against multiple frameworks
- Exploit demo generation
- Threat model generation
- Red-team playbook generation
- SBOM generation
- Fingerprinting and watermark-related analysis
- Dependency graph and CVE-style dependency checks
- Compliance-oriented reporting
- Patch and auto-fix generation
- Risk history tracking
- CI/CD template generation
- Live endpoint probing

### Desktop App

The Tauri app exposes the CLI through a local UI with these panels:

- `Scan`
- `Live Probe`
- `History`
- `Threat Model`
- `Red Team`
- `Analysis`
- `Settings`

The app shells out to the installed `veilscan` command, streams output into the UI, and can export generated content such as scan JSON, threat models, and red-team playbooks.

### Website Prototype

The repository also includes `launch_website.bat`, which targets `sample_ui 2/`. At the moment, this appears to be a prototype area rather than a stable, documented web product. Treat it as experimental unless the missing website source is restored.

## How VEILSCAN Works

### Static Scan Path

For local and repository targets, VEILSCAN:

1. Resolves the target type
2. Walks the file tree while skipping common cache/build directories
3. Reads source, config, and model-adjacent files safely
4. Runs all registered check modules
5. Aggregates findings into a risk score and label
6. Maps findings into checklist frameworks
7. Produces terminal output, JSON, fixes, or downstream reports

Notebooks are treated as code input for scanning purposes, so `.ipynb` content is included when Python-oriented checks run.

### Live Probe Path

The `probe` command is different from the static scanner.

It sends real HTTP requests to a running endpoint and checks runtime behavior such as:

- authentication enforcement
- CORS behavior
- rate limiting
- output length control
- prompt injection resistance
- system prompt leakage
- jailbreak resistance

This is the only active testing path in the project. Everything else is static analysis or generated reporting.

## Supported Targets

VEILSCAN accepts targets such as:

- local directories: `veilscan .`
- local files: `veilscan model.pt`
- Hugging Face model IDs: `veilscan meta-llama/Llama-2-7b-hf`
- Hugging Face URLs
- GitHub repository URLs

## Installation

### Python CLI

Recommended local development install:

```powershell
pip install -e .

Run the CLI:

veilscan --help

If the command is not on PATH:

py -m veilscan --help

Optional Python Dependencies

The core scanner is stdlib-first. Optional packages are used for specific workflows.

• huggingface_hub for Hugging Face snapshot scanning
• torch and transformers are referenced in fixtures and examples, not required for core static scans

Desktop App Prerequisites

To run the Tauri app, you need:

• Python with veilscan installed locally
• Node.js and npm
• Rust toolchain for Tauri builds

Install frontend dependencies:

cd app
npm install

Run the app:

npm run tauri dev

Or from the repo root:

start_app.bat

launch_app.bat also exists, but it includes branch-switching behavior and is more opinionated than start_app.bat.

CLI Usage

Basic Scan

veilscan .
veilscan C:\path\to\project
veilscan meta-llama/Llama-2-7b-hf
veilscan https://github.com/org/repo

JSON Output

veilscan . -o report.json

Purpose-Aware Scanning

veilscan . --purpose chatbot
veilscan . --purpose medical
veilscan . --purpose agent

Filtering and CI-Oriented Use

veilscan . --min-severity HIGH
veilscan . --fail-on HIGH
veilscan . -q

Auto-Fix and Patch Output

veilscan . --fix
veilscan patch . -o fixes.patch
veilscan patch . --pr-desc pr.md

Live Probe

veilscan probe http://localhost:8000/v1/chat/completions
veilscan probe http://localhost:11434/api/generate --format ollama --model llama3
veilscan probe https://api.anthropic.com/v1/messages --format anthropic --auth <api-key>
veilscan probe http://localhost:8000/generate --format raw

Reports and Analysis

veilscan threat-model .
veilscan redteam .
veilscan sbom .
veilscan fingerprint .
veilscan compliance .
veilscan watermark .
veilscan depgraph .
veilscan benchmark .

Utility Commands

veilscan history .
veilscan history --all
veilscan ci-setup
veilscan ci-setup --ci github
veilscan checklists

Desktop App Overview

The desktop app is a local shell around the CLI. It does not reimplement the scanner in JavaScript. Instead, it invokes the Python command and streams results into the UI.

Scan Panel

The Scan panel supports:

• path/model/repo target entry
• purpose selection
• exploit demo toggle
• fix toggle
• grouped findings by severity
• model-file focused filtering
• JSON export

Probe Panel

The Probe panel supports endpoint formats for:

• OpenAI-compatible chat/completions APIs
• Ollama
• Anthropic
• raw text endpoints

Analysis Panel

The Analysis panel provides UI wrappers for:

• sbom
• fingerprint
• compliance
• watermark
• depgraph
• benchmark
• patch

Threat Model and Red Team Panels

These panels generate and export:

• STRIDE threat models
• red-team attack playbooks

History Panel

History reads stored scan history from the user profile and visualizes risk score trends over time.

Settings Panel

Settings control defaults such as:

• minimum severity
• default purpose
• exploit/fix defaults
• stderr visibility
• CI/CD template generation

Checks and Detection Areas

VEILSCAN currently registers 19 main check families.

Check Family	Prefixes	Focus
Prompt Injection & Insecure Output Handling	PI-*	User-controlled prompt building, system prompt injection, eval/exec, prompt-to-SQL patterns, jailbreak text
Unsafe Serialization	SERIAL-*	Pickle-based formats, torch.load, pickle.load, unsafe yaml.load, related deserialization risks
Model Integrity	INTEG-*	Missing checksums, backdoor-like loaders, compressed pickle bypass patterns, tampered model behavior
Data Leakage	DL-*	Hardcoded secrets, tokens, credentials, private keys, PII patterns
Excessive Agency & Model Theft	AGENCY-*	Unsafe autonomy, disabled human approval, dangerous system prompts, model internals exposure
Plugin / Tool Security	PLUGIN-*	Dangerous tool definitions, missing parameter constraints, user-controlled external actions
Training Data Poisoning	TRAIN-*	Untrusted datasets, direct remote training input, poisoned JSONL instructions, reward-model abuse
Model Configuration	CONFIG-*	trust_remote_code, auto_map, risky tokenizer or generation settings
RAG Security	RAG-*	Untrusted loaders, poisoned vector stores, unsafe context insertion, raw retrieval injection
Model DoS	DOS-*	Missing output limits, absent rate limiting, unbounded loops, oversized generation configs
Privacy Risk	PRIV-*	Confidence scores, hidden state exposure, prompt leakage, personal data without privacy controls
Adversarial Robustness	ADV-*	Missing robustness tooling, absent validation, poor preprocessing, missing adversarial documentation
Transfer Learning Security	XFER-*	Fine-tuning unsafe bases, dynamic model paths, trust_remote_code=True
Output Integrity	OI-*	Missing audit logging, insecure serving, forwarding model output to external systems
License Compliance	LIC-*	Missing/unknown license, GPL/AGPL/non-commercial restrictions
Bias & Fairness	BIAS-*	Missing fairness evaluation, risky high-risk-use documentation gaps, protected attributes, stereotype patterns
Model Drift	DRIFT-*	Missing drift monitoring and post-deployment observation
Dependency Vulnerabilities	DEP-*	Version-based dependency risk rules and known vulnerable package checks
Supply Chain & Provenance	SC-*	Missing model cards, provenance gaps, weak documentation, related trust signals

For a fuller reference, see CHECKS.md.

Supported Security Frameworks

VEILSCAN maps findings into these checklist views:

• owasp-llm
• owasp-ml
• mitre-atlas
• real-world
• compliance

This means the scanner does not only emit raw findings. It also groups them into recognizable frameworks for governance and review.

Generated Outputs

Depending on the command, VEILSCAN can produce:

• terminal reports
• JSON scan reports
• threat model Markdown
• red-team playbooks
• SBOM JSON/Markdown
• compliance Markdown/HTML
• dependency graph JSON/DOT
• patch files
• PR description Markdown
• CI/CD config files

Tests and Fixtures

The repository includes:

• tests/test_checks.py for the main check modules and checklist behavior
• tests/test_commands.py for utility/reporting modules such as SBOM, depgraph, fixer, patcher, history, and resolver
• fixture projects under tests/fixtures/ covering vulnerable and clean examples

Useful fixture examples include:

• tests/fixtures/vulnerable_model/
• tests/fixtures/clean_model/
• tests/fixtures/rag_project/
• tests/fixtures/agent_project/
• tests/fixtures/training_project/
• tests/fixtures/dos_project/

Development Notes

Python Entry Point

The CLI entry point is:

• veilscan.cli:main

The python -m veilscan shim is in:

• veilscan/__main__.py

Main Python Modules

• veilscan/cli.py builds and dispatches commands
• veilscan/scanner.py orchestrates check execution
• veilscan/checks/ contains the detection modules
• veilscan/report.py formats and exports scan results
• veilscan/probe.py handles live API probing

Desktop App Architecture

• app/src/ is the React frontend
• app/src-tauri/src/lib.rs exposes Tauri commands
• the Tauri backend runs the installed veilscan binary and streams output into the UI

Limitations and Current Reality

This repository is strongest today as:

• a static AI/ML security scanner
• a local desktop frontend over that scanner
• a generator of security-oriented artifacts such as threat models and reports

Things to keep in mind:

• normal scans are heuristic static analysis, not proof of exploitability
• probe is a lightweight runtime tester, not a full red-team framework
• the website prototype area is not cleanly source-complete in this checkout
• some generated outputs are advisory or heuristic and should be reviewed by a human before being treated as authoritative

Suggested Starting Points

If you want to try the project quickly:

pip install -e .
veilscan . -o report.json
veilscan threat-model . -o threat-model.md
veilscan probe http://localhost:8000/v1/chat/completions

If you want the desktop app:

pip install -e .
cd app
npm install
npm run tauri dev