How It Works

Audex is a Rust CLI that creates scoped, short-lived credentials using cloud provider APIs (AWS STS, GCP IAM Credentials, Azure, Vault) with inline policies or credential restrictions.

Credential Flow

┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│  Your Agent  │────>│    Audex      │────>│   AWS STS   │
│  (claude,    │     │  - Policy     │     │  AssumeRole │
│   cursor,    │     │  - TTL        │     │  + Inline   │
│   etc.)      │     │  - Audit Log  │     │    Policy   │
│              │<────│              │<────│             │
└──────────────┘     └───────────────┘     └─────────────┘
     ^                                          │
     └──── AWS_ACCESS_KEY_ID <──────────────────┘
           AWS_SECRET_ACCESS_KEY
           AWS_SESSION_TOKEN

You run tryaudex run --allow "s3:GetObject" -- aws s3 ls
Audex parses the allowed actions into an IAM policy document
Audex calls sts:AssumeRole with your configured role ARN and an inline session policy
AWS returns temporary credentials (access key, secret key, session token) valid for the specified TTL
Audex injects these as environment variables and spawns your command
When the command exits, credentials are no longer usable (TTL-enforced by AWS)
Session metadata and events are written to the audit log

Architecture

audex/
├── crates/
│   ├── audex-cli/           # CLI binary (16 commands)
│   │   ├── commands/        # run, chain, sessions, audit, intent, learn,
│   │   │                    # compliance, dashboard, estimate, health,
│   │   │                    # metrics, replay, watch, clean, server, mcp
│   │   ├── tui/             # ratatui interactive dashboard
│   │   └── mcp.rs           # MCP server for Claude Code
│   └── audex-core/          # Core library (39+ modules)
│       ├── credentials.rs   # AWS STS credential issuance
│       ├── gcp.rs           # GCP service account impersonation
│       ├── azure.rs         # Azure CLI / identity token issuance
│       ├── vault.rs         # HashiCorp Vault (Token/AppRole/K8s auth)
│       ├── policy.rs        # IAM action parsing, universal syntax
│       ├── roles.rs         # Role mapping for teams
│       ├── intent.rs        # Natural language → IAM (Claude API)
│       ├── learn.rs         # CloudTrail replay → minimum policy
│       ├── server.rs        # REST API server for teams
│       ├── sso.rs           # SAML/OIDC authentication
│       ├── approval.rs      # Multi-party approval workflows
│       ├── session.rs       # Session lifecycle + JSON persistence
│       ├── audit.rs         # Append-only JSONL audit log
│       ├── budget.rs        # Cost Explorer monitoring (advisory)
│       ├── keystore.rs      # Encrypted credential cache
│       ├── broker.rs        # Credential broker REST client
│       ├── ha.rs            # Redis/etcd leader election & replication
│       ├── metrics.rs       # Prometheus metrics export
│       ├── health.rs        # Connectivity checks
│       ├── compliance.rs    # SOC2/ISO 27001 report generation
│       ├── drift.rs         # Policy drift detection
│       ├── rotation.rs      # Automatic key rotation
│       ├── leakdetect.rs    # Credential leak scanning
│       └── and others...
└── web/                      # Astro landing page + docs

Session Lifecycle

Each tryaudex run command creates a session that moves through these states:

State	Meaning
Active	Credentials issued, subprocess running
Completed	Subprocess exited with code 0
Failed	Subprocess exited with non-zero code
Expired	TTL elapsed
Revoked	Manually revoked
BudgetExceeded	Spend exceeded the budget limit

Sessions are persisted as JSON files at ~/.local/share/audex/sessions/.

Inline Session Policies

When you pass --allow "s3:GetObject,s3:ListBucket", Audex generates this IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": "*"
    }
  ]
}

This is passed as the Policy parameter to sts:AssumeRole. AWS computes the effective permissions as the intersection of the role’s attached policies and this inline policy. Even if the role has s3:*, the session can only use s3:GetObject and s3:ListBucket.

Audit Trail

Every session produces audit events in append-only JSONL format at ~/.local/share/audex/audit/audit.jsonl:

Event	When
`SessionCreated`	Session starts, records role ARN, TTL, actions, command
`CredentialsIssued`	STS returns credentials, records access key ID and expiry
`SessionEnded`	Subprocess exits, records status, duration, exit code
`BudgetWarning`	Spend exceeds 80% of budget limit
`BudgetExceeded`	Spend exceeds budget limit

# View all audit entries
tryaudex audit recent

# View entries for a specific session
tryaudex audit show a1b2c3d4