Docker

vigil can run inside Docker containers for reproducible environments, CI pipelines, or integration into existing Docker-based workflows.

Recommended base image

FROM python:3.12-slim

RUN pip install --no-cache-dir vigil-ai-cli

WORKDIR /app
ENTRYPOINT ["vigil"]
CMD ["--help"]

Build

docker build -t vigil .

Usage

# Scan a local directory
docker run --rm -v $(pwd):/app vigil scan src/

# With JSON format
docker run --rm -v $(pwd):/app vigil scan src/ -f json

# With config file
docker run --rm -v $(pwd):/app vigil scan src/ -c .vigil.yaml

# Save report
docker run --rm -v $(pwd):/app vigil scan src/ -f sarif -o vigil.sarif

---

Production Dockerfile

A more robust Dockerfile for production or distribution use:

FROM python:3.12-slim AS base

# Metadata
LABEL maintainer="vigil team"
LABEL description="Security scanner for AI-generated code"
LABEL version="0.3.0"

# Create non-root user
RUN groupadd -r vigil && useradd -r -g vigil vigil

# Install vigil
RUN pip install --no-cache-dir vigil-ai-cli

# Working directory
WORKDIR /scan

# Cache directory
RUN mkdir -p /home/vigil/.cache/vigil/registry && \
    chown -R vigil:vigil /home/vigil

# Switch to non-root user
USER vigil

ENTRYPOINT ["vigil"]
CMD ["scan", "."]

Advantages of this configuration

• Non-root user: Security best practice. vigil does not need elevated privileges.
• --no-cache-dir: Reduces image size.
• WORKDIR /scan: Clear mount point for the code to scan.
• Cache directory: Pre-created with correct permissions.

---

Docker Compose usage

For integration into projects that use Docker Compose:

# docker-compose.yaml
services:
  vigil:
    build:
      context: .
      dockerfile: Dockerfile.vigil
    volumes:
      - .:/scan:ro
      - vigil-cache:/home/vigil/.cache/vigil
    command: scan src/ --fail-on high -f json -o /scan/vigil-report.json

volumes:
  vigil-cache:

The vigil-cache volume persists the registry cache between runs, avoiding repeated HTTP requests.

---

Offline mode in Docker

For runners without internet access or in restricted networks:

docker run --rm -v $(pwd):/scan --network none vigil scan src/ --offline

--network none disables the container’s network, ensuring no external requests are made. Combined with --offline, vigil runs only static checks.

---

Registry cache

Persisting cache between runs

# Create volume for cache
docker volume create vigil-cache

# Use the volume
docker run --rm \
  -v $(pwd):/scan \
  -v vigil-cache:/home/vigil/.cache/vigil \
  vigil scan src/

Pre-warming the cache

If you want to pre-load the cache before an offline scan:

# First run: with network, to populate cache
docker run --rm \
  -v $(pwd):/scan \
  -v vigil-cache:/home/vigil/.cache/vigil \
  vigil deps

# Subsequent runs: without network, using cache
docker run --rm \
  -v $(pwd):/scan \
  -v vigil-cache:/home/vigil/.cache/vigil \
  --network none \
  vigil scan src/

---

CI with Docker

GitHub Actions with Docker

jobs:
  vigil:
    runs-on: ubuntu-latest
    container:
      image: python:3.12-slim
    steps:
      - uses: actions/checkout@v4
      - run: pip install vigil-ai-cli
      - run: vigil scan src/ --fail-on high

GitLab CI with Docker

vigil:
  image: python:3.12-slim
  stage: test
  script:
    - pip install vigil-ai-cli
    - vigil scan src/ -f junit -o report.xml
  artifacts:
    reports:
      junit: report.xml

With a custom pre-built image

To avoid installing vigil on every run:

# GitLab CI
vigil:
  image: registry.example.com/tools/vigil:latest
  stage: test
  script:
    - vigil scan src/ --fail-on high

---

Multi-stage build

If vigil is part of a larger build pipeline:

# Stage 1: Security scan
FROM python:3.12-slim AS security
RUN pip install --no-cache-dir vigil-ai-cli
WORKDIR /app
COPY . .
RUN vigil scan src/ --fail-on high

# Stage 2: Actual app build
FROM python:3.12-slim AS production
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["python", "-m", "app"]

If vigil finds issues (exit code 1), the build fails at the first stage and the production image is not built. This acts as a quality gate in the build process.

---

Image sizes

Estimated image sizes:

Base	Approx. size
python:3.12-slim + vigil	~180 MB
python:3.12-alpine + vigil	~120 MB
python:3.12 + vigil	~1 GB

Using python:3.12-slim is recommended as a balance between size and compatibility. Alpine may cause issues with some compiled dependencies.

---

Best practices

1. Mount code as read-only (-v $(pwd):/scan:ro): vigil does not modify files. Read-only mounting prevents accidental writes.

2. Persist the registry cache: Use a Docker volume or a host directory to avoid repeated HTTP requests between runs.

3. Use a non-root user: vigil does not need elevated privileges.

4. Pin the vigil version: In production Dockerfiles, use pip install vigil-ai-cli==0.3.0 instead of vigil-ai-cli for reproducible builds.

5. Separate scan from build: In multi-stage builds, run vigil as an independent stage so it fails fast without wasting resources on later stages.

6. Output to files inside the volume: When using --output, make sure the output file is in a mounted directory so the report can be accessed outside the container.