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

130
ToolboxStack/QWEN.md
View File

@@ -19,7 +19,7 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
- toolbox-base/ (base dev container)
- toolbox-template/ (template for new toolboxes)
- Generated toolboxes (toolbox-*/ directories)
- PROMPT files for AI collaboration
- QWEN.md files for AI collaboration
## Current Directory Tree
```
@@ -61,6 +61,11 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
- **PROMPT files**: Guidance for AI collaboration in various components
## Build and Release Workflow
- Pre-build audit: Before building any Docker images, run comprehensive audits using the toolbox-qadocker image:
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile`
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck *.sh`
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev trivy fs --offline-scan .`
- `docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .`
- Default build workflow: `./build.sh` produces a `:dev` tag; `./release.sh <semver>` (clean git tree required) rebuilds and pushes `:dev`, `:release-current`, and `v<semver>` (use `--dry-run`/`--allow-dirty` to rehearse).
- Downstream Dockerfiles should inherit from `:release-current` by default; pin to version tags when reproducibility matters.
@@ -81,6 +86,16 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
- Coordinate all git operations (commits and pushes) for repository consistency
- Follow the README maintenance guide in collab/README-Maintenance.md to keep documentation up to date
## Pre-Build Audit Workflow
Before creating or updating any toolbox images, I must perform comprehensive audits using the toolbox-qadocker image:
1. **Dockerfile Audit**: Run Hadolint to check for best practices and issues
2. **Shell Script Audit**: Run ShellCheck to validate shell scripts
3. **Security Scan**: Run Trivy to identify vulnerabilities
4. **Container Linting**: Run Dockle to check for security best practices
5. **Fix Issues**: Address all flagged issues before proceeding to build
6. **Re-Audit**: Re-run audits to confirm fixes were effective
## Git Operations
- I am now responsible for all git operations (commits and pushes) for the ToolboxStack component
- All changes should be committed with clear, descriptive commit messages
@@ -101,18 +116,19 @@ I am the QWEN instance operating in the ToolboxStack component of the TSYSDevSta
## Development Cycle
I should automatically handle the full development cycle of toolboxes:
1. **Building**: Use build.sh scripts to build toolbox images
2. **Testing**: Run comprehensive tests to verify functionality
3. **Documentation**: Keep README.md and other docs up to date
4. **Version Control**: Commit changes frequently with descriptive messages
5. **Rebuilding**: When updating the base, rebuild all dependent toolboxes
1. **Auditing**: Use the toolbox-qadocker image to check Dockerfiles and shell scripts for best practices, security issues, and common errors before building
2. **Building**: Use build.sh scripts to build toolbox images
3. **Testing**: Run comprehensive tests to verify functionality, including validation from within the container
4. **Documentation**: Keep README.md and other docs up to date
5. **Version Control**: Commit changes frequently with descriptive messages
6. **Rebuilding**: When updating the base, rebuild all dependent toolboxes
## Toolbox Management
I can easily create new toolboxes or update existing ones:
- **Create new toolbox**: Use NewToolbox.sh script with desired name
- **Update existing toolbox**: Modify Dockerfile, aqua.yaml, or other config files
- **Update base and rebuild**: Modify toolbox-base, then rebuild all dependent toolboxes
- **Testing**: Always test toolboxes after changes
- **Testing**: Always test toolboxes after changes, including validation from within the container where all tools are available
## Parallel QA Chat
I should be aware that there is a parallel chat called QA-ToolboxStack whose job is to conduct in-depth audits of the work that the ToolboxStack chat is doing. I should:
@@ -202,7 +218,20 @@ As part of my role in maintaining the ToolboxStack, I may conduct ongoing audits
- Security best practices
- Docker development environment best practices
- Best common practices for (dockerized) development/tooling stacks
- Assessment of all existing toolboxes (base, DocStack, QADocker, and any others)
- Assessment of all existing toolboxes (base, DocStack, qadocker, and any others)
### Pre-Build Audit Process
Before building any Docker images, I must run comprehensive audits using the toolbox-qadocker image to check for:
- Dockerfile best practices violations (with Hadolint)
- Shell script issues (with ShellCheck)
- Security vulnerabilities (with Trivy)
- Container image security issues (with Dockle)
- Common configuration errors
- Potential build failures
All of these tools should be used to flag as many issues as possible before starting a container image build to avoid running into problems later.
### Audit Process
@@ -216,7 +245,7 @@ The LLM-optimized reports are designed to be fed to other Qwen chats for impleme
### Using toolbox-qadocker for audits
When conducting Dockerfile audits, please use the `toolbox-qadocker:release-current` image which includes the following tools for comprehensive auditing:
When conducting Dockerfile audits, please use the `tsysdevstack-toolboxstack-toolbox-qadocker:dev` image (or build it locally) which includes the following tools for comprehensive auditing:
- **Hadolint**: Dockerfile linter that checks for best practices
- **ShellCheck**: Static analysis tool for shell scripts
@@ -224,20 +253,72 @@ When conducting Dockerfile audits, please use the `toolbox-qadocker:release-curr
- **Docker Client**: Command-line interface for Docker
- **Dive**: Tool to explore layers in Docker images
- **Buildctl**: BuildKit client for advanced builds
- **Dockerlint**: Additional Dockerfile linter
- **Dockle**: Container image linter for security best practices
- **Node.js**: JavaScript runtime for additional tooling
> ⚠️ **Important**: Never modify images that have a `release-current` tag already in place. Always iterate and test in `:dev` first, then use the release.sh script to promote to `:release-current` when ready.
To run audits using the toolbox-qadocker:
```bash
# Example: Run Hadolint on a Dockerfile
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current hadolint Dockerfile
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile
# Example: Run ShellCheck on script files
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current shellcheck script.sh
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
# Example: Run Trivy for vulnerability scanning
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current trivy fs --offline-scan .
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev trivy fs --offline-scan .
# Example: Run Dockle for container image linter
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .
# Example: Run comprehensive audit on current directory
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev /bin/bash -c "hadolint Dockerfile 2>/dev/null || echo 'No Dockerfile found or hadolint issues found'; shellcheck *.sh 2>/dev/null || echo 'No shell scripts found or shellcheck issues found'; trivy fs --offline-scan . 2>/dev/null || echo 'Trivy scan completed'; dockle . 2>/dev/null || echo 'Dockle scan completed'"
```
> 🧪 **Audit Compliance**: Both Hadolint and Dockle compliance are now mandatory for all Dockerfiles in the TSYSDevStack project and must be part of the audit process.
### Validation Process
During testing, I must also validate functionality from inside the container where the tools are available. This requires mounting the working directory as the container's working directory for the scanning tools to run successfully:
```bash
# Example: Run validation tools from inside the container
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile
```
### Testing Inside Container
Since the QA tools are installed inside the toolbox-qadocker container, I must always test from inside the container environment. This is necessary because:
- The tools (Hadolint, ShellCheck, Trivy, Dockle, etc.) are only available inside the container
- The environment may differ from the host system
- Consistent testing environment ensures reliable results
To test effectively from inside the container:
1. Mount the directory containing the files to be tested to `/workspace`
2. Set the working directory to `/workspace` using `-w /workspace`
3. Run the appropriate tool with its specific arguments
4. Check the output for any issues that need to be addressed before proceeding
Example workflow:
```bash
# Navigate to directory containing files to be tested
cd /path/to/files
# Run Dockerfile linting
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint Dockerfile
# Run shell script analysis
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck *.sh
# Run security scanning
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev trivy fs --offline-scan .
# Run container image linting
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev dockle .
```
### Beautiful Documentation Principle
@@ -262,6 +343,16 @@ The goal is to make documentation that is:
When updating documentation, please ensure it follows these principles to maintain a high standard across all ToolboxStack documentation.
### Documentation Files
Documentation in this project is now maintained using:
- 📄 **QWEN.md**: Primary AI agent documentation and instructions
- 📋 **README.md**: User-facing documentation for each component
- 📝 **WORKLOG.md**: Detailed work logs and change history
The use of PROMPT files has been discontinued in favor of the QWEN.md approach for maintaining AI agent instructions and project context.
### Advisory Role
In addition to audits, I can provide advice on:
@@ -300,4 +391,15 @@ The ToolboxStack is for "inner loop" operations (edit/compile/test) only.
There are other stacks for:
- Build/packaging/release operations
- Support functions (like atuin/mailhog etc)
- Support functions (like atuin/mailhog etc)
## Mandatory QA Process
The toolbox-qadocker image is now an integral part of the development workflow with mandatory usage:
1. **Before any Docker build**, all Dockerfiles must be validated with Hadolint
2. **Before any shell script execution**, scripts must be validated with ShellCheck
3. **Before releasing any image**, security scans must be performed with Trivy and Dockle
4. **As part of regular maintenance**, audits are performed using the automated script
5. **For all new toolboxes**, the QA process is mandatory before they can be released
This ensures that all toolboxes meet the highest standards of security, reliability, and best practices.