Contributing to S3 Security Scanner

January 10, 2026 · View on GitHub

Thank you for your interest in contributing to the S3 Security Scanner! We welcome contributions from the community.

Getting Started

Prerequisites

Python 3.8 or higher
Git
AWS CLI configured with appropriate credentials
Good understanding of AWS S3 security concepts

Development Setup

Fork and Clone the Repository

git clone https://github.com/TocConsulting/s3-security-scanner.git
cd s3-security-scanner

Create a Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Development Dependencies

# Install all development dependencies from pyproject.toml
pip install -e ".[dev]"

# Or install manually if needed
pip install pytest pytest-cov black flake8 mypy "moto[s3]"

Development Workflow

Code Style and Standards

We maintain high code quality standards using the following tools:

Code Formatting

# Format code with Black
black s3_security_scanner/

Code Linting

# Check code style with flake8
flake8 s3_security_scanner/

# Type checking with mypy
mypy s3_security_scanner/

Testing

# Run tests with pytest
pytest tests/

# Run tests with coverage
pytest --cov=s3_security_scanner tests/

Code Quality Requirements

Line Length: Maximum 79 characters (PEP8 standard)
Type Hints: Required for all public functions and methods
Docstrings: Required for all modules, classes, and public functions
Error Handling: Proper exception handling with logging
Security: No hardcoded credentials or sensitive information

Making Changes

Branch Naming Convention

feature/description-of-feature - New features
bugfix/description-of-bug - Bug fixes
docs/description-of-changes - Documentation updates
refactor/description-of-refactor - Code refactoring

Commit Message Format

type(scope): short description

Longer description if needed

- List any breaking changes
- Reference issues: Fixes #123

Types:

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

Pull Request Process

Create a Feature Branch

git checkout -b feature/your-feature-name

Make Your Changes
- Write clean, well-documented code
- Add tests for new functionality
- Update documentation as needed

Test Your Changes

# Run all checks
black s3_security_scanner/
flake8 s3_security_scanner/
pytest tests/

Commit Your Changes

git add .
git commit -m "feat(scanner): add new security check for bucket notifications"

Push and Create Pull Request

git push origin feature/your-feature-name

Submit Pull Request
- Provide clear description of changes
- Reference any related issues
- Include test results if applicable

Testing Guidelines

Test Structure

tests/
├── __init__.py
├── test_cli.py                 # CLI option tests
├── test_compliance.py          # Compliance framework tests
├── test_scanner.py             # Scanner functionality tests
├── test_cloudtrail_logging.py  # CloudTrail logging tests
├── test_gdpr_compliance.py     # GDPR compliance tests
└── test_soc2_monitoring.py     # SOC 2 monitoring tests

Writing Tests

Test individual functions and methods
Use unittest (Python standard library) or pytest
Mock AWS S3 services using moto[s3] library (only S3, not all AWS services)
Use @mock_aws decorator (moto 4.x+) for mocking AWS services
Aim for good test coverage

Example Test

import unittest
from moto import mock_aws
import boto3
from s3_security_scanner.scanner import S3SecurityScanner

class TestS3Scanner(unittest.TestCase):
    @mock_aws
    def test_check_public_access_block(self):
        """Test public access block configuration check."""
        # Create mock S3 resource
        s3 = boto3.client('s3', region_name='us-east-1')
        s3.create_bucket(Bucket='test-bucket')
        
        scanner = S3SecurityScanner()
        # Test implementation here

Architecture Guidelines

Project Structure

s3_security_scanner/
├── __init__.py         # Package initialization
├── cli.py              # Command-line interface
├── scanner.py          # Main scanning logic
├── compliance.py       # Compliance framework checks
├── html_reporter.py    # HTML report generation
├── utils.py            # Utility functions
└── templates/          # HTML templates