Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Docker deployment provides an enterprise-ready, containerized environment for running the Unified Security Scanner. It ensures that the scanner and its various underlying dependencies—such as Semgrep and TruffleHog—are available in a consistent, isolated environment, reducing the "command not found" issues often encountered during manual local installations.
The containerized approach supports multi-phase scanning, AI-enhanced validation, and seamless integration into various CI/CD environments by providing a pre-configured image containing the Node.js 18+ runtime and necessary security tools.
Sources: README.md:46-50, QUICK_START.md:315-325
Image Architecture and Components
The Docker image for the Unified Security Scanner is built to orchestrate multiple security engines and analysis phases. It includes the core scanning engine, the CLI interface, and the required system-level binaries for third-party tools.
Key Environment Components
- Runtime: Node.js 18.0.0 or higher.
- Package Manager: pnpm 8+ (used during the build phase).
- Security Tools: Built-in integrations for Semgrep and TruffleHog.
- AI Integration: Support for OpenAI, Anthropic, and AWS Q Developer via environment variables.
Sources: README.md:12-25, QUICK_START.md:20-35, package.json:34-36
Multi-Phase Execution Flow
The following diagram illustrates how the Dockerized scanner processes a target directory through its three primary phases.
The workflow logic starts with traditional SAST filters before progressing to AI-validated iterations to reduce false positives to below 5%.
Sources: README.md:16-25, README.md:86-100
Deployment Methods
Registry-Based Deployment (Recommended)
Users can pull the official production image directly from the GitHub Container Registry. This is the fastest method for CI/CD integration.
docker pull ghcr.io/enhanced-scanner/cli:latest
Sources: README.md:49-50
Building from Source
For custom rules or specialized security policies, the image can be built locally using the provided project structure and TypeScript configurations.
| Step | Command | Description |
|---|---|---|
| Clone | git clone <repo-url> | Retrieve source code and rules. |
| Install | pnpm install | Install engine dependencies. |
| Build | pnpm build | Compile TypeScript to JavaScript. |
| Image | docker build -t scanner . | Create the local container image. |
Sources: QUICK_START.md:45-55, CONTRIBUTING.md:11-16, package.json:8-12
Container Configuration
The container behavior is governed by environment variables and volume mounts. Configuration can be passed via a .securityrc.json file mounted into the container.
Configuration Options
The following settings are typically defined in the configs/default.json or a custom .securityrc.json mounted at runtime.
| Parameter | Type | Default | Description |
|---|---|---|---|
tools.semgrep.enabled | Boolean | true | Enables code analysis. |
scan.exclude | Array | ["**/node_modules/**"] | Directories to ignore. |
output.dir | String | "./reports" | Destination for scan results. |
severity.failOn | Array | ["CRITICAL", "HIGH"] | Severities that trigger exit code 1. |
Sources: configs/default.json:2-37, QUICK_START.md:230-245
Sequence of a Containerized Scan
The sequence diagram below shows the interaction between the User, the Docker CLI, and the internal Scanner Orchestrator.
The orchestrator embraces non-determinism by running three iterations during Phase 2 to ensure high accuracy.
Sources: README.md:113-118, README.md:200-210, CONTRIBUTING.md:22-25
CI/CD Pipeline Integration
Docker deployment is optimized for GitHub Actions and other CI environments where external tools might not be pre-installed.
- name: Run Enhanced Security Scan
run: |
docker run --rm \
-e OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} \
-v ${{ github.workspace }}:/src \
enhanced-scanner:latest scan /src --format sarif
Sources: README.md:233-245
Troubleshooting Docker Scans
- Memory Limits: For large projects (e.g., >10k files), the container may require increased memory. Default configurations recommend at least 8GB RAM for CodeQL-heavy scans.
- Permission Denied: Ensure the Docker user has read access to the mounted volume. Using
nodeexplicitly to run the entrypoint is recommended for cross-platform compatibility. - Missing AI Validation: Ensure
OPENAI_API_KEYor appropriate provider keys are passed as environment variables (-e).
Sources: README.md:135-140, QUICK_START.md:370-385, SECURITY_REVIEW.md:40-50
Docker deployment encapsulates the complex 3-phase scanning strategy—SAST, AI validation, and deep dives—into a portable unit, ensuring a consistent <5% false positive rate across different development and production environments.
Sources: README.md:5-10, CHANGELOG.md:11-15