TSYSDevStack/ToolboxStack/output/toolbox-qadocker/README.md

toolbox-qadocker

This is a specialized toolbox container for performing audit and quality assurance work on Docker images and related files in the TSYSDevStack project. It includes essential tools for Dockerfile linting, shell script validation, container auditing, and security scanning.

🛠️ Included Tools

• Hadolint: A Dockerfile linter that checks for best practices
• Dive: Tool to explore layers in Docker images
• ShellCheck: Static analysis tool for shell scripts
• Trivy: Comprehensive vulnerability scanner for containers
• Dockle: Container image linter for security best practices
• Docker Client: Command-line interface for Docker
• Node.js: JavaScript runtime for additional tooling

🚀 Quick Start

Build the Image

# Build with default 'dev' tag
./build.sh

# Build with a specific tag
./build.sh --tag mytag

Run the Container

# Run interactively with current directory mounted
./run.sh

# Run with Docker socket access (to use Docker from inside container)
./run.sh --with-docker

# Run with a specific tag
./run.sh --tag mytag

Release (Push to Registry)

# Build and push with version tag (requires clean git tree)
./release.sh --version v0.1.0

# Build and push with version tag (allowing dirty git tree)
./release.sh --version v0.1.0 --allow-dirty

# Dry run to test the process without actually pushing
./release.sh --version v0.1.0 --dry-run

🔍 Using QA Tools

Hadolint - Dockerfile Linting

# Lint a Dockerfile
docker run --rm -i hadolint/hadolint < Dockerfile

# Or when using the toolbox container with current directory mounted:
hadolint Dockerfile

ShellCheck - Shell Script Analysis

# Analyze a shell script
shellcheck myscript.sh

# Or when using the toolbox container:
shellcheck /workspace/myscript.sh

Dive - Analyze Docker Image Layers

# Analyze an image
dive myimage:tag

Trivy - Vulnerability Scanning

# Scan a container image for vulnerabilities
trivy image myimage:tag

# Scan the current directory for vulnerabilities
trivy fs .

Dockle - Container Image Linting

# Lint a container image
dockle myimage:tag

# Or run on current directory
dockle .

🏗️ Project Context

The toolbox-qadocker is designed to be a minimal, fast-to-rebuild image specifically for auditing and validating Docker images and related files in the TSYSDevStack ecosystem. Unlike other toolboxes, it does not inherit from toolbox-base and instead uses a clean Ubuntu base with only the essential QA tools installed.

🎯 Purpose

• Audit Dockerfiles for best practices and security issues
• Validate shell scripts with ShellCheck
• Analyze Docker image layers with Dive
• Scan for vulnerabilities with Trivy
• Check image security with Dockle
• Support AI CLI agents in container image creation

📁 Directory Structure

• Dockerfile: Defines the container image
• build.sh: Builds the container image
• run.sh: Runs the container with appropriate settings
• release.sh: Builds and pushes container images with multiple tags
• test.sh: Test script to verify all tools are working

🛡️ Security

• Runs as a non-root user (qadocker) by default
• Contains only essential tools needed for QA work
• Designed to be minimal and fast to rebuild if security issues are discovered

🧪 Testing

To verify that all tools are working correctly in the container:

# Run the test script to verify all tools
./test.sh

# Or run the test script inside the container
docker run --rm -v $(pwd)/test.sh:/test.sh tsysdevstack-toolboxstack-toolbox-qadocker:dev bash /test.sh

🔍 Dockerfile QA

You can use this toolbox to check Dockerfiles for best practices using Hadolint:

# Run Hadolint on a Dockerfile
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile

# Run ShellCheck on shell scripts
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck your_script.sh

# Run Trivy for vulnerability scanning
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev trivy fs --offline-scan .

# Run Dockle for container image linter
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .

📝 Dockerfile Compliance

The Dockerfile is designed to meet Docker best practices and security standards. It has been optimized to:

• Use minimal base image (Ubuntu 24.04)
• Install packages with --no-install-recommends to reduce bloat
• Download packages with quiet mode to reduce output
• Create a non-root user for running tools
• Follow security best practices for container images
• Comply with Hadolint and Dockle recommendations where possible

📝 License

This project is part of the TSYSDevStack project. See the main LICENSE file in the repository root for details.