# RoleTrail

Real-Time AWS IAM & Access Denied Intelligence Engine

Self-Defending Cloud

**RoleTrail** is a core pillar of **Self-Defending Cloud Infrastructure**. It detects, investigates, and responds to `AccessDenied` storms and unauthorized operations in real-time, while continuously diffing observed CloudTrail telemetry against active IAM policies to uncover and eliminate unused permissions.

[View RoleTrail on GitHub](https://github.com/jonathanbglass/roletrail) [Open Source Overview](https://jonathanglass.cloud/opensource.html) [Explore Fleet Marshal (CSPP)](https://jonathanglass.cloud/fleetmarshal.html) 100% API Calls Recorded 30–365d Lookback Windows < 1s AccessDenied Detection 0% Least-Privilege Guesswork

## A Core Engine for Self-Defending Cloud Infrastructure

In modern cloud environments, `AccessDenied` and `Client.UnauthorizedOperation` errors are not just troubleshooting nuisances—they are prime early-warning signals. Spikes in permission failures often indicate **active credential compromise, lateral movement reconnaissance, compromised compute instances, or broken CI/CD deployments**.

RoleTrail bridges the gap between IAM policy management and threat detection by providing actionable visibility into both successful calls and failure storms across entire AWS Organizations:

#### Rapid Access Denied Triage

Instantly correlates failure storms by `account_id + role_arn + iam_action`. Detects when assumed-role sessions attempt privilege escalation or scan restricted APIs before damage occurs.

#### True Least Privilege Diffing

Classifies every permission as **Used** (proven successful calls in window), **Unused** (allowed but never executed), or **Unknown** (actions outside management CloudTrail like PassRole).

#### Failure Isolation

Failed API attempts are counted and analyzed separately. Failed calls never falsely mark a permission as "used," preventing attacker probing from corrupting your least privilege baseline.

## Why RoleTrail Exists: The Tool Landscape

Existing IAM and CloudTrail tools either lack action-level call counts, ignore failure context, rely on service-only approximations, or charge prohibitive per-entity fees:

Tool Granularity Call Counts Failures & Access Denied Data Source **Netflix Aardvark + Repokid** Service last-accessed No No IAM Access Advisor (mutates inline policies) **IAM Access Analyzer Unused Access** Service + select actions No No IAM last-accessed (billed per entity) **Access Analyzer Policy Gen** Actions seen in CloudTrail No No CloudTrail (max 90-day window) **Duo-Labs CloudTracker** Action present / absent No Limited Athena over CloudTrail **RoleTrail (Self-Defending)** Action counts per role Yes (Daily Facts) Yes (AccessDenied & UnauthorizedOp) Org CloudTrail in S3 + CloudWatch Logs Stream

## Multi-Account Cloud Native Architecture

RoleTrail is engineered following strict AWS multi-account security best practices, cleanly isolating storage, analytics, and member workloads:

Member Accounts Logging Account Security Account ───────────────── ──────────────── ──────────────── IAM Roles & Policies ──┐ ┌── IAM Inventory (AssumeRole) Regional CloudWatch ───┼── Subscription Filters ──────────────►│ Firehose → Streaming Ingest │ │ └──────────────────────────────────────►│ Postgres (Prod) / SQLite (Local) Org CloudTrail (S3) ──────────── S3 Trail Bucket ─────────────►│ Athena + Glue Daily Rollup (Logging account holds files only) │ API + Next.js Dashboard

- **Logging Account**: Securely holds the immutable multi-account organization / Control Tower CloudTrail S3 bucket. It does not run compute or databases.
- **Security Account**: Reads the S3 bucket with KMS decryption, aggregates daily facts `(role, iam_action, outcome, day) → count`, ingests real-time CloudWatch streams, and serves the UI dashboard.
- **Dual-Pipeline Ingestion**: Combines **S3 batch** as the authoritative source of truth (~15 min latency) with **CloudWatch subscription filters** for instant real-time event upserts deduplicated on `eventID`.

## Core Capabilities

#### Assumed-Role Identity Resolution

Accurately resolves identities from `userIdentity.sessionContext.sessionIssuer`, properly attributing API calls to human engineers, CI/CD runners, and assumed roles while filtering out noisy AWS service events.

#### Multi-Lookback Analysis

Toggle seamlessly between 30, 60, 90, and 365-day observation windows to distinguish between high-frequency daily operations and legitimate annual disaster recovery or audit workflows.

#### Terraform StackSet Deployment

Includes complete modular Terraform configurations for the Logging account bucket policy, Security account warehouse (Athena, Glue, Firehose), and Member account subscription filters via StackSets.

#### Bounded Failure Storm Alerting

Groups new `AccessDenied` exceptions by `account_id + role_arn` to emit bounded EventBridge/SNS alerts without overwhelming responders with duplicate notification floods.

#### Interactive Local & Cloud UI

Built with Next.js and TypeScript, providing searchable role matrices, visual unused-action diffs, failure breakdown charts, and direct JSON export for automated policy synthesis.

#### Zero CloudWatch Dimension Tax

Avoids the massive cost and 3-dimension limits of CloudWatch metric filters by using high-throughput subscription filters and cost-effective Athena partition projection queries.

## Technology Stack

AWS IAM AWS CloudTrail CloudWatch Logs Subscription Filters Amazon Kinesis Data Firehose Amazon Athena & AWS Glue PostgreSQL & SQLite Next.js 15 & TypeScript Terraform Infrastructure as Code AWS Organizations & Control Tower

[Explore RoleTrail on GitHub](https://github.com/jonathanbglass/roletrail) [Back to Open Source Tools](https://jonathanglass.cloud/opensource.html) [Back to Home](https://jonathanglass.cloud/index.html)
