Skip to content

CLAUDE.md

Latest commit

 

History

History
349 lines (263 loc) · 14.4 KB

CLAUDE.md

File metadata and controls

349 lines (263 loc) · 14.4 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

When to Use Each File

  • CLAUDE.md (this file): Workflow guidance, commands, development tasks, and quick references
  • SCHEMA.md: Authoritative field definitions, validation rules, and format specifications
  • .claude/CLAUDE.md: Anti-patterns, style guide, and contribution-specific guidance

Rule of thumb: Check SCHEMA.md for "what does field X mean?", check this file for "how do I do task Y?"

Project Overview

pathfinding.cloud is a comprehensive, community-maintained library documenting AWS IAM privilege escalation paths. The project consists of:

  1. Data Layer: Structured YAML files documenting each privilege escalation path
  2. Validation Layer: Python scripts to validate YAML against schema
  3. Website Layer: Static HTML/CSS/JS site for browsing paths
  4. CI/CD Layer: GitHub Actions for validation and deployment

Terminology: Parent/Child vs Primary/Variant

We use different terminology in different contexts for clarity and semantic meaning:

In YAML Files and Code

  • parent field: Points to the parent path (e.g., parent.id: iam-002)
  • Why: Concise, follows common data structure conventions, natural for hierarchical references

In UI and Documentation

  • "Primary Technique": The foundational/original technique (what YAML calls the "parent")
  • "Variant": A modification that expands applicability by removing prerequisites (what YAML calls the "child")
  • Why: Semantic clarity - "variant" explains WHAT it is, not just that there's a hierarchy

Key Concepts

  • Primary techniques have no parent field - they are the foundational attacks
  • Variant techniques have a parent field with id and modification
  • Variants add required permissions that remove prerequisites from the primary technique
  • Example: IAM-002 (primary) requires < 2 keys. IAM-003 (variant) adds DeleteAccessKey to work even with 2 keys.

When Contributing

  • In YAML: Use parent field for variants
  • In documentation/comments: Refer to "primary techniques" and "variants"
  • In UI text: Display "Primary Technique" and "Variants (N)"

See SCHEMA.md for detailed parent/child relationship criteria.

Quick Start Commands

Essential Commands

# Install dependencies
pip install -r requirements.txt

# Validate a single file
python scripts/validate-schema.py data/paths/{service}/{service}-###.yaml

# Validate all files
python scripts/validate-schema.py data/paths/

# Generate JSON for website
python scripts/generate-json.py

# Test website locally (with SPA routing support)
cd docs && python3 dev-server.py
# Then visit http://localhost:8888

GitHub Token for Better Contributor Info

# Set GitHub token (optional but recommended)
export GITHUB_TOKEN=your_github_pat_here
python scripts/generate-json.py

# Token scopes:
# - Private repos: 'repo' scope
# - Public repos: 'public_repo' scope
# Create at: https://github.com/settings/tokens/new

Architecture

Data Structure

All privilege escalation paths are stored as individual YAML files in data/paths/{service}/:

  • Files follow naming convention: {service}-{number}.yaml (e.g., iam-001.yaml)
  • Each file adheres to the schema defined in SCHEMA.md
  • Files are organized by primary service (iam, ec2, lambda, ssm, cloudformation, etc.)

ID Numbering Convention

  • IAM-focused paths: iam-001, iam-002, etc.
  • PassRole combinations: Use the service of the resource being created/manipulated
    • iam:PassRole+ec2:RunInstances → ec2-001 (not iam-###)
    • iam:PassRole+lambda:CreateFunction → lambda-001
  • Other services: ssm-001, ec2-002, etc.
  • Sequential numbering: IDs are assigned sequentially within each service

Website Architecture (SPA with Client-Side Routing)

The website is a Single Page Application (SPA) with client-side routing:

  • List view: / - Shows all paths with search/filter functionality
  • Detail view: /paths/{id} - Shows individual path details (e.g., /paths/iam-001)
  • Routing: Uses History API (pushState/popState) for proper URLs
  • No page reloads: Navigation is instant, only content changes
  • SEO ready: Dynamic meta tags per page, Open Graph support
  • Analytics ready: Real pageviews on route changes
  • Backward compatible: Old hash URLs (#iam-001) redirect to new format

Directory Structure:

  • All website files are in the docs/ directory (GitHub Pages compatible)
  • Source data (YAML files) remain at data/paths/ in repository root
  • Generated files (paths.json, metadata.json) are created in docs/

Development:

  • Use docs/dev-server.py for local testing (handles SPA routing)
  • Run from project root: cd docs && python3 dev-server.py
  • Direct file opening won't support routing features

Production (GitHub Pages):

  • GitHub Pages deploys only the docs/ directory
  • 404.html implements the SPA routing pattern for GitHub Pages
  • When users access direct URLs (e.g., /paths/iam-001), GitHub Pages serves 404.html
  • The 404 page captures the requested path in sessionStorage and redirects to index.html
  • The client-side router in docs/js/app.js reads sessionStorage and restores the original URL
  • This allows direct linking and page refreshes to work correctly on GitHub Pages
  • All URLs work when shared, bookmarked, or accessed directly

Contribution Workflow

Adding a New Path

  1. Determine the next ID:

    ls data/paths/{service}/ | sort | tail -n 1

  2. Create YAML file: data/paths/{service}/{service}-{number}.yaml

  3. Follow the schema: See SCHEMA.md for complete field definitions

  4. Validate:

    python scripts/validate-schema.py data/paths/{service}/{service}-{number}.yaml

  5. Enhance with specialized agents (optional but recommended):

    • Use detection-tools agent to add detection tool coverage
    • Use learning-environments agent to add practice labs
    • Use add-vis agent to add attack visualization
    • Use attribution agent to find discoverer information

  6. Generate JSON and test:

    python scripts/generate-json.py
cd docs && python3 dev-server.py

  7. Submit PR (validation runs automatically)

Updating Existing Paths

  • Always validate after editing
  • Check relatedPaths field to ensure consistency with related paths
  • Update the website by regenerating JSON: python scripts/generate-json.py

Adding a New Service

  1. Create directory: mkdir data/paths/{service}
  2. Add first path: data/paths/{service}/{service}-001.yaml
  3. The service will automatically appear in website filters once deployed

Field Quick Reference

For complete field specifications, see SCHEMA.md.

Required Fields

Field Type Quick Description Details
id string Unique identifier (e.g., iam-001) SCHEMA.md
name string IAM permission syntax (e.g., iam:PassRole + ec2:RunInstances) SCHEMA.md
category enum Type of escalation (self-escalation, principal-access, new-passrole, credential-access, existing-passrole) SCHEMA.md
services array AWS services involved (e.g., [iam, ec2]) SCHEMA.md
permissions object Required and additional permissions SCHEMA.md
description string How the privilege escalation works SCHEMA.md
exploitationSteps object Step-by-step commands for different tools SCHEMA.md
recommendation string Prevention and detection strategies SCHEMA.md
discoveryAttribution object Rich attribution info (author, source, derivatives) SCHEMA.md

Optional Fields (Commonly Used)

Field Type Quick Description Details
status enum draft for partial submissions, omit for complete CONTRIBUTING.md
prerequisites object/array Conditions required for escalation SCHEMA.md
limitations string When admin vs limited access is achieved SCHEMA.md
references array External links and documentation SCHEMA.md
relatedPaths array Related path IDs SCHEMA.md
detectionTools object Open source tools that detect this path SCHEMA.md
learningEnvironments object Practice labs and CTF environments SCHEMA.md
attackVisualization object Interactive attack flow diagram SCHEMA.md

YAML Field Order (Convention)

While not enforced by validation, this order improves readability:

  1. id, name, category, services
  2. permissions
  3. description
  4. prerequisites (if applicable)
  5. exploitationSteps
  6. recommendation
  7. limitations (if applicable - especially for PassRole paths)
  8. nextSteps (if applicable - guidance for multi-hop attacks)
  9. discoveryAttribution (required - rich attribution with author/source/derivatives)
  10. references (if available)
  11. relatedPaths (if applicable)
  12. detectionTools (if available - added by detection-tools agent)
  13. learningEnvironments (if available - added by learning-environments agent)
  14. attackVisualization (if available - added by add-vis agent)

Common Development Tasks

Fixing Validation Errors

Common issues:

  • ID format: Must be service-### with exactly 3 digits
  • Category: Must be one of: self-escalation, principal-access, new-passrole, credential-access, existing-passrole
  • Step numbering: Must start at 1 and be sequential
  • Required fields: All fields in REQUIRED_FIELDS dict must be present

Testing Website Changes

  1. Generate JSON: python scripts/generate-json.py
  2. Start dev server: cd docs && python3 dev-server.py
  3. Visit http://localhost:8888 in browser
  4. Test search, filters, path detail pages, and navigation
  5. Test direct URLs like http://localhost:8888/paths/iam-001
  6. Test browser back/forward buttons
  7. Check browser console for JavaScript errors

Note: The website uses client-side routing (SPA). Direct file opening won't support routing features (refresh, direct URLs). Always use the dev server for local testing.

Using Specialized Agents

Claude Code has specialized agents for enhancing attack paths:

  • detection-tools: Research and add detection tool coverage
  • learning-environments: Research and add practice labs
  • add-vis: Create interactive attack visualizations
  • attribution: Find discoverer and reference information

Run multiple agents concurrently for efficiency:

Can you task the detection-tools, learning-environments, add-vis, and attribution agents concurrently?

Validation Script

scripts/validate-schema.py checks:

  • All required fields are present
  • Field types match expectations
  • ID format is correct (service-###)
  • Category values are allowed
  • Prerequisites have valid types
  • Exploitation steps are numbered sequentially from 1
  • No unexpected fields

Draft Mode

The validation script supports draft submissions with relaxed requirements:

# Normal mode - allows drafts (for PRs)
python scripts/validate-schema.py data/paths/

# Strict mode - no drafts allowed (for main branch)
python scripts/validate-schema.py data/paths/ --no-draft

Draft paths (status: draft) only require: id, name, category, services, permissions.required, description Complete paths (no status) require all fields including exploitationSteps, recommendation, discoveryAttribution

Website Generation

The website loads data from docs/paths.json, which is generated from YAML files:

  1. GitHub Actions runs scripts/generate-json.py on every push to main
  2. This converts all YAML files to a single JSON file
  3. The website JavaScript loads and displays the JSON data
  4. Changes to YAML files automatically update the website

Key Files

  • SCHEMA.md: Complete field documentation and examples (authoritative reference)
  • .claude/CLAUDE.md: Anti-patterns, style guide, and contribution-specific guidance
  • CONTRIBUTING.md: Contribution guidelines with examples
  • README.md: Project overview and setup instructions
  • scripts/validate-schema.py: Validation logic (comprehensive checks)
  • scripts/generate-json.py: YAML to JSON converter
  • .github/workflows/validate.yml: PR validation workflow
  • .github/workflows/deploy.yml: GitHub Pages deployment workflow

Research Sources

When adding new paths, cite these primary sources where applicable:

  • Rhino Security Labs: Original 21 methods by Spencer Gietzen
  • Bishop Fox: IAM Vulnerable project, additional 10 paths
  • nccgroup: PMapper implementation details
  • AWS Documentation: Official IAM permission docs

GitHub Actions Workflows

Validate Workflow (.github/workflows/validate.yml)

  • Triggers on: PRs and pushes to main affecting YAML files
  • Runs: python scripts/validate-schema.py data/paths/
  • Comments on PR: Success/failure status

Deploy Workflow (.github/workflows/deploy.yml)

  • Triggers on: Pushes to main branch
  • Steps:
    1. Validate all YAML files
    2. Generate JSON from YAML
    3. Update website JavaScript to use JSON
    4. Deploy to GitHub Pages
  • Permissions: Requires pages: write and id-token: write

Code Style

Python Scripts

  • Use Python 3.11+ features
  • Follow PEP 8
  • Include docstrings for functions
  • Use type hints where helpful
  • Provide clear error messages

YAML Files

  • Use 2-space indentation
  • Multi-line strings use | for description and recommendation
  • List items use - prefix
  • Strings with special characters should be quoted

Website Code

  • Vanilla JavaScript (no frameworks)
  • Responsive CSS (mobile-first)
  • Accessible HTML (semantic tags, ARIA labels)
  • Progressive enhancement