PathShield Quick Start Guide

Welcome to PathShield! This guide will help you get started with scanning your AWS environment for privilege escalation paths in just a few minutes.

What is PathShield?

PathShield is an AWS security scanner that discovers potential privilege escalation paths in your cloud infrastructure. It analyzes IAM relationships, cross-service interactions, and identifies attack vectors that could lead to unauthorized privilege escalation.

Prerequisites

Before you begin, ensure you have:

Python 3.9 or higher installed
AWS CLI configured with credentials
AWS Account with appropriate IAM permissions
pip package manager

Check your Python version:

python3 --version

Installation

Option 1: Install from PyPI (Recommended)

pip install pathshield

Option 2: Install from Source

git clone https://github.com/pathshield/pathshield.git
cd pathshield
pip install -e .

Option 3: Using Docker

docker pull pathshield/pathshield:latest

Quick Start - Your First Scan

1. Configure AWS Credentials

Ensure your AWS credentials are configured. PathShield uses the standard AWS credential chain:

# Configure AWS CLI if not already done
aws configure

# Verify credentials
aws sts get-caller-identity

2. Run Your First Scan

Basic Scan (CLI Output)

pathshield scan --region us-east-1

This will:

Scan IAM users, roles, and groups
Analyze EC2, Lambda, S3, and KMS resources
Display results in your terminal with color-coded severity levels

Save Results to JSON

pathshield scan --region us-east-1 --output json --output-file results.json

Generate HTML Dashboard

pathshield scan --region us-east-1 --output html --output-file dashboard.html

Open dashboard.html in your browser to view an interactive report.

Verbose Output

pathshield scan --region us-east-1 --verbose

Understanding the Output

Severity Levels

PathShield assigns severity levels to each detected escalation path:

CRITICAL 🔴 - Direct path to admin privileges, immediate action required
HIGH 🟡 - Significant escalation potential, should be addressed soon
MEDIUM 🔵 - Moderate risk, review and remediate
LOW 🟢 - Minor concern, consider fixing during maintenance

Sample Output

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

IAM Graph Summary:
  Total Principals: 45
  Users: 12
  Roles: 30
  Groups: 3
  Trust Relationships: 18

[!] Found 3 potential escalation paths:

[1] [CRITICAL]
    Source: developer-user (user)
    Target: admin-role (role)
    Technique: PassRole + CreateFunction
    Description: developer-user can create a Lambda function with privileged 
                 role admin-role and then invoke it to execute code with 
                 elevated privileges.
    Path Length: 2 hops

Common Use Cases

1. Security Audit

Perform a comprehensive security audit of your AWS account:

pathshield scan \
  --region us-east-1 \
  --output html \
  --output-file security-audit-$(date +%Y%m%d).html \
  --verbose

2. CI/CD Pipeline Integration

Generate SARIF output for GitHub Advanced Security:

# In your CI/CD pipeline
pathshield scan \
  --region us-east-1 \
  --output sarif \
  --output-file results.sarif

# Upload to GitHub (if using GitHub Actions)
# This will appear in the Security tab

3. Multi-Region Scan

Scan multiple AWS regions:

for region in us-east-1 us-west-2 eu-west-1; do
  echo "Scanning $region..."
  pathshield scan \
    --region $region \
    --output json \
    --output-file results-$region.json
done

4. Scan with Assumed Role

Scan another AWS account by assuming a role:

# Create a config file
cat > config.yaml << EOF
aws:
  profile: "default"
  region: "us-east-1"
  role_arn: "arn:aws:iam::123456789012:role/SecurityAuditRole"
  session_duration: 3600
EOF

# Run scan with config
pathshield --config config.yaml scan

Configuration

Using Configuration File

Create a config.yaml file:

aws:
  profile: "default"
  region: "us-east-1"

logging:
  level: "INFO"
  verbose: false

output:
  format: "cli"

analysis:
  services:
    - ec2
    - lambda
    - s3
    - kms
    - iam
  depth: 3

Run with configuration:

pathshield --config config.yaml scan

Using Environment Variables

export PATHSHIELD_AWS_PROFILE=production
export PATHSHIELD_AWS_REGION=us-east-1
export PATHSHIELD_LOGGING_LEVEL=DEBUG

pathshield scan

Required IAM Permissions

PathShield requires read-only IAM permissions. Here's a minimal policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetUser",
        "iam:GetRole",
        "iam:GetGroup",
        "iam:ListUsers",
        "iam:ListRoles",
        "iam:ListGroups",
        "iam:ListAttachedUserPolicies",
        "iam:ListAttachedRolePolicies",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "ec2:DescribeInstances",
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "s3:ListAllMyBuckets",
        "s3:GetBucketPolicy",
        "kms:ListKeys",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    }
  ]
}

Using Docker

Run a Scan

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

Save Results

docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  -v $(pwd)/results:/results \
  pathshield/pathshield:latest \
  scan --region us-east-1 --output json --output-file /results/scan.json

Using docker-compose

Create docker-compose.yml:

version: '3.8'
services:
  pathshield:
    image: pathshield/pathshield:latest
    volumes:
      - ~/.aws:/root/.aws:ro
      - ./results:/results
    command: scan --region us-east-1 --output json --output-file /results/scan.json

Run:

docker-compose up

Troubleshooting

Issue: "No credentials found"

Solution: Configure AWS credentials:

aws configure
# or
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

Issue: "Access Denied" errors

Solution: Ensure your IAM user/role has the required read permissions. Check the IAM policy section above.

Issue: "Region not specified"

Solution: Explicitly specify the region:

pathshield scan --region us-east-1

Or set default region:

export AWS_DEFAULT_REGION=us-east-1

Issue: Scan is slow

Solution:

Reduce analysis depth:

pathshield scan --region us-east-1 --max-depth 2

Scan specific services only (create config.yaml):

analysis:
  services:
    - iam
    - ec2

Issue: Too many results

Solution: Filter by severity in your analysis workflow, or use JSON output and process programmatically:

pathshield scan --region us-east-1 --output json --output-file results.json
# Then use jq to filter
jq '.escalation_paths[] | select(.severity == "critical")' results.json

Tips and Best Practices

1. Start with a Test Account

Run your first scans on a non-production AWS account to familiarize yourself with the tool.

2. Regular Scans

Schedule regular scans (weekly/monthly) to track your security posture over time:

# Add to cron
0 2 * * 1 /usr/local/bin/pathshield scan --region us-east-1 --output json --output-file /var/log/pathshield/scan-$(date +\%Y\%m\%d).json

3. Integrate with CI/CD

Add PathShield to your CI/CD pipeline to catch privilege escalation paths before they reach production.

4. Review and Remediate

Focus on CRITICAL and HIGH severity issues first
Document false positives
Track remediation progress

5. Use Verbose Mode for Investigation

When investigating a specific path, use verbose mode to see detailed information:

pathshield scan --region us-east-1 --verbose

Next Steps

Now that you've completed your first scan, here's what to do next:

Review the Results
- Understand each detected escalation path
- Assess the risk in your specific context
Remediate Issues
- Start with CRITICAL severity paths
- Apply least-privilege principles
- Update IAM policies
Learn More
- Read the full README
- Check CONTRIBUTING.md to contribute
- Review SECURITY.md for security best practices
Automate
- Set up scheduled scans
- Integrate with your security monitoring
- Create dashboards for tracking
Get Help
- Open an issue on GitHub
- Check existing issues for solutions
- Join our community discussions

Quick Reference

Common Commands

# Basic scan
pathshield scan --region us-east-1

# Show version
pathshield version

# Show current config
pathshield config

# Verbose scan with JSON output
pathshield scan --region us-east-1 --verbose --output json --output-file results.json

# Scan with custom config
pathshield --config myconfig.yaml scan

# HTML report
pathshield scan --region us-east-1 --output html --output-file report.html

# SARIF for CI/CD
pathshield scan --region us-east-1 --output sarif --output-file results.sarif

Output Formats

Format	Use Case	File Extension
cli	Terminal viewing	N/A
json	Programmatic processing	.json
sarif	CI/CD integration	.sarif
html	Dashboard/Reports	.html

Example Workflow

Here's a complete workflow from installation to remediation:

# 1. Install
pip install pathshield

# 2. Verify installation
pathshield version

# 3. Run initial scan
pathshield scan --region us-east-1 --output html --output-file initial-scan.html

# 4. Review results in browser
open initial-scan.html

# 5. Export for analysis
pathshield scan --region us-east-1 --output json --output-file analysis.json

# 6. After remediation, run another scan
pathshield scan --region us-east-1 --output html --output-file post-remediation.html

# 7. Compare results
# (Use your preferred diff tool or custom script)

Support

Documentation: README.md
Issues: GitHub Issues
Security: SECURITY.md
Contributing: CONTRIBUTING.md

Happy Scanning! 🛡️

Remember: PathShield is a tool to help identify potential privilege escalation paths. Always validate findings and apply fixes according to your organization's security policies.

FilesExpand file tree

QUICKSTART.md

Latest commit

History