Implementation:Protectai Modelscan CLI Scan Command

Knowledge Sources	ModelScan
Domains	ML_Security, CLI
Last Updated	2026-02-14 12:00 GMT

Overview

Concrete tool for scanning ML model files from the command line, provided by the modelscan CLI module built on Click.

Description

The cli.py module implements the modelscan command-line interface using the Click library. It provides two commands: scan (default) which runs a security scan on model files, and create-settings-file which generates a default TOML configuration file. The scan command handles settings file loading, logging configuration, reporting format selection, and exit code management.

Usage

Use this command-line tool when:

Running ad-hoc security scans on model files from the terminal
Integrating modelscan into shell scripts or CI/CD pipelines
Generating a default settings file for customization

Code Reference

Source Location

Repository: modelscan
File: modelscan/cli.py
Lines: L1-216

Signature

@cli.command()
def scan(
    ctx: click.Context,
    log: str,                        # Log level: CRITICAL|ERROR|WARNING|INFO|DEBUG
    path: Optional[str],             # Path to file or directory to scan
    show_skipped: bool,              # Include skipped files in output
    settings_file: Optional[str],    # Path to TOML settings file
    reporting_format: str,           # Output format: console|json|custom
    output_file: Path,               # Optional file for report output
) -> int:
    """Scan a model file or directory for suspicious actions."""

@cli.command("create-settings-file")
def create_settings(
    force: bool,                     # Overwrite existing file
    location: Optional[str],         # Custom file path
) -> None:
    """Create a modelscan settings file."""

def main() -> None:
    """Entry point registered as 'modelscan' console script."""

Import

# CLI is invoked via the 'modelscan' console script entry point
# Defined in pyproject.toml: modelscan = "modelscan.cli:main"

I/O Contract

Inputs

Name	Type	Required	Description
-p/--path	str (click.Path)	Yes	Path to file or directory to scan. Must exist.
-l/--log	str (Choice)	No	Log level: CRITICAL, ERROR, WARNING, INFO (default), DEBUG
--show-skipped	bool (flag)	No	Include skipped files in the report output (default: False)
--settings-file	str (click.Path)	No	Path to TOML settings file. Default: ./modelscan-settings.toml
-r/--reporting-format	str (Choice)	No	Report format: console (default), json, custom
-o/--output-file	str (click.Path)	No	File path for report output (used with JSON format)

Outputs

Name	Type	Description
Console output	stdout	Rich-formatted (console) or JSON report printed to stdout
Output file	file	Optional JSON report written to --output-file path
Exit code 0	int	Scan completed, no vulnerabilities found
Exit code 1	int	Scan completed, vulnerabilities found
Exit code 2	int	Scan encountered errors or exceptions
Exit code 3	int	No supported files were found to scan
Exit code 4	int	CLI usage error (e.g., missing --path)

Usage Examples

Basic Scan

# Scan a single model file
modelscan -p /path/to/model.pkl

# Scan a directory
modelscan -p /path/to/models/

JSON Output with File

# Output JSON report to terminal and file
modelscan -p /path/to/model.pkl -r json -o scan_report.json

With Settings File

# Use custom settings file
modelscan -p /path/to/model.pkl --settings-file /etc/modelscan/settings.toml

# With verbose logging
modelscan -p /path/to/model.pkl -l DEBUG

CI/CD Pipeline Integration

#!/bin/bash
# CI/CD script using exit codes
modelscan -p ./models/ -r json -o report.json

EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
    echo "Models are safe"
elif [ $EXIT_CODE -eq 1 ]; then
    echo "VULNERABILITIES FOUND - blocking deployment"
    exit 1
elif [ $EXIT_CODE -eq 2 ]; then
    echo "Scan errors occurred"
    exit 1
fi

Generate Settings File

# Create default settings file in current directory
modelscan create-settings-file

# Overwrite existing and specify location
modelscan create-settings-file --force --location /etc/modelscan/settings.toml

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment