OWASP · advaitpatel · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,7 +1,7 @@
 include LICENSE
 include README.md
-include *.html
 include requirements.txt
 include .env.example
-recursive-include testfiles *
-global-exclude *.py[cod] __pycache__ *.so .DS_Store
+recursive-include docksec/templates *.html
+recursive-include tests *
+global-exclude *.py[cod] __pycache__ *.so .DS_Store
diff --git a/docksec.py:Zone.Identifier b/docksec.py:Zone.Identifier
diff --git a/.gitignore:Zone.Identifier → docksec/__init__.py b/.gitignore:Zone.Identifier → docksec/__init__.py
diff --git a/docksec.py → docksec/cli.py b/docksec.py → docksec/cli.py
@@ -112,15 +112,15 @@ def main() -> None:
         print("\n=== Running AI-based Dockerfile analysis ===")
         try:
             # Import required modules from main.py
-            from utils import (
+            from docksec.utils import (
                 get_custom_logger,
                 load_docker_file,
                 get_llm,
                 analyze_security,
                 AnalyzesResponse,
                 ScoreResponse
             )
-            from config import docker_agent_prompt, docker_score_prompt
+            from docksec.config import docker_agent_prompt, docker_score_prompt
             from pathlib import Path
 
             # Set up the same components as main.py
@@ -150,7 +150,7 @@ def main() -> None:
         scan_type = "image-only" if args.image_only else "full"
         print(f"\n=== Running {scan_type} security scanner ===")
         try:
-            from docker_scanner import DockerSecurityScanner
+            from docksec.docker_scanner import DockerSecurityScanner
 
             # Initialize the scanner
             dockerfile_path = args.dockerfile if run_dockerfile_analysis else None

diff --git a/config.py → docksec/config.py b/config.py → docksec/config.py
diff --git a/config_manager.py → docksec/config_manager.py b/config_manager.py → docksec/config_manager.py
diff --git a/docker_scanner.py → docksec/docker_scanner.py b/docker_scanner.py → docksec/docker_scanner.py
@@ -11,9 +11,9 @@
 import re
 import shlex
 from pathlib import Path
-from config import RESULTS_DIR
-from config import docker_score_prompt
-from utils import ScoreResponse, get_llm, print_section, get_custom_logger
+from docksec.config import RESULTS_DIR
+from docksec.config import docker_score_prompt
+from docksec.utils import ScoreResponse, get_llm, print_section, get_custom_logger
 
 # Initialize logger
 logger = get_custom_logger(__name__)
@@ -997,7 +997,7 @@ def _calculate_local_score(self, results: Dict) -> float:
             vuln_score = max(0.0, 100.0 - deduction)
 
         # Configuration score — static Dockerfile checks
-        from score_calculator import SecurityScoreCalculator
+        from docksec.score_calculator import SecurityScoreCalculator
         config_score = SecurityScoreCalculator._calculate_config_score(self, results)
 
         overall = (dockerfile_score * 0.3) + (vuln_score * 0.5) + (config_score * 0.2)
@@ -1063,7 +1063,7 @@ def save_results_to_html(self, results: Dict) -> str:
             #
             # with open(template_path, 'r', encoding='utf-8') as f:
             #     html_template = f.read()
-            from config import html_template
+            from docksec.config import html_template
 
             # Prepare template variables
             template_vars = self._prepare_html_template_vars(results)

diff --git a/report_generator.py → docksec/report_generator.py b/report_generator.py → docksec/report_generator.py
@@ -21,8 +21,8 @@
 from fpdf import FPDF
 from pathlib import Path
 
-from config import RESULTS_DIR, html_template
-from utils import get_custom_logger
+from docksec.config import RESULTS_DIR, html_template
+from docksec.utils import get_custom_logger
 
 # Initialize logger
 logger = get_custom_logger(__name__)

diff --git a/score_calculator.py → docksec/score_calculator.py b/score_calculator.py → docksec/score_calculator.py
@@ -8,8 +8,8 @@
 import logging
 import re
 from typing import Dict
-from config import docker_score_prompt
-from utils import ScoreResponse, get_llm, get_custom_logger
+from docksec.config import docker_score_prompt
+from docksec.utils import ScoreResponse, get_llm, get_custom_logger
 
 # Initialize logger
 logger = get_custom_logger(__name__)

diff --git a/setup_external_tools.py → docksec/setup_external_tools.py b/setup_external_tools.py → docksec/setup_external_tools.py
diff --git a/templates/report_template.html → docksec/templates/report_template.html b/templates/report_template.html → docksec/templates/report_template.html
diff --git a/utils.py → docksec/utils.py b/utils.py → docksec/utils.py
@@ -30,7 +30,7 @@
     OLLAMA_AVAILABLE = True
 except ImportError:
     OLLAMA_AVAILABLE = False
-from config import (
+from docksec.config import (
     BASE_DIR,
     OPENAI_API_KEY
 )
@@ -153,7 +153,7 @@ def get_llm() -> Union[ChatOpenAI, 'ChatAnthropic', 'ChatGoogleGenerativeAI', 'C
         - Uses exponential backoff: 2s, 4s, 8s
         - Handles rate limiting automatically
     """
-    from config_manager import get_config
+    from docksec.config_manager import get_config
 
     try:
         config = get_config()

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -5,6 +5,27 @@ All notable changes to DockSec will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2026.5.6] - 2026-05-06
+
+### Changed
+- **Major Structural Overhaul**: Restructured the project from a flat layout to a proper Python package structure.
+  - Core logic moved to `docksec/` directory.
+  - CLI entry point moved to `docksec/cli.py`.
+  - Templates moved to `docksec/templates/`.
+  - Consolidation of redundant files (`main.py` removed).
+- **Packaging Improvements**:
+  - Updated `setup.py` and `pyproject.toml` for better distribution.
+  - Improved `MANIFEST.in` to include all necessary package data.
+- **Documentation**:
+  - Updated `README.md` and `CONTRIBUTING.md` to reflect the new structure.
+  - Improved project structure visualization in documentation.
+
+### Fixed
+- Internal import paths updated to use absolute package imports.
+- Metadata artifacts (`*:Zone.Identifier`) removed from the repository.
+
+---
+
 ## [2026.2.23] - 2026-02-23
 
 ### Added

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -8,10 +8,10 @@ It's people like you that make DockSec such a great tool. We welcome contributio
 
 - [Code of Conduct](#code-of-conduct)
 - [How Can I Contribute?](#how-can-i-contribute)
-  - [Reporting Bugs](#reporting-bugs)
-  - [Suggesting Features](#suggesting-features)
-  - [Your First Code Contribution](#your-first-code-contribution)
-  - [Pull Requests](#pull-requests)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Your First Code Contribution](#your-first-code-contribution)
+- [Pull Requests](#pull-requests)
 - [Development Setup](#development-setup)
 - [Code Style Guidelines](#code-style-guidelines)
 - [Testing](#testing)
@@ -112,7 +112,7 @@ Unsure where to begin? Look for issues labeled:
 
 5. **Install external tools** (optional, for full testing):
    ```bash
-   python setup_external_tools.py
+   python -m docksec.setup_external_tools
    ```
 
 6. **Set up environment variables**:
@@ -162,42 +162,6 @@ flake8 .
 mypy .
 ```
 
-### Code Standards
-
-1. **Follow PEP 8** style guide
-2. **Use type hints** for all functions
-3. **Write docstrings** for all public functions and classes
-4. **Keep functions small** and focused
-5. **Add comments** for complex logic
-6. **Use meaningful variable names**
-
-### Example
-
-```python
-from typing import List, Optional
-
-def analyze_dockerfile(
-    dockerfile_path: str,
-    severity_levels: Optional[List[str]] = None
-) -> Dict[str, Any]:
-    """
-    Analyze a Dockerfile for security vulnerabilities.
-
-    Args:
-        dockerfile_path: Path to the Dockerfile to analyze
-        severity_levels: Optional list of severity levels to filter
-
-    Returns:
-        Dictionary containing analysis results
-
-    Raises:
-        FileNotFoundError: If Dockerfile doesn't exist
-        ValueError: If Dockerfile path is invalid
-    """
-    # Implementation here
-    pass
-```
-
 ## 🧪 Testing
 
 We maintain high test coverage to ensure code quality.
@@ -218,33 +182,6 @@ pytest tests/test_docker_scanner.py
 pytest tests/test_docker_scanner.py::test_scan_dockerfile
 ```
 
-### Writing Tests
-
-1. **Create test files** in the `tests/` directory
-2. **Name test functions** starting with `test_`
-3. **Use descriptive test names** that explain what's being tested
-4. **Test edge cases** and error conditions
-5. **Use fixtures** for common setup
-6. **Mock external dependencies** (API calls, file I/O)
-
-### Example Test
-
-```python
-import pytest
-from docksec import analyze_dockerfile
-
-def test_analyze_dockerfile_success():
-    """Test successful Dockerfile analysis."""
-    result = analyze_dockerfile("tests/fixtures/good_dockerfile")
-    assert result["score"] > 80
-    assert "vulnerabilities" in result
-
-def test_analyze_dockerfile_missing_file():
-    """Test error handling for missing Dockerfile."""
-    with pytest.raises(FileNotFoundError):
-        analyze_dockerfile("nonexistent/Dockerfile")
-```
-
 ## 📚 Documentation
 
 Good documentation is crucial! When contributing:
@@ -262,33 +199,29 @@ Good documentation is crucial! When contributing:
 - Update **CLI help text** if you change commands
 - Add entries to **CHANGELOG.md**
 
-### Documentation Style
-
-- Use **clear, simple language**
-- Provide **code examples**
-- Include **expected output**
-- Add **troubleshooting tips** if needed
-
 ## 🏗️ Project Structure
 
 ```
 DockSec/
 ├── .github/              # GitHub templates and workflows
-├── templates/            # Report templates
+├── docksec/              # Main package directory
+│   ├── templates/        # Report templates
+│   ├── cli.py            # Main CLI entry point
+│   ├── docker_scanner.py # Scanning engine
+│   ├── utils.py          # Utility functions
+│   ├── config.py         # Configuration management
+│   ├── config_manager.py # Advanced configuration manager
+│   ├── report_generator.py # Report generation
+│   ├── score_calculator.py # Security scoring
+│   └── setup_external_tools.py # Tool installation helper
 ├── tests/                # Test files
-├── docksec.py           # Main CLI entry point
-├── main.py              # AI analysis module
-├── docker_scanner.py    # Scanning engine
-├── utils.py             # Utility functions
-├── config.py            # Configuration management
-├── report_generator.py  # Report generation
-├── score_calculator.py  # Security scoring
-├── requirements.txt     # Dependencies
-├── setup.py             # Package configuration
-├── README.md            # Main documentation
-├── CONTRIBUTING.md      # This file
-├── CHANGELOG.md         # Version history
-└── SECURITY.md          # Security policy
+├── requirements.txt      # Dependencies
+├── setup.py              # Package configuration
+├── pyproject.toml        # Build system configuration
+├── README.md             # Main documentation
+├── CONTRIBUTING.md       # This file
+├── CHANGELOG.md          # Version history
+└── SECURITY.md           # Security policy
 ```
 
 ## 🔄 Development Workflow

diff --git a/main.py b/main.py
diff --git a/report_template.html:Zone.Identifier b/report_template.html:Zone.Identifier