deploy-audit 0.1.0

Auditing tool for Docker Compose and Kubernetes deployments to ensure deployment hygiene and container readiness.

Deploy-Audit

Deploy-Audit is a comprehensive auditing tool for Docker Compose and Kubernetes deployments, designed to ensure deployment hygiene and container readiness. It performs automated checks for best practices, security policies, and configuration standards.

Features

Core Capabilities

• Docker Compose Auditing: Validate healthchecks, restart policies, resource limits, environment variables, and port exposure
• Kubernetes Auditing: Check for resource requirements, probes (liveness/readiness), security context, and image pull policies
• Multiple Report Formats: CLI, Markdown, JSON, and HTML reports
• Severity Scoring: Critical, High, Medium, Low, and Info severity levels
• Flexible Integration: Python library API + CLI tool

Docker Compose Checks

• ✅ Healthcheck presence and configuration
• ✅ Restart policy definition
• ✅ Environment variable security (detects hardcoded secrets)
• ✅ Port exposure sanity (detects insecure bindings)
• ✅ Image tag specificity (warns against :latest)
• ✅ Resource limits configuration
• ✅ Logging configuration

Kubernetes Checks

• ✅ Image pull policy validation
• ✅ Resource requirements (requests/limits)
• ✅ Liveness probe presence
• ✅ Readiness probe presence
• ✅ Security context configuration
• ✅ Network policy awareness
• ✅ Image registry validation

Installation

From PyPI

pip install deploy-audit

From Source

git clone https://github.com/yourusername/deploy-audit.git
cd deploy-audit
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Docker Compose Audit

# Audit a Docker Compose file
deploy-audit docker docker-compose.yml

# Generate HTML report
deploy-audit docker docker-compose.yml --format html --output report.html

# Fail if non-compliant (useful for CI/CD)
deploy-audit docker docker-compose.yml --strict

Kubernetes Audit

# Audit a Kubernetes manifest
deploy-audit kubernetes deployment.yaml

# Generate JSON report
deploy-audit kubernetes deployment.yaml --format json --output report.json

# Check with strict mode
deploy-audit kubernetes deployment.yaml --strict

Auto-detect Configuration Type

# Automatically detect config type
deploy-audit audit docker-compose.yml
deploy-audit audit manifest.yaml

Python API Usage

Basic Usage

from deploy_audit.auditor import Auditor
from deploy_audit.report import Report

# Read configuration file
with open("docker-compose.yml", "rb") as f:
    content = f.read()

# Create auditor and run audit
auditor = Auditor()
audit_report = auditor.audit_docker_compose(content, "docker-compose.yml")

# Generate reports in different formats
report = Report(audit_report)
print(report.cli())  # Print to console
report.save_markdown("report.md")  # Save Markdown
report.save_json("report.json")  # Save JSON
report.save_html("report.html")  # Save HTML

Advanced Usage

from deploy_audit.auditor import DockerComposeAuditor
from deploy_audit.models import CheckResult

# Use specific auditor
auditor = DockerComposeAuditor()
report = auditor.audit_content(content)

# Check report status
print(f"Is Compliant: {report.is_compliant}")
print(f"Critical Issues: {report.critical_count()}")
print(f"High Issues: {report.high_count()}")

# Filter findings
failed_checks = [f for f in report.findings if f.result == CheckResult.FAILED]
critical_issues = [f for f in report.findings if f.severity.name == "CRITICAL"]

Custom Checks

from deploy_audit.checks import Check
from deploy_audit.models import CheckResult, Severity

class CustomCheck(Check):
    id = "custom-001"
    name = "Custom Check"
    description = "My custom audit check"
    severity = Severity.HIGH
    remediation = "Fix the issue"

    def evaluate(self, resource_name, config):
        # Your check logic here
        if condition_met(config):
            return CheckResult.PASSED
        return CheckResult.FAILED

Report Formats

CLI Report

================================================================================
DEPLOYMENT AUDIT REPORT: docker-compose.yml
Type: docker-compose | Time: 2024-01-15T10:30:00
================================================================================

SUMMARY
--------------------------------------------------------------------------------
Total Checks: 14
Passed: 9
Failed: 5
Critical: 1
High: 2
Status: ✗ NON-COMPLIANT

Markdown Report

Professional Markdown format suitable for documentation and version control:

# Deployment Audit Report: docker-compose.yml

| Metric | Value |
|--------|-------|
| Total Checks | 14 |
| Passed | 9 |
| Failed | 5 |
| Status | ❌ NON-COMPLIANT |

## Findings
...

JSON Report

{
  "config_type": "docker-compose",
  "config_name": "docker-compose.yml",
  "timestamp": "2024-01-15T10:30:00",
  "summary": {
    "total_checks": 14,
    "passed": 9,
    "failed": 5,
    "is_compliant": false
  },
  "findings": [...]
}

HTML Report

Interactive HTML report with:

• Visual severity indicators
• Summary statistics
• Detailed findings with remediation
• Responsive design

Configuration

Severity Levels

• CRITICAL (🔴): Must fix before deployment
• HIGH (🟠): Should fix for production
• MEDIUM (🟡): Recommended improvements
• LOW (🟢): Nice to have enhancements
• INFO (ℹ️): Informational

Check Results

• PASSED: Check succeeded
• FAILED: Check failed
• WARNING: Check passed but with warnings
• INFO: Informational finding
• SKIPPED: Check not applicable

Integration

GitHub Actions Example

name: Deployment Audit

on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install deploy-audit
        run: pip install deploy-audit
      - name: Audit Docker Compose
        run: deploy-audit docker docker-compose.yml --format markdown --output audit.md
      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: audit-report
          path: audit.md

Pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: deploy-audit-docker
        name: Deploy-Audit Docker Compose
        entry: deploy-audit docker
        language: python
        files: docker-compose\.yml$
        types: [yaml]

Architecture

Components

• Parsers: Extract and validate configuration files
• Auditors: Run checks against configurations
• Checks: Individual audit rules and validations
• Models: Data structures for findings and reports
• Reporters: Format and export audit results
• CLI: Command-line interface

Design Principles

• Single Responsibility: Each check handles one concern
• Composability: Mix and match checks as needed
• Extensibility: Easy to add custom checks
• Performance: Fast audit execution
• Clarity: Clear, actionable findings

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=deploy_audit

# Run specific test suite
pytest tests/test_auditors.py

# Run tests in parallel
pytest -n auto

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Documentation

• User Guide - Detailed usage instructions
• API Reference - Complete Python API documentation
• Check Reference - Detailed description of all checks
• Contributing Guide - Development guidelines

Performance

• Average audit time: <100ms for typical Docker Compose files
• Memory usage: <50MB for standard configurations
• Scalability: Handles 100+ services efficiently

Roadmap

• Docker Compose support
• Kubernetes support
• Multi-file manifest support
• Policy-as-code engine
• Custom rule definitions
• Integration with registries
• SBOM generation
• Compliance framework mapping (CIS, NIST)

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: https://deploy-audit.readthedocs.io

About

Deploy-Audit is designed for:

• DevOps Engineers: Ensure consistent deployment standards
• Security Teams: Enforce security policies
• Platform Teams: Automate infrastructure validation
• CI/CD Pipelines: Automated compliance checks
• Learning: DevOps best practices education

---

Made with ❤️ for the DevOps community