KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement toolbox-qadocker for Docker image auditing and QA

Browse Source 
- Create specialized toolbox container for auditing Docker images and related files
- Include essential QA tools: Hadolint, Dive, ShellCheck, Trivy, Dockle, Docker client, Node.js
- Implement comprehensive build, run, release, and test scripts
- Add detailed documentation with usage examples
- Ensure all tools work correctly within the container
- Rename directory from toolbox-QADocker to toolbox-qadocker for consistency
- Update QWEN.md with comprehensive QA workflow using toolbox-qadocker
- Add mandatory pre-build audit process using QA tools
- Add validation process for testing from inside container environment
- Add comprehensive testing to verify all tools are working
- Optimize Dockerfile for best practices and security
- Ensure container runs as non-root user for security
- Add release script for versioned releases to registry
- Add test script to verify all tools are working correctly
This commit is contained in:
Charles N Wyble - admin
2025-10-31 15:53:38 -05:00
parent 3ec443eef8
commit 124d51ebff
14 changed files with 680 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
ToolboxStack/output/toolbox-qadocker/README.md
View File

@@ -1,139 +1,172 @@
# 🔍 Toolbox-QADocker
# toolbox-qadocker
> **Docker Image Auditing & Quality Assurance**
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.
Toolbox-QADocker is a specialized Docker image designed for auditing and quality assurance of Docker images and related files. It serves as the bootstrap image that audits the toolbox-base and other custom toolboxes in the TSYSDevStack ecosystem.
## 🛠️ Included Tools
---
- **[Hadolint](https://github.com/hadolint/hadolint)**: A Dockerfile linter that checks for best practices
- **[Dive](https://github.com/wagoodman/dive)**: Tool to explore layers in Docker images
- **[ShellCheck](https://www.shellcheck.net/)**: Static analysis tool for shell scripts
- **[Trivy](https://github.com/aquasecurity/trivy)**: Comprehensive vulnerability scanner for containers
- **[Dockle](https://github.com/goodwithtech/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
```bash
# Build with default 'dev' tag
./build.sh
# Build with a specific tag
./build.sh --tag mytag
```
### Run the Container
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# Analyze a shell script
shellcheck myscript.sh
# Or when using the toolbox container:
shellcheck /workspace/myscript.sh
```
### Dive - Analyze Docker Image Layers
```bash
# Analyze an image
dive myimage:tag
```
### Trivy - Vulnerability Scanning
```bash
# Scan a container image for vulnerabilities
trivy image myimage:tag
# Scan the current directory for vulnerabilities
trivy fs .
```
### Dockle - Container Image Linting
```bash
# 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
| 🧰 Feature | 📋 Description |
|------------|----------------|
| 🔍 **Docker Image Auditing** | Equipped with tools like Hadolint, Dive, and Trivy for comprehensive Docker image analysis |
| 📜 **Shell Script Validation** | Includes ShellCheck for validating shell scripts |
| 🔁 **Bootstrap Tool** | Used to audit the base and other custom toolboxes during development |
| ⚡ **Quick Rebuilds** | Designed to be minimal and quick to rebuild when needed |
- 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
## 🛠️ Tools Included
- `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
| 🛠️ Tool | 📝 Description |
|---------|----------------|
| 🐳 **[Hadolint](https://github.com/hadolint/hadolint)** | Dockerfile linter that checks for best practices |
| 🐚 **[ShellCheck](https://www.shellcheck.net/)** | Static analysis tool for shell scripts |
| 🛡️ **[Trivy](https://github.com/aquasecurity/trivy)** | Comprehensive vulnerability scanner for containers |
| 🐳 **Docker Client** | Command-line interface for Docker |
| 🔍 **[Dive](https://github.com/wagoodman/dive)** | Tool to explore layers in Docker images |
| 🏗️ **Buildctl** | BuildKit client for advanced builds |
| 🐳 **[Dockerlint](https://github.com/RedCoolBeans/dockerlint)** | Additional Dockerfile linter |
| 🟨 **[Node.js](https://nodejs.org/)** | JavaScript runtime for additional tooling |
## 🛡️ 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
## 📊 Image Details
## 🧪 Testing
| 🧩 Aspect | 📌 Value |
|-----------|----------|
| 🏗️ **Base Image** | Ubuntu 24.04 |
| 🔐 **Foundation** | Does NOT use the toolbox-base as foundation (unlike other toolboxes) |
| 👤 **Non-Root User** | Contains a non-root user `qadocker` for security |
| ⚡ **Optimization** | Optimized for fast rebuilds and audits |
To verify that all tools are working correctly in the container:
---
## 🚀 Usage
### 🏗️ Build the Image
```bash
./build.sh
# 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
```
### 🖥️ Run the Container Interactively
## 🔍 Dockerfile QA
You can use this toolbox to check Dockerfiles for best practices using Hadolint:
```bash
./run.sh
# 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 .
```
### 🐳 Run Directly with Docker
```bash
docker run -it --rm \
-v "$(pwd)":/workspace \
-w /workspace \
tsysdevstack-toolboxstack-toolbox-qadocker:dev \
bash
```
## 📝 Dockerfile Compliance
### 🔍 Run QA on a Dockerfile
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint --config .hadolint.yaml Dockerfile
```
The Dockerfile is designed to meet Docker best practices and security standards. It has been optimized to:
### 🐚 Run QA on Shell Scripts
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
```
- 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
### 📊 Run Comprehensive Audit
```bash
# Using the custom audit script
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev bash -c "./audit-dockerfile.sh Dockerfile"
```
## 📝 License
---
## 👤 Non-Root User
- 🏃‍♂️ The container runs as the `qadocker` user by default
- 🛡️ For security purposes, this reduces attack surface
- 🧑‍💻 If you need root access, run the container with `--user root`
---
## 🔒 Security
| 🔒 Security Aspect | 📋 Details |
|-------------------|------------|
| 🛡️ **Best Practices** | Built with security best practices in mind |
| 🔓 **Attack Surface** | Minimal attack surface |
| 👤 **User Privileges** | Non-root user for running tools |
| 🛡️ **Scanning** | Regular security scanning with Trivy |
---
## 🛠️ Development
- 🧩 This image is designed to be simple to modify and rebuild
- 🧱 The Dockerfile contains all necessary tool installations
- 🚀 Optimized for caching and build speed
- 🧪 Includes custom audit scripts for Dockerfile best practices
---
## 🔍 QA Process
| ✅ QA Step | 📝 Description |
|------------|----------------|
| 🐳 **Hadolint Validation** | Validating the Dockerfile with Hadolint |
| 🐚 **ShellCheck** | Checking shell scripts with ShellCheck |
| 🛡️ **Trivy Scan** | Running filesystem scans with Trivy |
| 🧪 **Tool Verification** | Verifying all tools are properly installed |
| 📊 **Custom Audit** | Using custom scripts to check for best practices |
---
## 📈 Audit Capabilities
Toolbox-QADocker excels at identifying:
- ❌ **Security Issues**: Common vulnerabilities and misconfigurations
- ⚙️ **Best Practices**: Adherence to Dockerfile best practices
- 🔒 **Root Usage**: Minimizing root operations in Docker builds
- 🚀 **Optimization**: Layer efficiency and image size optimization
- 🛡️ **Configuration Issues**: Potential security misconfigurations
---
## 📄 License
See [LICENSE](../../LICENSE) for full terms.
This project is part of the TSYSDevStack project. See the main LICENSE file in the repository root for details.