Contributing to DockSec

July 14, 2026 · View on GitHub

First off, thank you for considering contributing to DockSec! 🎉

It's people like you that make DockSec such a great tool. We welcome contributions from everyone, whether you're fixing a typo, reporting a bug, or implementing a major new feature.

📋 Table of Contents

Code of Conduct
How Can I Contribute?
Reporting Bugs
Suggesting Features
Your First Code Contribution
Pull Requests
Development Setup
Code Style Guidelines
Testing
Documentation
Community

📜 Code of Conduct

This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. By participating, you are expected to uphold this code:

Be respectful and inclusive
Be collaborative and constructive
Focus on what is best for the community
Show empathy towards other community members

🤝 How Can I Contribute?

The following diagram illustrates the complete contribution workflow:

flowchart TD
    Start([Start]) --> CreateIssue[Create New Issue]
    Start --> FindIssue[Find Existing Issue]
    CreateIssue --> GetAssigned[**Get Assigned to Issue**]
    FindIssue --> GetAssigned
    GetAssigned --> ResolveIssue[**Resolve Issue**<br/>work on code/docs/tests]

    ResolveIssue --> RunChecks{**Run `make check-test`**<br/>locally!}
    RunChecks -->|Fails| WP1[ ]
    RunChecks -->|Passes| PushChanges[**Push Changes to<br/>GitHub Fork Branch**]
    WP1 -.-> ResolveIssue

    PushChanges --> CreatePR[Create Pull Request]
    CreatePR --> WaitAutoChecks[**Wait for Automated Checks**]
    
    WaitAutoChecks --> RequestReview[Request Review from<br/>Project Maintainers]
    RequestReview --> WaitMaintainer[Wait for Maintainers' Comments]

    WaitMaintainer --> HasMaintainerComments{**Resolved?**}
    HasMaintainerComments -->|No| ResolveIssue
    HasMaintainerComments -->|Yes| CheckCI{**CI/CD Passing?**}

    CheckCI -->|Yes| ReadyMerge([PR Ready for Merge])
    CheckCI -->|No| ResolveIssue

    style Start fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#ffffff
    style ReadyMerge fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#ffffff
    style ResolveIssue fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#000000

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Use a clear and descriptive title
Describe the exact steps to reproduce the problem
Provide specific examples (commands, Dockerfiles, etc.)
Describe the behavior you observed and what you expected
Include screenshots or error messages if applicable
Specify your environment (OS, Python version, DockSec version)

Use our Bug Report Template when creating issues.

Suggesting Features

Feature suggestions are welcome! Before creating a feature request:

Check if the feature already exists in the latest version
Search existing issues to see if someone else suggested it
Provide a clear use case for the feature
Explain why this feature would be useful to most users

Use our Feature Request Template.

Your First Code Contribution

Unsure where to begin? Look for issues labeled:

good first issue - Good for newcomers
help wanted - Issues where we need community help
documentation - Documentation improvements

Pull Requests

Fork the repository and create your branch from main
Make your changes following our code style guidelines
Add or update tests as needed
Update documentation if you changed functionality
Ensure all tests pass before submitting
Write a clear commit message describing your changes
Submit a pull request using our PR template

🛠️ Development Setup

Prerequisites

Python 3.12 or higher
Git
Docker (for testing image scanning)
Trivy and Hadolint (for full functionality)

Setup Steps

Clone your fork:

git clone https://github.com/YOUR_USERNAME/DockSec.git
cd DockSec

Create a virtual environment:

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

Install dependencies:

pip install -e ".[dev]"
pip install -r requirements.txt

Install external tools (optional, for full testing):
```
python -m docksec.setup_external_tools
```

Set up environment variables:

cp .env.example .env
# Edit .env and add your OpenAI API key if testing AI features

Verify Installation

# Run DockSec
docksec -h

# Run tests
pytest tests/

# Check code style
black --check .
isort --check-only .
flake8 .
mypy .

🎨 Code Style Guidelines

We follow Python best practices and use automated tools to maintain code quality.

AI & Tooling Guidelines

To maintain project integrity and professional standards:

No AI Branding: Do not use "Cursor Agent", "AI Coding Assistant", or similar AI-specific branding in code comments, documentation, or commit messages.
Clean Commits: Do not include "Co-authored-by: Cursor" or other automated AI attribution in git commit messages.
Human-Centric: All code and documentation should be professional, technical, and focused on project functionality.

Style Tools

Black for code formatting
isort for import sorting
flake8 for linting
mypy for type checking

Running Style Checks

# Format code
black .
isort .

# Check linting
flake8 .

# Type checking
mypy .

🧪 Testing

We maintain high test coverage to ensure code quality.

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_docker_scanner.py

# Run specific test function
pytest tests/test_docker_scanner.py::test_scan_dockerfile

📚 Documentation

Good documentation is crucial! When contributing:

Code Documentation

Add docstrings to all public functions and classes
Use Google-style docstrings
Include type hints in function signatures
Add inline comments for complex logic

User Documentation

Update README.md if you add features
Update CLI help text if you change commands
Add entries to CHANGELOG.md

🏗️ Project Structure

DockSec/
├── .github/              # GitHub templates and workflows
├── 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
├── 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

Create a branch for your changes:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Make your changes and commit them:

git add .
git commit -m "feat: add new feature"

Keep your branch up to date:

git fetch upstream
git rebase upstream/main

Push to your fork:

git push origin feature/your-feature-name

Open a pull request on GitHub

Commit Message Guidelines

We follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(scanner): add Docker Compose support
fix(cli): handle missing Dockerfile gracefully
docs(readme): add installation instructions for Windows
test(scanner): add unit tests for Trivy integration

🚀 Release Process

Maintainers follow this process for releases:

Update version in setup.py
Update CHANGELOG.md with release notes
Create a git tag: git tag v0.0.X
Push tag: git push origin v0.0.X
Build and publish to PyPI: python -m build && twine upload dist/*
Create GitHub release with changelog

💬 Community

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and community discussion
Pull Requests: Code contributions

Getting Help

Read the README
Check existing issues
Ask questions in Discussions

📄 License

By contributing to DockSec, you agree that your contributions will be licensed under the MIT License.

🙏 Recognition

Contributors are recognized in:

GitHub contributors page
Release notes for significant contributions
README acknowledgments (for major features)

❓ Questions?

Don't hesitate to ask! You can:

Open an issue with the question label
Start a discussion on GitHub Discussions
Reach out to the maintainers

Thank you for contributing to DockSec! Your efforts help make Docker security more accessible to everyone. 🎉