# Usage Examples ## Scanning a single file Use the Model Scanner CLI to scan a single file stored locally on your system. ### Local setup - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - The model to be scanned is on the host machine at path `/home/user/models/`. Change this path to match your system. - The model to be scanned is named `my_model.keras`. Change this name to match the file you want to scan. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. - `--persist` adds the scan results to an existing model in the Console. - `--model-name` and `--model-version` are the name and version number that appear in the Console. ### Container execution Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -v /home/user/models:/files-to-scan \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/my_model.keras --persist --model-name= --model-version= ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -v /home/user/models:/files-to-scan \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/my_model.keras --persist --model-name= --model-version= ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -v /home/user/models:/files-to-scan \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/my_model.keras ``` ### Output Example - STDOUT Scan results will be JSON-minified, but are shown formatted here for readability. details summary b EXPAND to see an example for scan results. ``` { "scan_id": "13c0f8a4-c938-43ee-9d95-2803ccd7de10", "start_time": "2025-02-12T17:55:36.511Z", "end_time": "2025-02-12T17:55:36.517Z", "status": "done", "version": "25.3.0", "$schema_version": "3.1.0", "inventory": { "requested_scan_location": "/files-to-scan/ZS_withConfig.nemo", "model_id": "00000000-0000-0000-0000-000000000000", "model_name": "cli-25.3.0-cdffd55e-802b-4440-8403-698e930e5bb9", "model_version": "1739382936", "model_version_id": "00000000-0000-0000-0000-000000000000" }, "file_results": [ { "file_instance_id": "01c8c57d-dd77-488b-b459-709f1933f7b2", "file_location": "/files-to-scan/ZS_withConfig.nemo", "status": "done", "start_time": "2025-02-12T17:55:36.511Z", "end_time": "2025-02-12T17:55:36.517Z", "details": { "sha256": "6a15d94d7c9a67d2574ba8226cfa7d678524899d61f18f98cb218da6e30f0570", "file_type": "TAR", "file_type_details": {}, "estimated_time": "" }, "seen": "2025-02-12T17:55:36.511Z", "detections": [ { "detection_id": "b3598a21-bdb0-4f4d-9c66-c7f127894b43", "rule_id": "NEMO_0008_202408", "category": "Decompression Vulnerabilities", "description": "Archive Contains Tar Slip attack, which can be used to overwrite files on the system.", "severity": "high", "mitre_atlas": [ { "technique": "AML.T0010", "tactic": "AML.TA0004" } ], "owasp": [ "ML06", "LLM05" ], "cwe": "", "cwe_href": "" } ] } ], "detection_count": 1, "file_count": 1, "files_with_detections_count": 1, "summary": { "detection_count": 1, "file_count": 1, "severity": "high", "files_with_detections_count": 1, "detection_categories": [ "Decompression Vulnerabilities" ] } } ``` ## Scanning a directory Use the Model Scanner CLI to scan all files in a directory that is stored locally on your system. ### Local Setup - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - The models to be scanned are on the host machine at path `/home/user/models/`. Change this path to match your system. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. ### Container execution Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -v /home/user/models:/files-to-scan \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/ ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -v /home/user/models:/files-to-scan \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/ ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -v /home/user/models:/files-to-scan \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input /files-to-scan/ ``` ### Output Example - STDOUT Scan results will be JSON-minified, but are shown formatted here for readability. details summary b EXPAND to see an example for scan results. ``` { "scan_id": "935fe7b5-ebc2-4a34-9c85-f1dd9f71b464", "start_time": "2024-12-13T05:58:26.306Z", "end_time": "2024-12-13T05:58:46.163Z", "status": "done", "version": "24.10.3", "$schema_version": "3.1.0", "inventory": { "requested_scan_location": "/files-to-scan/", "model_id": "00000000-0000-0000-0000-000000000000", "model_version_id": "d6ee11d6-31e6-4e28-8382-cda6a49c0c3e" }, "file_results": [ { "file_instance_id": "2c975b09-b9bf-4bf4-8d80-9ee45d344b8b", "file_location": "/files-to-scan/aws_model.safetensors", "status": "done", "start_time": "2024-12-13T05:58:26.306Z", "end_time": "2024-12-13T05:58:37.203Z", "details": { "sha256": "eed458758bd8165d80f496a90bcd2cfed9f1bf7d7b08677acd64e0f7d72bdcf2", "file_type": "safetensors", "file_type_details": {}, "estimated_time": "" }, "seen": "2024-12-13T05:58:26.306Z", "detections": [] }, { "file_instance_id": "ba1a10f9-5113-4520-b03a-0e4c0970fa25", "file_location": "/files-to-scan/test_model.pkl", "status": "done", "start_time": "2024-12-13T05:58:46.003Z", "end_time": "2024-12-13T05:58:46.163Z", "details": { "sha256": "bce834158f08706277377c50226e31b74e372770fe26fc5bdb4ff74de9924ffa", "file_type": "pickle", "file_type_details": { "pickle_header": { "pickle_version": "3", "type": "pickle" }, "pickle_modules": [ "sklearn.pipeline.pipeline", "sklearn.preprocessing._data.standardscaler", "callable: numpy.core.multiarray.scalar", "callable: numpy.dtype", "callable: numpy.core.multiarray._reconstruct", "numpy.ndarray", "lightgbm.sklearn.lgbmclassifier", "lightgbm.basic.booster", "callable: collections.defaultdict", "collections.ordereddict", "sklearn.preprocessing._label.labelencoder" ], "subtype": [ "numpy", "scikit" ] }, "estimated_time": "" }, "seen": "2024-12-13T05:58:46.003Z", "detections": [] } ], "detection_count": 1, "file_count": 3, "files_with_detections_count": 1, "summary": { "detection_count": 1, "file_count": 3, "severity": "high", "files_with_detections_count": 1, "detection_categories": [ "Decompression Vulnerabilities" ] } } ``` ## Globbing File Paths Preview This feature is in Preview. - Scan all `.pkl` files in the current directory and all subdirectories: `--input . --include-pattern "*.pkl"` - Scan all files in the directory tree rooted at the directory models, excluding `.txt` files: `--input ./models --exclude-pattern "*.txt"` - Scan all `.onnx` files in the directory tree rooted at the current working directory, except those labeled with a “v1” in the name: `modelscan-cli . --include-pattern "*.onnx" --exclude-pattern "*v1*"` - Scan all files except `.json` and `.txt` files in the current directory and all subdirectories: `--input . --exclude-pattern "*.json" --exclude-pattern "*.txt"` - Scan all files in the current directory and all subdirectories that start with `pytorch_model-`: `--input . --include-pattern "pytorch_model-*.bin"` ## Azure Blob Storage ### URL for Single Blob with Shared Access Signature An HTTPS URL with a shared access signature can be used with the --input parameter, but only a single blob is supported. ### Blob Enumeration Multiple blobs in a single container can be scanned by using a wasbs:// URI with the --input parameter. The URI should be of the following form: wasbs://your-container-name@your-storage-account.blob.core.windows.net/your-optional-prefix Depending on the storage configuration, credentials may be required. Set the following environment variables: - `AZURE_TENANT_ID` - `AZURE_CLIENT_ID` - `AZURE_CLIENT_SECRET` ### Download Model from Azure If none of the previous methods are suitable, the model can be downloaded from Azure, then scanned using the Model Scanner CLI’s support for local files. This example uses the Azure CLI to download the file. To install the Azure CLI, see the Azure documentation. After installing the Azure CLI, configure authentication for the Azure CLI. ### Download a Model from Azure to Local - Replace `` with the name of the Azure storage account. - Replace `` with the name of the Azure Blob container. Replace `` with the file name you are downloading. - Replace `<~/destination/path/for/file>` with the path and file name for your local storage (example: `~/Downloads/pytorch_model.bin`). ``` az storage blob download \ --account-name \ --container-name \ --name \ --file <~/destination/path/for/file> \ --auth-mode login ``` After downloading the file, use [Scanning a single file](#scanning-a-single-file) to scan the local model. ## Scan Model from Amazon S3 ### Presigned URL for Single Object An HTTPS URL that is presigned can be used with the `--input` parameter, but only a single object is supported. - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - Replace `presigned_url` with your AWS S3 presigned URL for the model file you want to scan. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. - `--persist` adds the scan results to an existing model in the Console. - `--model-name` and `--model-version` are the name and version number that appear in the Console. Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input "presigned_url" --persist --model-name= --model-version= ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input "presigned_url" --persist --model-name= --model-version= ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input "presigned_url" ``` ### Bucket Enumeration Multiple objects in a single bucket can be scanned by using a `s3://` URI with the `--input` parameter. The URI should be of the following form: `s3://some-bucket/some-optional-prefix` Depending on the bucket policy, AWS credentials may be required. - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - Replace `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, and `AWS_ENDPOINT` with your AWS information. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - Replace `s3://some-bucket/some-optional-prefix` with your AWS S3 bucket information for the bucket you want to scan. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input s3://some-bucket/some-optional-prefix ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input s3://some-bucket/some-optional-prefix ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -e AWS_ACCESS_KEY_ID= \ -e AWS_SECRET_ACCESS_KEY= \ -e AWS_SESSION_TOKEN= \ -e AWS_REGION= \ -e AWS_ENDPOINT= \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input s3://some-bucket/some-optional-prefix ``` ## Scan Model from Google Cloud Storage Multiple objects in a single bucket can be scanned by using a `gs://` URI with the `--input` parameter. - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - Create a credentials file (credentials.json) for the service account. See Google documentation for more information. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - Replace `gs://some-bucket/some-prefix` with your Google storage information for the bucket you want to scan. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -v $PWD/credentials.json:/credentials.json \ -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input gs://some-bucket/some-prefix ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -v $PWD/credentials.json:/credentials.json \ -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input gs://some-bucket/some-prefix ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -v $PWD/credentials.json:/credentials.json \ -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input gs://some-bucket/some-prefix ``` ## Scan a Hugging Face Repository Scan the files within a Hugging Face repository by providing the Hugging Face repository URL in the scan request. Example: `https://huggingface.co/username/repo_name`. When scanning a Hugging Face repository, the Model Scanner CLI will: - Identify and download all files within the specified repository. - Perform the scanning process on each downloaded file, according to the standard scanning rules and logic of the Model Scanner CLI. - Generate a scan report. If an invalid or non-existent Hugging Face repository URL is used, an error message is returned, and no scanning is performed. Use the following command to scan a Hugging Face repository. ### Hugging Face Repository Use the following command to scan a Hugging Face repository. - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - Replace `/` with the appropriate Hugging Face repository information. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ``` ### Private or Gated Hugging Face Repository To scan a private or gated Hugging Face repository, include the Hugging Face token as an environment variable in the scan request. - `HL_LICENSE` is your Model Scanner license as an environment variable. See [Running Model Scanner CLI](/docs/products/model-scanner/cli/run_model_scanner_cli) for information about setting the HiddenLayer environment variables. - This example runs the latest Model Scanner CLI image. Change the Model Scanner CLI version if you want to pull a different Model Scanner version. Example: change `latest` to `25.1.0`. - Replace `/` with the appropriate Hugging Face repository information. - Replace `` with the Hugging Face token for the private or gated repository. - For **Disconnected Mode**: - The scan results are saved at path `/home/user/results`. Change this path to match your system. - For **Hybrid Mode**: - `HL_CLIENT_ID` and `HL_CLIENT_SECRET` are the API key and secret to allow communication with the HiddenLayer AISec Platform. Hybrid Mode (US Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HF_TOKEN= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ``` Hybrid Mode (EU Region) ``` docker run --rm \ -e HL_LICENSE \ -e HL_CLIENT_ID \ -e HL_CLIENT_SECRET \ -e HL_MODEL_SCANNER_PLATFORM_RESULTS_URL='https://api.eu.hiddenlayer.ai' \ -e HL_MODEL_SCANNER_TOKEN_URL=https://auth.eu.hiddenlayer.ai/ \ -e HF_TOKEN= \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ``` Disconnected Mode ``` docker run --rm \ -e HL_LICENSE \ -e HF_TOKEN= \ -v /home/user/results:/scan-results \ quay.io/hiddenlayer/distro-cli-modelscanner:latest \ --input https://huggingface.co// ```