How to Run SkillSpector Using Docker: Complete Setup Guide

SkillSpector ships a minimal multi-stage Docker image that lets you run security scans without installing Python dependencies locally by mounting your code to /scan and invoking the skillspector CLI as the container entrypoint.

NVIDIA/SkillSpector is an AI security scanner designed to analyze skill bundles for vulnerabilities. If you need to run SkillSpector using Docker to avoid Python environment management, the repository provides a production-ready container built via an optimized multi-stage Dockerfile.

Understanding the SkillSpector Docker Architecture

The containerization strategy defined in the repository root Dockerfile uses a multi-stage build to minimize image size and eliminate build dependencies from the final runtime.

Builder Stage

The first stage uses python:3.12-slim-bookworm as the base image. According to lines 1-8 of the Dockerfile, this stage copies the project source, creates a virtual environment, and installs the package with pip install --no-cache-dir . to ensure a clean, cache-free installation.

Runtime Stage

The second stage copies the pre-built virtual environment from the builder, sets PATH="/app/.venv/bin:$PATH" so the skillspector command is available system-wide, and establishes /scan as the working directory (lines 9-15). This design ensures the runtime image contains only the necessary binaries without build tools.

Entrypoint Configuration

The container declares skillspector as its entrypoint in lines 16-17 of the Dockerfile. This entrypoint invokes the CLI implementation found in src/skillspector/cli.py, meaning any arguments you append to docker run are forwarded directly to the SkillSpector command.

Building the Docker Image

You can build the image manually or use the convenience target in the provided Makefile.

# Build manually with a specific tag

docker build -t skillspector .

# Or use the Makefile shortcut

make docker-build

Running SkillSpector Scans in Docker

To analyze skills, mount a host directory to the container's /scan path and specify the target path relative to that mount point.

Static Analysis Without LLM

For air-gapped environments or quick static checks, disable LLM analysis using the --no-llm flag:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

LLM-Enabled Scans Using Environment Files

For enhanced analysis requiring LLM capabilities, create an .env file and mount it via --env-file:

# Create environment file

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

# Run with credentials

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

Passing Credentials via Command Line

Alternatively, inject credentials directly using the -e flag to reference host environment variables:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

Exporting Scan Results

To capture reports on your host system, specify an output path relative to the mounted /scan directory:

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

Creating a Persistent Docker Alias

For frequent use, create a shell alias that encapsulates the standard volume mount:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'

# Usage

skillspector-docker scan ./my-skill/ --no-llm

Summary

• The multi-stage Dockerfile (lines 1-17) creates a minimal runtime image with the skillspector CLI available on the system PATH at /app/.venv/bin
• Mount your project directory to /scan to make files accessible inside the container environment
• Pass LLM credentials via --env-file or -e flags, as the image contains no hardcoded API keys
• Use --no-llm for offline environments requiring only static analysis capabilities
• The Makefile provides make docker-build as a convenient shortcut for image compilation

Frequently Asked Questions

Do I need Python installed locally to use the SkillSpector Docker image?

No. The Docker image is completely self-contained. The builder stage compiles everything into a virtual environment inside the container, and the runtime stage includes only the necessary Python binaries and dependencies. You only need Docker installed on your host system to run SkillSpector.

How do I scan a skill directory located outside my current working directory?

Mount the specific directory to /scan using the absolute path in the -v flag. For example: docker run --rm -v "/path/to/skill:/scan" skillspector scan /scan/. The container treats /scan as its working directory, so adjust your target paths accordingly when referencing files inside the container.

Can I integrate the SkillSpector Docker image into CI/CD pipelines?

Yes. The container exits with appropriate status codes based on scan results, making it suitable for automated pipelines. Mount your repository and add the --format json flag to parse results programmatically in subsequent pipeline steps. Ensure you inject LLM API keys via environment variables if running enhanced scans in automated environments.

Where is the container's entrypoint defined in the source code?

The entrypoint is defined in the final lines of the Dockerfile (lines 16-17) and points to the skillspector command. This command is implemented in src/skillspector/cli.py, which handles argument parsing and orchestrates the scanning logic. When you append arguments to docker run, they are passed directly to this CLI implementation.

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