# How to Use Docker to Scan Skills Without Installing Python Dependencies

> Scan AI skill bundles easily with the NVIDIA SkillSpector Docker image. Avoid Python dependency headaches and get started quickly on your host machine.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-06-17

---

**You can scan AI skill bundles using NVIDIA's SkillSpector Docker image without installing Python or managing dependencies on your host machine.**

The NVIDIA/SkillSpector repository provides a containerized scanner that encapsulates the entire Python runtime environment, allowing you to analyze skill bundles in an isolated environment. By leveraging a multi-stage Docker build, the container includes all necessary components while maintaining a minimal footprint and avoiding pollution of your local system.

## Understanding the Docker Multi-Stage Build

The `Dockerfile` implements a two-stage build strategy that separates build dependencies from runtime requirements, creating a clean, secure scanning environment.

### Builder Stage

The first stage uses `python:3.12-slim-bookworm` as the base image. It creates a virtual environment at `.venv`, copies the package metadata ([`pyproject.toml`](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml), [`README.md`](https://github.com/NVIDIA/SkillSpector/blob/main/README.md)) and the source tree (`src/`) into the build context, and installs the project's Python requirements as defined in [`pyproject.toml`](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml). This process occurs in lines 1-8 of the `Dockerfile`.

### Runtime Stage

The second stage starts fresh from the same slim Python image to eliminate build artifacts. It installs only essential system packages—**git** and **CA certificates**—needed for pulling remote skill bundles. The pre-built `.venv` directory is copied from the builder stage, and the `PATH` environment variable is updated so the `skillspector` entrypoint resolves correctly. This configuration is defined in lines 9-20 of the `Dockerfile`.

## Running Your First Skill Scan

The container's entrypoint is configured as `ENTRYPOINT ["skillspector"]` in the `Dockerfile`, which forwards arguments directly to the CLI module implemented in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py). The scan command implementation (lines 35-90) handles both local directories and remote Git repositories.

To scan a local skill directory, mount your code to the container's working directory `/scan`:

```bash

# Build the image once

docker build -t skillspector .

# Scan a local skill directory

docker run --rm \
  -v "$(pwd)/my-skill:/scan" \
  skillspector scan /scan \
  --format json \
  --output /scan/report.json

```

For remote repositories, no volume mount is required:

```bash
docker run --rm \
  skillspector scan https://github.com/user/my-skill \
  --no-llm \
  --format sarif \
  --output /tmp/report.sarif

```

## CLI Flags and Output Options

The `skillspector` CLI supports several flags to customize the analysis behavior:

- **`--format`**: Select output representation (`json`, `sarif`, `markdown`, or `terminal`)
- **`--output <path>`**: Write the report to a specific file path; when using bind mounts, ensure the path is inside the mounted directory to persist results locally
- **`--no-llm`**: Skip the LLM-based static analysis for faster execution using only built-in static checks
- **`--yara-rules-dir <dir>`**: Specify custom YARA rules by mounting a directory into the container

## Mounting Custom YARA Rules

To include custom security rules, mount your rules directory into the container and reference it with the `--yara-rules-dir` flag:

```bash
docker run --rm \
  -v "$(pwd)/my-skill:/scan" \
  -v "$(pwd)/custom-rules:/rules" \
  skillspector scan /scan \
  --yara-rules-dir /rules \
  --output /scan/report.json

```

This approach keeps your host system clean while allowing flexible rule configuration for specialized security scanning.

## Summary

- SkillSpector's Docker image uses a multi-stage build to create an isolated Python environment based on `python:3.12-slim-bookworm`
- The entrypoint at [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) handles both local and remote skill bundle scanning through the `scan` subcommand
- Mount local directories to `/scan` or pass URLs directly for remote analysis without volume mounts
- Use `--no-llm` for faster static-only analysis or custom YARA rules for specialized security checks
- The [`src/skillspector/graph.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/graph.py) module orchestrates the LangGraph workflow when LLM-based analysis is enabled

## Frequently Asked Questions

### Do I need Python installed on my host machine to use SkillSpector?

No. The Docker image contains a complete Python 3.12 virtual environment with all dependencies pre-installed according to the [`pyproject.toml`](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml) specifications. You only need Docker installed on your host system to run the scanner.

### How do I save scan reports to my local machine?

When scanning local directories, mount your project folder to `/scan` and specify an output path inside that directory (for example, `--output /scan/report.json`). The report will be written to your local filesystem through the bind mount. For remote scans, you can mount an additional volume specifically for output files.

### Can I scan private Git repositories with the Docker container?

Yes. The runtime stage installs git and CA certificates specifically to support remote repository access. You may need to pass authentication tokens or SSH keys via environment variables or mounted volumes depending on your repository configuration, as the container includes the necessary tools to clone remote bundles.

### What is the difference between using `--no-llm` and the default scan mode?

The `--no-llm` flag disables the LangGraph-based LLM analysis implemented in [`src/skillspector/graph.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/graph.py) and runs only the built-in static security checks. This produces faster results without requiring API keys for external language models, while the default mode includes both static checks and AI-powered analysis for deeper inspection.