🧊 The next generation AI-Powered Docker Security Analyzer 📦

GitHub 🔹 Docker Hub 🔹 PyPI Hub 🔹 LinkedIn 🔹 Twitter / X

---

🔐 What is DockSec?

DockSec is an Open Source, AI-powered Docker Security Analyzer that helps developers and DevSecOps teams detect, prioritize, and remediate security issues in Dockerfiles and container images.

It combines trusted static analysis tools like Trivy, Hadolint, and Docker Scout with a powerful AI engine (LangChain + OpenAI GPT-4) to provide actionable security insights, remediation suggestions, and human-readable reports.

Unlike traditional scanners that overwhelm users with raw output, DockSec focuses on developer-first security — delivering context-aware recommendations, automated security scoring, and professional reports in HTML, PDF, JSON, and CSV formats. It seamlessly integrates into CI/CD pipelines or can be run locally via a simple CLI with built-in retry logic and rate limiting for reliability.

❓Why DockSec?

Most Docker security tools do one thing well — scan. But they often fall short where it matters most: prioritizing what’s important, explaining why it matters, and guiding you toward a fix.

Here’s why DockSec is different:

✅ Smart + Actionable: Combines traditional scanners with AI-driven remediation suggestions using LangChain + OpenAI GPT-4.

🚀 Developer-First: Clear, prioritized output with progress indicators. Designed to work in CI/CD, pre-commit hooks, and developer environments.

📊 Security Score & Reports: Automatically calculates security scores (0-100) and generates professional reports in multiple formats (HTML, PDF, JSON, CSV).

🔧 Flexible CLI: Run full scans, AI-only analysis, scan-only modes, or image-only scanning with simple commands.

🧠 Shift Left, Intelligently: Helps developers fix security issues early with actionable error messages and troubleshooting guidance.

🔄 Production-Ready: Built-in retry logic with exponential backoff, rate limiting handling, and robust error recovery.

⚡ Performance: Real-time progress indicators, optimized scanning, and configurable timeouts for long-running operations.

🌟 Key Features

Security Scanning

• Multi-Tool Integration: Leverages Trivy, Hadolint, and Docker Scout for comprehensive vulnerability detection
• Severity-Based Filtering: Automatically prioritizes CRITICAL and HIGH vulnerabilities
• CVE Detection: Identifies known vulnerabilities with detailed CVE information and CVSS scores
• Package Analysis: Tracks vulnerable packages with version information

AI-Powered Analysis

• Intelligent Recommendations: OpenAI GPT-4 powered suggestions for security improvements
• Automated Security Scoring: 0-100 security score calculation based on findings
• Best Practice Guidance: Context-aware recommendations for Dockerfile optimization
• Remediation Steps: Actionable fix suggestions with implementation guidance

Reporting & Visualization

• Multi-Format Reports: Generate reports in JSON, CSV, PDF, and HTML formats
• Professional Formatting: Clean, well-structured reports with severity-based organization
• Interactive HTML: Web-based reports with styling and easy navigation
• Machine-Readable Output: JSON format for integration with other tools

Developer Experience

• Progress Indicators: Real-time progress bars for long-running scans
• Clear Error Messages: Actionable error messages with troubleshooting steps
• Multiple Scan Modes: AI-only, scan-only, image-only, or full analysis
• Configurable Timeouts: Adjust timeouts for different scanning scenarios

Production-Ready Reliability

• Retry Logic: Automatic retry with exponential backoff for transient failures
• Rate Limiting: Intelligent handling of OpenAI API rate limits
• Error Recovery: Graceful handling of network issues and API failures
• Robust Logging: Comprehensive logging for debugging and monitoring

Flexibility & Integration

• CLI Interface: Simple command-line interface for local development
• CI/CD Ready: Easy integration into continuous integration pipelines
• Environment Configuration: Comprehensive configuration via environment variables
• No-API-Key Mode: Scan-only mode works without OpenAI API key

🧩 Architecture Diagram

Here’s how DockSec works behind the scenes:

• Input: Dockerfile + optional Docker image
• Static Analysis: Trivy, Hadolint, Docker Scout for comprehensive vulnerability detection
• AI Layer: LangChain + OpenAI GPT-4 for intelligent insights and automated security scoring
• Output: Multi-format security reports (PDF, HTML, JSON, CSV) with severity-based organization
• Modes: Full scan, AI-only, scan-only, or image-only modes
• Reliability: Automatic retry with exponential backoff, rate limiting support, configurable timeouts

🚀 Installation

You can install DockSec via PyPI

pip install docksec

OR You can install DockSec using Python virtual environment

python -m venv env

# On Windows
env\Scripts\activate

# On macOS/Linux
source env/bin/activate

pip install -e .

This will install the DockSec using setup.py from local files.

To completely use the AI scanning of DockSec, you have to setup the OPENAI-API-KEY

• 🔹 PowerShell (Windows): $env:OPENAI_API_KEY = "your-secret-key"

• 🔹 Command Prompt (CMD on Windows): set OPENAI_API_KEY=your-secret-key

• 🔹 Bash/Zsh (Linux/macOS): export OPENAI_API_KEY="your-secret-key"

• 🔹 Or create a .env file with: OPENAI_API_KEY=your-secret-key

The following dependencies will be automatically installed:

• langchain - AI orchestration framework
• langchain-openai - OpenAI integration for LangChain
• python-dotenv - Environment variable management
• pandas - Data manipulation for reports
• tqdm - Progress bars for long operations
• colorama - Cross-platform colored terminal output
• rich - Advanced terminal formatting and progress indicators
• fpdf2 - PDF report generation
• tenacity - Retry logic with exponential backoff
• setuptools - Package management

Congratulations, you can now explore and use DockSec! 🎉

Configuration Options

DockSec supports configuration via environment variables. Create a .env file in your project root:

# Required for AI features
OPENAI_API_KEY=your-secret-key

# Optional: Customize LLM settings
LLM_MODEL=gpt-4o  # Default model
LLM_TEMPERATURE=0.0  # Response randomness (0-1)
LLM_REQUEST_TIMEOUT=60  # Request timeout in seconds
LLM_MAX_RETRIES=2  # Number of retries for failed requests

# Optional: Tool timeouts (in seconds)
DOCKER_IMAGE_INSPECT_TIMEOUT=30
HADOLINT_TIMEOUT=300
TRIVY_SCAN_TIMEOUT=600
DOCKER_SCOUT_TIMEOUT=300

# Optional: Retry configuration
RETRY_STOP_ATTEMPT=3  # Maximum retry attempts
RETRY_WAIT_MULTIPLIER=1  # Exponential backoff multiplier
RETRY_WAIT_MIN=2  # Minimum wait time between retries
RETRY_WAIT_MAX=10  # Maximum wait time between retries

📝 How to Use DockSec (CLI)

After installation, you can use DockSec with a simple command:

docksec path\to\Dockerfile

Command-Line Options:

Option	Description
dockerfile	Path to the Dockerfile to analyze (optional when using --image-only)
-i, --image	Docker image name to scan (e.g., myimage:latest)
-o, --output	Output file for the report (default: security_report.txt)
--ai-only	Run only AI-based recommendations (requires Dockerfile)
--scan-only	Run only Dockerfile/image scanning (no AI analysis)
--image-only	Scan only the Docker image without Dockerfile analysis

Usage Examples:

# Basic analysis (Dockerfile + AI recommendations)
docksec path/to/Dockerfile

# Full analysis: Dockerfile + Docker image scanning + AI
docksec path/to/Dockerfile -i myimage:latest

# AI-only mode: Get recommendations without security scanning
docksec path/to/Dockerfile --ai-only

# Scan-only mode: Security scanning without AI (works without OpenAI API key)
docksec path/to/Dockerfile -i myimage:latest --scan-only

# Image-only mode: Scan Docker image without Dockerfile analysis
docksec --image-only -i myimage:latest

# Custom output file
docksec path/to/Dockerfile -o custom_report.txt

What Gets Generated:

DockSec automatically generates comprehensive reports in the results/ directory:

• JSON Report (<image>_json.json) - Machine-readable vulnerability data
• CSV Report (<image>_csv.csv) - Spreadsheet-friendly vulnerability list
• PDF Report (<image>_pdf.pdf) - Professional formatted security report
• HTML Report (<image>_html.html) - Interactive web-based report with styling
• Text Report (security_report.txt) - Human-readable summary with AI insights
• Security Score - Automated 0-100 rating based on findings

Features in Action:

• Progress Indicators: Real-time progress bars show scan status

• Error Recovery: Automatic retry with exponential backoff for API calls

• Rate Limiting: Intelligent handling of OpenAI API rate limits

• Actionable Messages: Clear error messages with troubleshooting steps

• Severity Filtering: Focus on CRITICAL and HIGH vulnerabilities

• Best Practices: AI-powered recommendations for Dockerfile optimization

  • Legacy Usage

You can still use the original commands:

# For AI-based recommendations
python .\main.py "path\to\your\dockerfile"

# For scanning both Dockerfile and images
python docker_scanner.py <dockerfile_path> <image_name> [severity]
# Example: python docker_scanner.py .\Dockerfile myapp:latest CRITICAL,HIGH

• External Tools Setup

To check the Dockerfile as well as images for vulnerabilities, you need to setup Trivy and hadolint:

python .\setup_external_tools.py

For manual installation, refer to Trivy and hadolint documentation.

🔧 Troubleshooting

Common Issues

Problem: [ERROR] No OpenAI API Key provided

• Solution: Set your OpenAI API key as an environment variable or in a .env file
• Alternative: Use --scan-only mode which doesn't require an API key

Problem: Hadolint not found in PATH

• Solution: Install Hadolint using the setup script: python setup_external_tools.py
• Manual: Follow Hadolint installation guide

Problem: Trivy scan timed out

• Solution: Increase timeout in .env: TRIVY_SCAN_TIMEOUT=1200
• Alternative: Scan smaller images or check network connectivity

Problem: OpenAI API rate limit errors

• Solution: DockSec automatically retries with exponential backoff
• Manual: Configure retry settings in .env file
• Alternative: Wait a few minutes and retry, or upgrade your OpenAI plan

Problem: Reports not generating

• Solution: Check the results/ directory permissions
• Manual: Ensure the directory exists: mkdir results

Debug Mode

For detailed logging, set the log level:

export LOG_LEVEL=DEBUG
docksec path/to/Dockerfile

Getting Help

If you encounter issues:

1. Check the logs in the console output
2. Review error messages - they include troubleshooting steps
3. Open an issue with:
   • DockSec version
   • Command used
   • Error message
   • Operating system

🎬 Demo Video

☝️ Need Help or Want to Provide Feedback?

If you encounter any problems, we will be happy to support you wherever we can. For bugs, issues or feature requests feel free to open an issue. We are happy to assist you with anything related to the project.

🤝 How to Contribute to DockSec

Your feedback is invaluable to us as we continue to improve DockSec. If you'd like to contribute, consider trying out the beta version, reporting any issues, and sharing your suggestions. See the contributing guide for detailed instructions on how you can contribute.

👾 Activity

📘 License

The DockSec is licensed under the MIT license. For more information check the LICENSE file for details.