Security Model

Audex reduces the blast radius when AI agents interact with cloud infrastructure (AWS, GCP, Azure, Vault). Here is what it guarantees, what it does not, and what you are trusting.

---

What Audex Protects Against

• Overprivileged agents — An agent that only needs s3:GetObject cannot call s3:DeleteBucket, even if the underlying IAM role allows it
• Long-lived credentials — Credentials expire after the TTL (max 12 hours, enforced by AWS STS), even if Audex crashes or is killed
• Unaudited access — Every session is logged with timestamp, actions, command, duration, and exit code
• Accidental scope creep — Each command gets its own session with its own policy, no accumulated permissions

---

What Audex Does NOT Protect Against

• Compromised machine — If an attacker has local access, they can read STS tokens from the subprocess environment or the audit log
• Malicious base role — If the IAM role itself has overly broad permissions, Audex only narrows within that scope
• Real-time budget enforcement — The --budget flag uses AWS Cost Explorer which has a ~24 hour delay. It provides advisory alerts, not real-time spend prevention
• Data exfiltration within scope — If you allow s3:GetObject, the agent can read anything the role has access to in S3. Audex scopes actions, not resources (resource scoping is on the roadmap)

---

Trust Boundary

When you use Audex, you are trusting:

Component	What you trust
Audex binary	To correctly generate inline policies and pass them to STS
AWS STS	To enforce the inline session policy (this is an AWS guarantee)
Your IAM role	That its base permissions are the maximum you’re comfortable with
Your machine	That no malicious process is reading subprocess environment variables

Audex does not store secrets on disk. Session metadata (ID, status, role ARN, allowed actions) is stored as JSON. Credentials exist only in memory and in the subprocess environment.

---

Credential Lifecycle

1. tryaudex run --allow "s3:GetObject" -- aws s3 ls
2. Audex calls sts:AssumeRole with inline policy
3. AWS returns temporary credentials (access key + secret + token)
4. Credentials injected as env vars into subprocess
5. Subprocess runs
6. Subprocess exits
7. Credentials are NOT revoked (no API for that)
   but they expire when TTL elapses (enforced by AWS)
8. Session status updated, audit event written

Credentials cannot be explicitly revoked before TTL expiry. This is an AWS STS limitation. The mitigation is to use short TTLs (the default is 15 minutes).

---

TTL Clamping

AWS STS enforces a maximum session duration of 12 hours (43200 seconds). If you request a TTL longer than this, Audex silently clamps it. The actual expiry is set by AWS, not by Audex.

---

Inline Session Policy

The inline policy uses the intersection model. The effective permissions are:

effective = role_policy AND inline_session_policy

The inline policy can only narrow the role’s permissions, never widen them. If the role does not grant lambda:UpdateFunctionCode, the inline policy cannot add it.

---

Audit Log Integrity

The audit log is an append-only JSONL file at ~/.local/share/audex/audit/audit.jsonl. It is a local file, not tamper-proof. It is sufficient for personal audit trails and debugging.

For compliance use cases (SOC2, ISO 27001), forward the audit log to an immutable store (S3 with Object Lock, CloudWatch Logs, or a SIEM).

---

Recommendations

1. Use short TTLs. The default 15 minutes is the AWS STS minimum for AssumeRole. For faster rotation, rely on --profile scoping rather than sub-15m TTLs (STS will reject any DurationSeconds < 900).
2. Scope the base role narrowly. Audex can only narrow, not widen. A role with *:* and an inline policy for s3:GetObject still works, but a narrower base role is defense in depth.
3. Review audit logs regularly. Run tryaudex audit recent to see what your agents have been doing.
4. Don’t rely on budget caps for cost control. The 24-hour delay makes them advisory only. Use AWS Budgets with CloudWatch alarms for real-time spend alerts.