Skip to content

TODO.md

Latest commit

 

History

History
174 lines (140 loc) · 4.82 KB

TODO.md

File metadata and controls

174 lines (140 loc) · 4.82 KB

PathShield Development Roadmap

Project Overview

PathShield - AWS Cloud Privilege Escalation Attack Path Scanner

Development Status: ✅ COMPLETE

Core Package Structure

PathShield/
├── pathshield/                      # Main Python package
│   ├── __init__.py                  # Package initialization
│   ├── main.py                      # CLI entry point (Click-based)
│   ├── config.py                    # Configuration management (Pydantic)
│   ├── logger.py                    # Logging setup (Rich)
│   ├── exceptions.py                # Custom exceptions hierarchy
│   ├── aws/
│   │   ├── __init__.py              # AWS module exports
│   │   └── session.py               # AWS session + rate limiting
│   ├── iam/
│   │   ├── __init__.py              # IAM module exports
│   │   └── analyzer.py              # IAM graph + escalation detection
│   ├── services/
│   │   ├── __init__.py              # Services module exports
│   │   ├── base.py                  # Base plugin interface
│   │   └── ec2.py                   # EC2 escalation plugin
│   ├── output/
│   │   ├── __init__.py              # Output module exports
│   │   └── base.py                  # Output formatters (CLI, JSON, SARIF, HTML)
│   └── cicd/
│       ├── __init__.py              # CI/CD module exports
│       └── integration.py           # Terraform, CloudFormation, GitHub Actions
├── tests/
│   ├── __init__.py
│   └── test_pathshield.py           # Unit tests (pytest)
├── config.yaml                      # Configuration file
├── pyproject.toml                   # Project metadata & dependencies
├── requirements.txt                 # Core dependencies
├── README.md                        # Comprehensive documentation
└── .gitignore                       # Git ignore rules

Key Features Implemented

1. Advanced Exception Handling

  • PathShieldException - Base exception class
  • AWSException - AWS API related exceptions
  • ThrottlingException - AWS API throttling with retry
  • AuthenticationException - AWS authentication failures
  • AuthorizationException - AWS authorization denials
  • ConfigurationException - Configuration errors
  • AnalysisException - Analysis/scanning errors

2. Configuration Management (Pydantic)

  • AWS configuration (profile, region, role ARN, MFA)
  • Logging configuration (level, format, file)
  • Output configuration (format, verbose)
  • Analysis configuration (services, depth, metadata)
  • Environment variable overrides
  • Configuration file loading

3. AWS Session Management

  • Boto3 session handling with profile support
  • Role assumption support
  • Automatic credential refresh
  • Rate limiting with exponential backoff
  • Error handling for API calls

4. IAM Analysis Engine

  • Graph-based IAM relationship mapping
  • Trust relationship analysis
  • Permission boundary evaluation
  • Privilege escalation path detection
  • BFS-based path finding algorithm
  • Severity calculation

5. Service Plugins

  • Base plugin interface (BaseServicePlugin)
  • EC2 service plugin for:
    • Instance profile privilege escalation
    • PassRole detection
  • Extensible architecture for new services

6. Output Engines

  • CLI - Rich console output with colors
  • JSON - Structured JSON output
  • SARIF - Standard format for CI/CD
  • HTML - Interactive dashboard

7. CI/CD Integration

  • Terraform plan parser
  • CloudFormation template analyzer
  • GitHub Actions workflow generator
  • LocalStack integration for testing

Usage

Installation

# From PyPI
pip install pathshield

# From source
pip install -e ".[dev]"

Basic Scan

pathshield scan --region us-east-1

Terraform Plan Scanning

pathshield scan --terraform tfplan.json --format sarif --output results.sarif

Configuration

# config.yaml
aws:
  profile: "default"
  region: "us-east-1"

logging:
  level: "INFO"

output:
  format: "cli"

Testing

# Run all tests
pytest tests/ -v --cov=pathshield

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

Next Steps

  1. Install dependencies: pip install -e ".[dev]"
  2. Run tests: pytest tests/ -v
  3. Build Docker image: docker build -t pathshield .
  4. Execute scan: pathshield scan --region us-east-1

Dependencies

Core

  • boto3 - AWS SDK
  • click - CLI framework
  • rich - Terminal output
  • pyyaml - Configuration
  • pydantic - Data validation
  • networkx - Graph analysis
  • jinja2 - HTML templating

Development

  • pytest - Testing
  • black - Code formatting
  • flake8 - Linting
  • mypy - Type checking

Version

  • Current: 0.1.0
  • Python: 3.9+
  • License: MIT