Pathfinder

Cloud trust chain mapper. Discovers and maps all inbound trust relationships across cloud environments, resolves transitive chains, and shows what an attacker can reach if any link is compromised.

Features

• Trust Source Discovery — Enumerate all inbound trust relationships: cross-account role assumptions, SAML/OIDC federation, resource-based policies, service principals
• Chain Resolution — Walk the full transitive trust chain from any entry point to every reachable resource
• Risk Scoring — 7-dimension weighted scoring: chain depth, entry point type, terminal resource, external trust, condition scoping, privilege level, credential durability
• Analysis Engine — 5 analyzers: cross-account trust, privilege escalation, circular trust, overly permissive trust, stale external trust
• Drift Detection — Compare snapshots over time to detect new, removed, or changed trust chains
• What-If Simulation — Simulate adding/removing trust edges and see the impact before making changes
• Baseline Allowlisting — Accept known chains and only report new or changed findings
• Scan Caching — Cache results locally to avoid redundant API calls
• CI/CD Ready — SARIF output for GitHub Security, exit codes for pipeline gating, config file for consistent defaults
• AWS Coverage — 17 services with resource-based policy support (S3, KMS, Lambda, SQS, SNS, Secrets Manager, ECR, EventBridge, API Gateway, CloudWatch Logs, Backup, CodeBuild, OpenSearch, CodeArtifact, EFS, Glacier, MediaStore)
• Output Formats — Table, JSON, Markdown, Graphviz DOT, SARIF 2.1.0

Installation

go install github.com/0xsj/pathfinder@latest

Or build from source:

git clone https://github.com/0xsj/pathfinder.git
cd pathfinder
go build -o pathfinder ./cmd/pathfinder

Quick Start

# Discover all trust chains in your AWS account
pathfinder scan

# Only show HIGH and CRITICAL findings
pathfinder scan --min-severity high

# Output as SARIF for GitHub Security
pathfinder scan --output sarif > results.sarif

# Fail CI if HIGH or CRITICAL findings exist
pathfinder scan --fail-on high

# Use caching to skip redundant API calls
pathfinder scan --cache

# Create a baseline of accepted chains
pathfinder baseline -f baseline.json

# Only report new findings against baseline
pathfinder scan --baseline baseline.json

Usage

scan

Enumerate all trust relationships and resolve chains:

pathfinder scan [flags]

Flag	Description	Default
--provider	Cloud provider	aws
--profile	AWS profile name	default
--account-id	Target AWS account ID	auto
--region	AWS region	from profile/env
--regions	Multi-region scan (comma-separated)	none
--output / -o	Output format (table, json, markdown, dot, sarif)	table
--max-depth	Maximum chain depth	10
--min-severity	Minimum severity to display	none
--fail-on	Exit code 2 if findings at/above severity	none
--baseline	Baseline file — only report new/changed	none
--cache	Enable scan result caching	false
--refresh	Force re-scan ignoring cache	false
--include-services	Include AWS service principals	false

trace

Trace the full trust chain from a specific entry point:

pathfinder trace --entry-point <arn> [flags]

export

Export scan results as a snapshot for drift comparison:

pathfinder export -f snapshot.json

baseline

Create a baseline to suppress known findings:

pathfinder baseline -f baseline.json

diff

Compare two snapshots and show drift:

pathfinder diff old.json new.json
pathfinder diff old.json new.json --output json

simulate

Simulate trust chain changes:

# What happens if we remove an external trust?
pathfinder simulate \
  --remove-edge "arn:aws:iam::999:role/Ext|arn:aws:iam::111:role/Admin|TrustsExternal"

# What happens if we add a new trust relationship?
pathfinder simulate \
  --add-edge "arn:aws:iam::222:role/CI|arn:aws:iam::111:role/Deploy|CanAssume"

Configuration

Config File

Pathfinder reads defaults from ~/.pathfinder.json:

{
  "min_severity": "medium",
  "output": "table",
  "max_depth": 10,
  "provider": "aws",
  "cache": true,
  "cache_ttl": "2h",
  "profile": "production"
}

CLI flags override config file values.

AWS Credentials

Pathfinder reads AWS credentials from the standard credential chain:

# Environment variables
export AWS_PROFILE=production
export AWS_REGION=us-east-1

# Or pass directly
pathfinder scan --profile production --region us-east-1

CI/CD Integration

GitHub Actions

- name: Scan trust chains
  run: pathfinder scan --output sarif --fail-on high > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Baseline Workflow

# On main branch: update baseline
- run: pathfinder baseline -f baseline.json

# On PRs: report only new findings
- run: pathfinder scan --baseline baseline.json --fail-on high

Requirements

• Go 1.22+
• AWS credentials with read-only access:
  • iam:ListRoles, iam:GetRole, iam:ListPolicies, iam:GetPolicy, iam:GetPolicyVersion
  • iam:ListRolePolicies, iam:GetRolePolicy
  • sts:GetCallerIdentity
  • Service-specific read permissions for resource policy enumeration (S3, KMS, Lambda, etc.)

License

MIT