PathShield - AWS Cloud Privilege Escalation Attack Path Scanner

Overview

PathShield is an advanced AWS security scanning tool that discovers privilege escalation paths attackers could exploit. It analyzes IAM relationships, cross-service interactions, and identifies potential attack vectors that could lead to privilege escalation.

Features

• 🔍 IAM Trust Graph Analysis - Map and analyze IAM trust relationships
• 🚨 Cross-Service Escalation Detection - Identify escalation paths across EC2, Lambda, S3, KMS, RDS
• 🔧 CI/CD Ready - Terraform and CloudFormation plan scanning
• 📊 Multi-Format Reporting - CLI, JSON, SARIF, and HTML dashboards
• 🐳 Docker Support - Containerized deployment
• 📈 Plugin Architecture - Extensible design for new services

Installation

Using pip

pip install pathshield

Using Docker

docker pull pathshield/pathshield:latest
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  pathshield/pathshield:latest \
  scan --region us-east-1

From Source

git clone https://github.com/pathshield/pathshield.git
cd pathshield
pip install -e ".[dev]"

Quick Start

Basic IAM Scan

# Scan IAM for privilege escalation paths
pathshield scan --region us-east-1

# With verbose output
pathshield scan --region us-east-1 --verbose

Terraform Plan Scanning

# Generate Terraform plan
terraform plan -out=tfplan

# Convert to JSON (required)
terraform show -json tfplan > tfplan.json

# Scan with PathShield
pathshield scan --terraform tfplan.json --output results.json

CI/CD Integration

# SARIF output for GitHub Advanced Security
pathshield scan --region us-west-2 --format sarif --output results.sarif

Configuration

PathShield can be configured via a YAML configuration file:

# config.yaml
aws:
  profile: "default"
  region: "us-east-1"
  role_arn: "arn:aws:iam::123456789:role/PathShieldRole"

logging:
  level: "INFO"
  verbose: false

output:
  format: "cli"

Environment Variables

Variable	Description
PATHSHIELD_AWS_PROFILE	AWS profile name
PATHSHIELD_AWS_REGION	AWS region
PATHSHIELD_LOGGING_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR)
PATHSHIELD_OUTPUT_FORMAT	Output format (cli, json, sarif, html)

Usage

CLI Commands

# Show help
pathshield --help

# Scan command
pathshield scan --help

# Show version
pathshield version

# Show configuration
pathshield config

Scan Options

Option	Description
--region	AWS region (default: us-east-1)
--profile	AWS profile name
--output	Output format: cli, json, sarif, html
--output-file	Path to output file
--max-depth	Maximum path depth (default: 5)
--verbose	Enable verbose output
--config	Path to configuration file

Architecture

Core Components

PathShield/
├── pathshield/
│   ├── main.py              # CLI entry point
│   ├── config.py            # Configuration management
│   ├── logger.py            # Logging setup
│   ├── exceptions.py        # Custom exceptions
│   ├── aws/
│   │   └── session.py       # AWS session management
│   ├── iam/
│   │   └── analyzer.py      # IAM analysis engine
│   ├── services/
│   │   ├── base.py          # Plugin base class
│   │   └── ec2.py           # EC2 service plugin
│   ├── output/
│   │   └── base.py          # Output formatters
│   └── cicd/
│       └── integration.py   # CI/CD integrations

Plugin System

PathShield uses a plugin-based architecture for service analysis:

1. BaseServicePlugin - Abstract base class for all plugins
2. Service Plugins - EC2, Lambda, S3, KMS, RDS
3. Output Formatters - CLI, JSON, SARIF, HTML

Escalation Path Detection

PathShield identifies common escalation techniques:

• PassRole + EC2 - Attach privileged role to EC2 instance
• PassRole + Lambda - Create Lambda with privileged execution role
• UpdateAssumeRolePolicy - Modify trust policy to assume role
• AttachRolePolicy - Attach policies to gain privileges

Development

Setup

# Install development dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install

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

# Code formatting
black pathshield/ tests/
flake8 pathshield/ tests/

Adding a New Service Plugin

from pathshield.services.base import BaseServicePlugin, ServiceEscalationPath

class MyServicePlugin(BaseServicePlugin):
    name = "myservice"
    version = "1.0.0"
    description = "My service escalation detection"
    
    def collect(self):
        # Collect resources from the service
        pass
    
    def analyze_escalation(self, iam_graph):
        # Analyze for escalation paths
        pass

CI/CD Integration

GitHub Actions

name: PathShield Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run PathShield
        run: |
          pip install pathshield
          pathshield scan --format sarif --output results.sarif
      - name: Upload SARIF
        uses: github/sarif-upload@v1
        with:
          sarif_file: results.sarif

Output Formats

CLI Output

PathShield - AWS Privilege Escalation Scanner
==============================================

Scanning region: us-east-1
Found 3 potential escalation paths:

[CRITICAL] user:developer -> role:ec2-admin
Technique: EC2 Instance Profile Privilege Escalation

[HIGH] user:lambda-tester -> role:kms-admin
Technique: Lambda Role Chaining

JSON Output

{
  "scan_timestamp": "2024-01-01T00:00:00Z",
  "escalation_paths": [
    {
      "source": {"name": "developer", "type": "user"},
      "target": {"name": "ec2-admin", "type": "role"},
      "technique": "EC2 Instance Profile",
      "severity": "critical"
    }
  ]
}

SARIF Output

Standard SARIF 2.1.0 format for integration with security tools.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

• AWS IAM documentation
• Cloud Security research community
• Open source security tools