Metadata-Version: 2.4
Name: deploy-audit
Version: 0.1.0
Summary: Auditing tool for Docker Compose and Kubernetes deployments to ensure deployment hygiene and container readiness.
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/deploy-audit
Project-URL: Documentation, https://deploy-audit.readthedocs.io
Project-URL: Repository, https://github.com/yourusername/deploy-audit.git
Project-URL: Issues, https://github.com/yourusername/deploy-audit/issues
Keywords: docker,kubernetes,deployment,audit,devops,healthcheck,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin>=6.0; extra == "docs"
Dynamic: license-file

# Deploy-Audit

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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
```bash
pip install deploy-audit
```

### From Source
```bash
git clone https://github.com/yourusername/deploy-audit.git
cd deploy-audit
pip install -e .
```

### Development Installation
```bash
pip install -e ".[dev]"
```

## Quick Start

### Docker Compose Audit
```bash
# 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
```bash
# 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
```bash
# Automatically detect config type
deploy-audit audit docker-compose.yml
deploy-audit audit manifest.yaml
```

## Python API Usage

### Basic Usage
```python
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
```python
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
```python
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:
```markdown
# Deployment Audit Report: docker-compose.yml

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

## Findings
...
```

### JSON Report
```json
{
  "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
```yaml
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
```yaml
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

```bash
# 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](docs/guide.md) - Detailed usage instructions
- [API Reference](docs/api.md) - Complete Python API documentation
- [Check Reference](docs/checks.md) - Detailed description of all checks
- [Contributing Guide](CONTRIBUTING.md) - Development guidelines

## Performance

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

## Roadmap

- [x] Docker Compose support
- [x] 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**
