Principle:Protectai Modelscan CLI Scan Interface

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

Overview

A command-line interface that provides direct terminal access to model security scanning with configurable output formats, logging levels, and settings file support.

Description

The CLI Scan Interface principle covers the design of a user-friendly terminal interface for security scanning of ML model files. The interface needs to balance simplicity (scan a file with a single command) with flexibility (customize settings, output formats, logging verbosity). It also must provide meaningful exit codes for integration with shell scripts and CI/CD pipelines.

Key design decisions:

• Default command: The scan command is the default action, so modelscan -p /path works without specifying a subcommand
• Settings precedence: Command-line flags override settings file values, which override built-in defaults
• Exit code contract: Structured exit codes distinguish between clean scans (0), vulnerabilities found (1), errors (2), no supported files (3), and CLI usage errors (4)
• Settings file auto-detection: The CLI automatically looks for modelscan-settings.toml in the current directory

Usage

Apply this principle when:

• Running ad-hoc model scans from the terminal
• Integrating modelscan into shell scripts or CI/CD pipelines
• Creating or managing settings files for team-wide scanning standards
• Understanding the relationship between CLI options and the programmatic API

Theoretical Basis

The CLI follows a convention-over-configuration approach with progressive disclosure of options:

# Simplest usage - scan with defaults
# $ modelscan -p /path/to/model.pkl

# With options
# $ modelscan scan -p /path/to/model -r json -o report.json --show-skipped

# Settings file generation
# $ modelscan create-settings-file
# $ modelscan create-settings-file --force --location /custom/path.toml

Exit code contract:

Exit 0: Scan completed, no vulnerabilities found
Exit 1: Scan completed, vulnerabilities found
Exit 2: Scan encountered errors or threw exceptions
Exit 3: No supported files were found to scan
Exit 4: CLI usage error (missing required options)

Settings resolution order:

# Pseudo-code for settings resolution
if --settings-file specified:
    settings = parse_toml(settings_file)
elif ./modelscan-settings.toml exists:
    settings = parse_toml("./modelscan-settings.toml")
else:
    settings = DEFAULT_SETTINGS

# CLI flags override settings
settings["reporting"]["module"] = REPORTING_MODULES[--reporting-format]
settings["reporting"]["settings"]["show_skipped"] = --show-skipped
settings["reporting"]["settings"]["output_file"] = --output-file

Related Pages

Implemented By

• Implementation:Protectai_Modelscan_CLI_Scan_Command