Contributing to PathShield

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

Code of Conduct
Getting Started
Development Setup
How to Contribute
Coding Standards
Testing
Documentation
Submitting Changes
Issue Guidelines
Pull Request Process

Code of Conduct

This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions.

Getting Started

Fork the repository on GitHub
Clone your fork locally
Set up the development environment
Create a new branch for your changes
Make your changes
Test your changes
Submit a pull request

Development Setup

Prerequisites

Python 3.9 or higher
pip package manager
Git
AWS CLI configured (for testing)

Installation

Clone your fork:

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

Create a virtual environment:

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

Install dependencies:

pip install -e ".[dev]"

Install pre-commit hooks:

pre-commit install

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=pathshield --cov-report=html

# Run specific test file
pytest tests/test_pathshield.py -v

# Run with verbose output
pytest tests/ -vv

Code Formatting

We use Black for code formatting and Flake8 for linting:

# Format code
black pathshield/ tests/

# Check code style
flake8 pathshield/ tests/

# Type checking
mypy pathshield/

How to Contribute

Types of Contributions

We welcome several types of contributions:

Bug fixes: Fix issues in existing code
New features: Add new service plugins or functionality
Documentation: Improve or add documentation
Tests: Add or improve test coverage
Performance improvements: Optimize existing code
Security improvements: Enhance security features

Adding a New Service Plugin

To add a new AWS service plugin:

Create a new file in pathshield/services/ (e.g., rds.py)
Inherit from BaseServicePlugin
Implement required methods:
- collect(): Collect resources from AWS
- analyze_escalation(): Analyze for privilege escalation paths
Add tests in tests/
Update documentation

Example plugin structure:

from pathshield.services.base import BaseServicePlugin, ServiceEscalationPath
from pathshield.aws.session import AWSSession, AWSResource

class MyServicePlugin(BaseServicePlugin):
    name = "myservice"
    version = "1.0.0"
    description = "My service escalation detection"
    dependencies = ["myservice:ListResources"]
    
    def collect(self) -> List[AWSResource]:
        # Collect resources
        pass
    
    def analyze_escalation(self, iam_graph) -> List[ServiceEscalationPath]:
        # Analyze escalation paths
        pass

Coding Standards

Python Style Guide

Follow PEP 8 style guide
Use Black for automatic formatting (line length: 100)
Use type hints for function arguments and return values
Write docstrings for all public functions and classes

Docstring Format

Use Google-style docstrings:

def function_name(param1: str, param2: int) -> bool:
    """Short description of the function.
    
    Longer description if needed.
    
    Args:
        param1: Description of param1.
        param2: Description of param2.
    
    Returns:
        Description of return value.
    
    Raises:
        ValueError: When validation fails.
    """
    pass

Naming Conventions

Classes: PascalCase
Functions/methods: snake_case
Constants: UPPER_SNAKE_CASE
Private methods: _leading_underscore
Modules: lowercase or snake_case

Error Handling

Use custom exceptions from pathshield.exceptions
Provide meaningful error messages
Log errors appropriately
Don't catch generic Exception unless necessary

Example:

from pathshield.exceptions import AWSException
from pathshield.logger import get_logger

logger = get_logger(__name__)

try:
    result = some_aws_operation()
except ClientError as e:
    logger.error(f"AWS operation failed: {e}")
    raise AWSException(f"Failed to perform operation: {e}") from e

Testing

Test Structure

Unit tests: Test individual functions/methods
Integration tests: Test interactions between components
Use mocking for AWS API calls
Aim for >80% code coverage

Writing Tests

import pytest
from pathshield.services.ec2 import EC2ServicePlugin

class TestEC2Plugin:
    def test_collect(self, mock_session):
        plugin = EC2ServicePlugin(mock_session)
        resources = plugin.collect()
        assert len(resources) > 0
    
    def test_analyze_escalation(self, mock_session, mock_iam_graph):
        plugin = EC2ServicePlugin(mock_session)
        paths = plugin.analyze_escalation(mock_iam_graph)
        assert isinstance(paths, list)

Test Fixtures

Use pytest fixtures for common test data:

@pytest.fixture
def mock_session():
    # Return mock AWS session
    pass

@pytest.fixture
def mock_iam_graph():
    # Return mock IAM graph
    pass

Documentation

Updating Documentation

Update README.md for user-facing changes
Add docstrings to new functions/classes
Update CHANGELOG.md with your changes
Add examples for new features

Documentation Standards

Write clear, concise documentation
Include code examples
Document parameters and return values
Explain complex logic with comments

Submitting Changes

Branch Naming

Use descriptive branch names:

feature/add-rds-plugin
bugfix/fix-iam-parsing
docs/update-readme
test/add-lambda-tests

Commit Messages

Write clear, descriptive commit messages:

Add RDS service plugin for privilege escalation detection

- Implement RDS resource collection
- Add escalation path analysis
- Include tests for RDS plugin
- Update documentation

Fixes #123

Format:

First line: Short summary (50 chars or less)
Blank line
Detailed description if needed
Reference issues/PRs

Issue Guidelines

Reporting Bugs

When reporting bugs, include:

PathShield version
Python version
Operating system
Steps to reproduce
Expected behavior
Actual behavior
Error messages/logs
AWS region (if applicable)

Feature Requests

When requesting features, include:

Use case description
Proposed solution
Alternatives considered
Impact on existing functionality

Pull Request Process

Before submitting:
- Update documentation
- Add/update tests
- Run all tests locally
- Format code with Black
- Check with Flake8 and mypy
Submitting PR:
- Fill out the PR template
- Link related issues
- Provide clear description
- Add screenshots/examples if applicable
Review process:
- Maintainers will review your PR
- Address review comments
- Make requested changes
- Keep PR up to date with main branch
After approval:
- PR will be merged by maintainers
- Your contribution will be in the next release

PR Checklist

Development Workflow

Recommended Git Workflow

# Update your fork
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "Add my feature"

# Push to your fork
git push origin feature/my-feature

# Create pull request on GitHub

Keeping Your Fork Updated

# Add upstream remote (once)
git remote add upstream https://github.com/pathshield/pathshield.git

# Fetch and merge upstream changes
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Code Review Guidelines

For Contributors

Respond to review comments promptly
Be open to feedback
Ask questions if unclear
Update PR based on feedback

For Reviewers

Be constructive and respectful
Explain reasoning for changes
Approve when requirements met
Help contributors improve

Getting Help

If you need help:

Check existing documentation
Search existing issues
Ask questions in issues/discussions
Contact maintainers

Recognition

Contributors will be:

Listed in CONTRIBUTORS.md
Mentioned in release notes
Credited in commit history

License

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

Thank you for contributing to PathShield! 🛡️

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History