How to Use Docker to Scan Skills Without Installing Python Dependencies

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, README.md) and the source tree (src/) into the build context, and installs the project's Python requirements as defined in 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. 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:

# 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:

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:

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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}