diff --git a/README.md b/README.md index 0b7a493..4e3343a 100644 --- a/README.md +++ b/README.md @@ -2,444 +2,221 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI version](https://badge.fury.io/py/docksec.svg)](https://badge.fury.io/py/docksec) [![Python Version](https://img.shields.io/pypi/pyversions/docksec.svg)](https://pypi.org/project/docksec/) -[![CI Status](https://github.com/advaitpatel/DockSec/actions/workflows/python-app.yml/badge.svg)](https://github.com/advaitpatel/DockSec/actions) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/advaitpatel/DockSec/blob/main/CONTRIBUTING.md) -[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -
- - - -

🧊 The next generation AI-Powered Docker Security Analyzer πŸ“¦

- -

- GitHub - πŸ”Ή - PyPI - πŸ”Ή - Quick Start - πŸ”Ή - LinkedIn - πŸ”Ή - Twitter / X + DockSec + +

DockSec

+

AI-powered Docker security scanner that explains vulnerabilities in plain English

+ +

+ Quick Start β€’ + Features β€’ + Installation β€’ + Usage β€’ + Contributing

-
+--- -## πŸš€ Quick Start +## What is DockSec? -Get started with DockSec in 3 simple steps: +DockSec combines traditional Docker security scanners (Trivy, Hadolint, Docker Scout) with AI to provide **context-aware security analysis**. Instead of dumping 200 CVEs and leaving you to figure it out, DockSec: -```bash -# 1. Install DockSec -pip install docksec - -# 2. Set your OpenAI API key (optional, for AI features) -export OPENAI_API_KEY="your-api-key" - -# 3. Scan your Dockerfile -docksec path/to/Dockerfile -``` - -That's it! DockSec will analyze your Dockerfile and provide actionable security recommendations. πŸŽ‰ - -> **Note**: Scan-only mode works without an API key: `docksec path/to/Dockerfile --scan-only` - - -## πŸ” 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 +- 🎯 Prioritizes what actually matters +- πŸ’‘ Explains vulnerabilities in plain English +- πŸ”§ Suggests specific fixes for YOUR Dockerfile +- πŸ“Š Generates professional security reports -### 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 +Think of it as having a security expert review your Dockerfiles. -### 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: - -![DockSec Architecture](https://github.com/advaitpatel/DockSec/blob/main/images/docksec-architecture-diagram-II.png) - -![DockSec Architecture](https://github.com/advaitpatel/DockSec/blob/main/images/docksec-architecture-diagram-III.png) - -- **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](https://pypi.org/project/docksec/) +## Quick Start ```bash +# Install pip install docksec -``` -OR You can install DockSec using Python virtual environment - -```bash -python -m venv env - -# On Windows -env\Scripts\activate +# Scan your Dockerfile +docksec Dockerfile -# On macOS/Linux -source env/bin/activate +# Scan with image analysis +docksec Dockerfile -i myapp:latest -pip install -e . +# Scan without AI (no API key needed) +docksec Dockerfile --scan-only ``` -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 +## Features - - πŸ”Ή Bash/Zsh (Linux/macOS): export OPENAI_API_KEY="your-secret-key" +- **Smart Analysis**: AI explains what vulnerabilities mean for your specific setup +- **Multiple Scanners**: Integrates Trivy, Hadolint, and Docker Scout +- **Security Scoring**: Get a 0-100 score to track improvements +- **Multiple Formats**: Export reports as HTML, PDF, JSON, or CSV +- **No AI Required**: Works offline with `--scan-only` mode +- **CI/CD Ready**: Easy integration into build pipelines - - πŸ”Ή Or create a .env file with: OPENAI_API_KEY=your-secret-key +## Installation -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: +**Requirements:** Python 3.12+, Docker (for image scanning) ```bash -# 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 +pip install docksec ``` - -## πŸ“ How to Use DockSec (CLI) - -After installation, you can use DockSec with a simple command: - +**For AI features**, set your OpenAI API key: ```bash -docksec path\to\Dockerfile +export OPENAI_API_KEY="your-key-here" ``` -### 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: - +**External tools** (optional, for full scanning): ```bash -# 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 +# Install Trivy and Hadolint +python -m docksec.setup_external_tools -# Custom output file -docksec path/to/Dockerfile -o custom_report.txt +# Or install manually: +# - Trivy: https://aquasecurity.github.io/trivy/ +# - Hadolint: https://github.com/hadolint/hadolint ``` -### What Gets Generated: +## Usage -DockSec automatically generates comprehensive reports in the `results/` directory: - -- **JSON Report** (`_json.json`) - Machine-readable vulnerability data -- **CSV Report** (`_csv.csv`) - Spreadsheet-friendly vulnerability list -- **PDF Report** (`_pdf.pdf`) - Professional formatted security report -- **HTML Report** (`_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: +### Basic Scanning ```bash -# For AI-based recommendations -python .\main.py "path\to\your\dockerfile" - -# For scanning both Dockerfile and images -python docker_scanner.py [severity] -# Example: python docker_scanner.py .\Dockerfile myapp:latest CRITICAL,HIGH -``` +# Analyze Dockerfile with AI recommendations +docksec Dockerfile - - ### External Tools Setup +# Scan Dockerfile + Docker image +docksec Dockerfile -i nginx:latest -To check the Dockerfile as well as images for vulnerabilities, you need to setup `Trivy` and `hadolint`: +# Get only scan results (no AI) +docksec Dockerfile --scan-only -```bash -python .\setup_external_tools.py +# Scan image without Dockerfile +docksec --image-only -i nginx:latest ``` -For manual installation, refer to [Trivy](https://trivy.dev/v0.18.3/installation/) and [hadolint](https://github.com/hadolint/hadolint?tab=readme-ov-file#install) 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 +### CLI Options -**Problem**: `Hadolint not found in PATH` -- **Solution**: Install Hadolint using the setup script: `python setup_external_tools.py` -- **Manual**: Follow [Hadolint installation guide](https://github.com/hadolint/hadolint#install) - -**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` +| Option | Description | +|--------|-------------| +| `dockerfile` | Path to Dockerfile | +| `-i, --image` | Docker image to scan | +| `-o, --output` | Output file path | +| `--ai-only` | AI analysis only (no scanning) | +| `--scan-only` | Scanning only (no AI) | +| `--image-only` | Scan image without Dockerfile | -### Debug Mode +### Configuration -For detailed logging, set the log level: +Create a `.env` file for advanced configuration: ```bash -export LOG_LEVEL=DEBUG -docksec path/to/Dockerfile +OPENAI_API_KEY=your-key +LLM_MODEL=gpt-4o +TRIVY_SCAN_TIMEOUT=600 ``` -### 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](https://github.com/advaitpatel/DockSec/issues/new) with: - - DockSec version - - Command used - - Error message - - Operating system +See [full configuration options](CONTRIBUTING.md#configuration). +## Example Output -## 🎬 Examples & Screenshots - -### Example: Scanning a Vulnerable Dockerfile +``` +πŸ” Scanning Dockerfile... +⚠️ Security Score: 45/100 -Check out our example Dockerfiles in the [`examples/`](examples/) directory: +Critical Issues (3): + β€’ Running as root user (line 12) + β€’ Hardcoded API key detected (line 23) + β€’ Using vulnerable base image -- **Secure Python App** - Best practices example (Score: 90+) -- **Vulnerable Node App** - Common mistakes to avoid (Score: 30-) -- **Multi-stage Golang** - Advanced optimization patterns (Score: 95+) +πŸ’‘ AI Recommendations: + 1. Add non-root user: RUN useradd -m appuser && USER appuser + 2. Move secrets to environment variables or build secrets + 3. Update FROM ubuntu:20.04 to ubuntu:22.04 (fixes 12 CVEs) -```bash -# Try scanning our example vulnerable Dockerfile -git clone https://github.com/advaitpatel/DockSec.git -cd DockSec/examples/dockerfiles/vulnerable-node-app -docksec Dockerfile +πŸ“Š Full report: results/nginx_latest_report.html ``` -**Sample Output:** -``` -πŸ” Scanning Dockerfile... -⚠️ Security Score: 32/100 +## Examples -Critical Issues (5): - β€’ Hardcoded secrets detected - β€’ Running as root user - β€’ Using 'latest' tag +Check out example Dockerfiles in [`examples/`](examples/): -High Issues (8): - β€’ Outdated packages with CVEs - β€’ Unnecessary packages installed - ... +- **Secure Python app** - Best practices (Score: 95/100) +- **Vulnerable Node app** - Common mistakes (Score: 32/100) +- **Multi-stage Go build** - Advanced patterns (Score: 98/100) -πŸ’‘ AI Recommendations: - 1. Remove hardcoded secrets and use environment variables - 2. Create non-root user: RUN adduser -S appuser && USER appuser - 3. Use specific version tags: FROM node:18-alpine - ... +## Architecture -πŸ“Š Reports generated in: results/ +``` +Dockerfile β†’ [Trivy + Hadolint + Scout] β†’ AI Analysis β†’ Reports ``` -For more examples and sample reports, see the [`examples/`](examples/) directory. - - -## ☝️ Need Help or Want to Provide Feedback? +DockSec runs security scanners locally, then uses GPT-4 to: +1. Combine and deduplicate findings +2. Assess real-world impact for your context +3. Generate actionable remediation steps +4. Calculate security score -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](https://github.com/advaitpatel/DockSec/issues/new). -We are happy to assist you with anything related to the project. +All scanning happens on your machine. Only scan results (not your code) are sent to OpenAI when using AI features. +## Roadmap -## 🀝 How to Contribute to DockSec +- [ ] Docker Compose support +- [ ] Kubernetes manifest scanning +- [ ] Additional LLM providers (Claude, local models) +- [ ] GitHub Actions integration +- [ ] Custom security policies -We welcome contributions from the community! Whether it's: +See [open issues](https://github.com/advaitpatel/DockSec/issues) or suggest features in [discussions](https://github.com/advaitpatel/DockSec/discussions). -- πŸ› Reporting bugs -- πŸ’‘ Suggesting new features -- πŸ“ Improving documentation -- πŸ”§ Submitting pull requests +## Contributing -See our [Contributing Guide](CONTRIBUTING.md) for detailed instructions. +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +Quick links: +- [Report a bug](https://github.com/advaitpatel/DockSec/issues/new?template=bug_report.md) +- [Request a feature](https://github.com/advaitpatel/DockSec/issues/new?template=feature_request.md) +- [View roadmap](https://github.com/advaitpatel/DockSec/issues) -## πŸ“š Documentation +## Documentation -- **[Quick Start Guide](#quick-start)** - Get started in 3 steps -- **[Installation](#-installation)** - Detailed installation instructions -- **[Usage Examples](#-how-to-use-docksec-cli)** - CLI usage and examples -- **[Configuration](CONTRIBUTING.md#configuration)** - Environment variables and settings -- **[Examples Directory](examples/)** - Sample Dockerfiles and use cases -- **[Troubleshooting](#-troubleshooting)** - Common issues and solutions -- **[Changelog](CHANGELOG.md)** - Version history and updates -- **[Security Policy](SECURITY.md)** - Security guidelines and reporting +- [Installation Guide](CONTRIBUTING.md#development-setup) +- [Configuration Options](CONTRIBUTING.md#configuration) +- [Examples](examples/) +- [Changelog](CHANGELOG.md) +- [Security Policy](SECURITY.md) +## Troubleshooting -## πŸ—ΊοΈ Roadmap +**"No OpenAI API Key provided"** +β†’ Set `OPENAI_API_KEY` or use `--scan-only` mode -### Coming Soon -- [ ] Docker Compose support -- [ ] Kubernetes manifest scanning -- [ ] GitHub Actions integration -- [ ] Custom rule engine -- [ ] Web dashboard interface +**"Hadolint not found"** +β†’ Run `python -m docksec.setup_external_tools` -### Under Consideration -- [ ] Support for additional LLM providers (Claude, Gemini) -- [ ] SBOM generation -- [ ] Container runtime monitoring -- [ ] VSCode extension +**"Python version not supported"** +β†’ DockSec requires Python 3.12+. Use `pyenv install 3.12` to upgrade. -Vote on features or suggest new ones in [GitHub Discussions](https://github.com/advaitpatel/DockSec/discussions)! +For more issues, see [Troubleshooting Guide](CONTRIBUTING.md#troubleshooting). +## License -## πŸ‘Ύ Activity +MIT License - see [LICENSE](LICENSE) for details. -![DockSec Activity](https://repobeats.axiom.co/api/embed/c5aac6f5d22bd6b83a21ae51353dd7bcb43f9517.svg "DockSec activity image") +## Links +- **PyPI**: https://pypi.org/project/docksec/ +- **Issues**: https://github.com/advaitpatel/DockSec/issues +- **Discussions**: https://github.com/advaitpatel/DockSec/discussions -## πŸ“˜ License +--- -The DockSec is licensed under the MIT license. For more information check the [LICENSE](https://github.com/advaitpatel/DockSec/blob/main/LICENSE) file for details. \ No newline at end of file +
+ + **If DockSec helps you, give it a ⭐ to help others discover it!** + + Built with ❀️ by [Advait Patel](https://github.com/advaitpatel) + +