feat: CIEM effective permissions engine (Phase 3)

[therandomsecurityguy]

CIEM / Effective Permissions Engine

Implements the full Cloud Infrastructure Entitlement Management (CIEM) system for computing effective IAM permissions, detecting escalation paths, identifying unused permissions, and generating rightsizing recommendations.

What's New

Enhanced IAM Collector (lambdas/collector/index.ts)

• Fetches IAM groups, inline policies (user/role/group), managed policy documents
• Parses trust policies (AssumeRolePolicyDocument) into TRUSTS edges
• Decomposes policy documents into individual IamPolicyStatement nodes
• Tracks permission boundaries via HAS_PERMISSION_BOUNDARY edges
• New Neptune node types: IamGroup, IamPolicyDocument, IamPolicyStatement
• New Neptune edge types: MEMBER_OF, ATTACHED_TO, CONTAINS, GRANTS, TRUSTS, HAS_PERMISSION_BOUNDARY

Policy Evaluator Lambda (lambdas/policy-evaluator/)

• policy-parser.ts: IAM policy JSON parsing, wildcard matching (*, ?, s3:Get*), trust policy extraction
• condition-evaluator.ts: 20+ IAM condition operators (StringEquals, IpAddress/CIDR, ArnEquals, Bool, Numeric, Date, Null), service-specific condition keys (aws, s3, kms, ec2, lambda, dynamodb, rds, ssm)
• effect-resolver.ts: Resolves identity + resource + session policies against permission boundaries and SCPs following AWS evaluation rules (explicit deny > allow > implicit deny). Wildcards expanded through boundaries.
• escalation-detector.ts: Trust graph traversal (max 3 hops configurable), detects admin/privilege_escalation/lateral_movement paths, deduplication, account filtering
• rightsizer.ts: Computes unused permissions by comparing effective permissions vs CloudTrail usage, generates least-privilege recommendations with risk-level classification (low/medium/high), configurable safety margin and read-only preservation

CloudTrail Analyzer Lambda (lambdas/cloudtrail-analyzer/)

• Athena queries against CloudTrail S3 logs (90-day configurable window)
• Groups by principal/eventSource/eventName with COUNT and MAX timestamps
• Writes results to AccessAnalyzerCache DynamoDB table (TTL: 90 days, GSI: ActionIndex)

API Endpoints (api-service/src/routes/identity.ts)

• GET /identity/effective-permissions/:principal — Computed net effective permissions
• GET /identity/escalation-paths — Detected escalation paths with filters (riskLevel, escalationType, sourceAccount, targetRole)
• GET /identity/unused-permissions?principal=X&days=90 — Unused actions grouped by service
• GET /identity/rightsizing/:principal?safetyMarginDays=7 — Least-privilege policy recommendation
• GET /identity/trust-graph?account=X — Cross-account trust relationships as graph

CDK Stack Updates (cdk/lib/khalifa-stack.ts)

• PolicyEvaluator Lambda (1024MB, 15min timeout)
• CloudTrailAnalyzer Lambda (512MB, 5min timeout) with Athena + DynamoDB + Glue + S3 IAM policies
• AccessAnalyzerCache DynamoDB table (PAY_PER_REQUEST, TTL, GSI)
• Step Function: Added PolicyEvaluator step after GraphWriter
• EventBridge: Policy evaluator every 6h, CloudTrail analyzer daily at 02:00 UTC

NeptuneClient Additions (api-service/src/services/neptune-client.ts)

• getEffectivePermissions() — Query EffectivePermission nodes
• getEscalationPaths() — Query EscalationPath nodes with filters
• getTrustGraph() — Retrieve TRUSTS edges with connected nodes

Tests (89 passing, 5 suites)

Suite	Tests	Coverage
policy-parser.test.ts	27	Policy parsing, wildcard matching, trust policy
condition-evaluator.test.ts	20	All operators, condition blocks, Null
effect-resolver.test.ts	12	Allow/deny, boundaries, SCPs, conditional grants
escalation-detector.test.ts	16	Admin paths, chained trust, maxHops, lateral movement
rightsizer.test.ts	14	Unused perms, rightsizing, risk levels, read-only safety

Files Changed

• Modified (7): collector, api-service (app, types, neptune-client, package.json), CDK stack, top-level package.json
• New (20): policy-evaluator (8 source + 5 test + config), cloudtrail-analyzer (1 source + config), identity routes, types
• +3,672 lines across 28 files

Architecture Decisions

• Athena over S3 logs for CloudTrail analysis (scales better, supports 90-day window)
• Policy evaluator as new Step Function step after graph-writer (sequential guarantee)
• Max 3 hops for trust chain traversal (catches real escalation paths, fast queries)
• Pre-compute + cache EffectivePermission nodes in Neptune (fast API reads)
• 89 unit tests, all typechecks pass