Policies

Audex supports multiple ways to define permissions: inline actions, named profiles, AI-powered intent parsing, and learning from observed API calls.

---

Action Syntax

AWS

AWS uses the service:Action format:

# Single action
tryaudex run --allow "s3:GetObject" -- aws s3 ls

# Multiple actions (comma-separated)
tryaudex run --allow "s3:GetObject,s3:ListBucket,s3:HeadObject" -- aws s3 ls

# Wildcards
tryaudex run --allow "s3:*" -- aws s3 ls                    # All S3 actions
tryaudex run --allow "lambda:Invoke*" -- aws lambda invoke  # All Invoke* actions
tryaudex run --allow "*:*" -- aws ec2 describe-instances    # All actions (dangerous!)

GCP

GCP uses dot-separated permissions like service.resource.verb:

# Single permission
tryaudex run --provider gcp --allow "storage.objects.get" -- gsutil ls

# Multiple permissions
tryaudex run --provider gcp --allow "storage.objects.get,storage.objects.list" -- gsutil ls

# Wildcards
tryaudex run --provider gcp --allow "storage.objects.*" -- gsutil ls
tryaudex run --provider gcp --allow "storage.*.*" -- gsutil ls

Azure

Azure uses Microsoft.Service/resource/action format:

# Single action
tryaudex run --provider azure \
  --allow "Microsoft.Storage/storageAccounts/read" \
  -- az storage account list

# Multiple actions
tryaudex run --provider azure \
  --allow "Microsoft.Storage/storageAccounts/read,Microsoft.Storage/storageAccounts/listKeys/action" \
  -- az storage account keys list

# Wildcards
tryaudex run --provider azure \
  --allow "Microsoft.Storage/storageAccounts/*" \
  -- az storage account list

---

Built-in Profiles

Use --profile instead of manually listing actions:

AWS Profiles

Profile	Actions	Use Case
s3-readonly	s3:GetObject,s3:ListBucket,s3:HeadObject	Read S3 objects
s3-readwrite	s3:GetObject,s3:PutObject,s3:DeleteObject,s3:ListBucket	Full S3 access
dynamodb-readonly	dynamodb:GetItem,dynamodb:Query,dynamodb:Scan,dynamodb:BatchGetItem	Read DynamoDB
dynamodb-readwrite	dynamodb:GetItem,dynamodb:PutItem,dynamodb:UpdateItem,dynamodb:DeleteItem,dynamodb:Query,dynamodb:Scan	Full DynamoDB
lambda-invoke	lambda:InvokeFunction,lambda:InvokeAsync	Invoke Lambda functions
lambda-deploy	lambda:UpdateFunctionCode,lambda:GetFunction,lambda:PublishVersion	Deploy Lambda
ec2-readonly	ec2:DescribeInstances,ec2:DescribeImages,ec2:DescribeSecurityGroups	Read EC2
secrets-readonly	secretsmanager:GetSecretValue	Read secrets
iam-readonly	iam:GetUser,iam:ListAccessKeys,iam:GetPolicy	Read IAM metadata

GCP Profiles

Profile	Permissions	Use Case
gcs-readonly	storage.objects.get,storage.objects.list	Read Cloud Storage
gcs-readwrite	storage.objects.get,storage.objects.list,storage.objects.create,storage.objects.delete	Full Cloud Storage
compute-readonly	compute.instances.list,compute.instances.get	Read Compute Engine
bigquery-readonly	bigquery.datasets.get,bigquery.tables.get,bigquery.tables.list	Read BigQuery

Azure Profiles

Profile	Actions	Use Case
azure-storage-readonly	Microsoft.Storage/storageAccounts/read	Read storage accounts
azure-storage-readwrite	Microsoft.Storage/storageAccounts/read,Microsoft.Storage/storageAccounts/write	Full storage access
azure-keyvault-readonly	Microsoft.KeyVault/vaults/read,Microsoft.KeyVault/vaults/secrets/read	Read Key Vault
azure-compute-readonly	Microsoft.Compute/virtualMachines/read	Read VMs

Usage

# Use a built-in profile
tryaudex run --profile s3-readonly -- aws s3 ls

# List all available profiles
tryaudex policies list

# Show details of a profile
tryaudex policies show s3-readonly

---

Universal Policy Syntax

Audex supports a cloud-agnostic syntax that translates to provider-specific actions:

Supported Universal Permissions

Universal	AWS	GCP	Azure
storage:read	s3:GetObject,s3:ListBucket	storage.objects.get,storage.buckets.list	Microsoft.Storage/storageAccounts/read
storage:write	s3:PutObject,s3:DeleteObject	storage.objects.create,storage.objects.delete	Microsoft.Storage/storageAccounts/write
database:read	dynamodb:GetItem,dynamodb:Query	bigquery.tables.get	Microsoft.SQL/servers/databases/read
database:write	dynamodb:PutItem,dynamodb:UpdateItem	bigquery.tables.update	Microsoft.SQL/servers/databases/write
compute:read	ec2:DescribeInstances	compute.instances.list	Microsoft.Compute/virtualMachines/read
secrets:read	secretsmanager:GetSecretValue	secretmanager.secrets.get	Microsoft.KeyVault/vaults/secrets/read
logs:read	logs:GetLogEvents	logging.logEntries.list	Microsoft.Insights/logs/read
monitoring:read	cloudwatch:GetMetricStatistics	monitoring.timeSeries.list	Microsoft.Insights/metrics/read

Example

# AWS: storage:read expands to s3:GetObject,s3:ListBucket
tryaudex run --provider aws --allow "storage:read" -- aws s3 ls

# GCP: storage:read expands to storage.objects.get,storage.buckets.list
tryaudex run --provider gcp --allow "storage:read" -- gsutil ls

# Azure: storage:read expands to Microsoft.Storage/storageAccounts/read
tryaudex run --provider azure --allow "storage:read" -- az storage account list

---

Learning from CloudTrail / Audit Logs

Automatically discover minimum permissions by observing actual API calls:

# Run a script and observe what permissions it actually uses
tryaudex learn -- ./my-script.sh

# Output:
# Observed actions (from CloudTrail):
#   s3:GetObject (2 calls)
#   s3:ListBucket (1 call)
# Recommended policy: s3:GetObject,s3:ListBucket

How It Works

1. Audex creates a session with broad permissions (you specify a base role)
2. Your script runs
3. Audex queries CloudTrail to find all API calls made during the session
4. Maps CloudTrail event names back to IAM action names
5. Outputs the minimum set of IAM actions needed

Limitations

• CloudTrail has a ~5 minute delay, so this works best for longer-running operations
• Only works for AWS (GCP/Azure support coming)
• Requires CloudTrail to be enabled on your account

Example

tryaudex learn --ttl 10m -- python train_model.py
# Waits for script to complete, then queries CloudTrail
# Output shows: dynamodb:Query, s3:GetObject, dynamodb:UpdateItem

---

Natural Language to IAM (Intent)

Convert a description to IAM permissions using Claude:

# Ask Claude what permissions you need
tryaudex intent "Read from S3 bucket and invoke a Lambda function"

# Output:
# {
#   "allow": "s3:GetObject,lambda:InvokeFunction",
#   "resource": null,
#   "description": "Read objects from S3 and invoke Lambda functions"
# }

# Can include resource restrictions
tryaudex intent "Read only from my-bucket in S3"
# Output:
# {
#   "allow": "s3:GetObject",
#   "resource": "arn:aws:s3:::my-bucket/*",
#   "description": "Read objects from a specific S3 bucket"
# }

Requirements

• Set ANTHROPIC_API_KEY environment variable with a valid Claude API key
• Requires internet access to Anthropic API

How It Works

Audex sends your natural language description to Claude with a system prompt asking it to extract:

• The minimum set of IAM actions needed
• Any resource ARN restrictions
• A human-readable description

The response is formatted as JSON for easy parsing and use with --allow and --resource.

---

Custom Profiles

Define your own reusable policy profiles in ~/.config/audex/profiles.toml:

[profiles.my-data-pipeline]
description = "Read from S3, write to DynamoDB"
actions = "s3:GetObject,dynamodb:PutItem,dynamodb:UpdateItem"
resources = ["arn:aws:s3:::input-data/*", "arn:aws:dynamodb:*:*:table/pipeline-results"]

[profiles.ml-inference]
description = "Invoke SageMaker and read model artifacts"
actions = "sagemaker:InvokeEndpoint,s3:GetObject"
resources = ["arn:aws:s3:::ml-models/*"]

Then use them:

tryaudex run --profile my-data-pipeline -- python pipeline.py
tryaudex run --profile ml-inference -- python inference.py

---

Deny Lists

Prevent certain actions even if the underlying role allows them:

# Global deny list in ~/.config/audex/deny-list.toml
[deny]
actions = [
  "iam:*",
  "ec2:TerminateInstances",
  "rds:DeleteDBInstance",
  "s3:DeleteBucket"
]

When you request --allow "s3:*", actions in the deny list are automatically filtered out. Useful for team deployments where you want to prevent accidental destructive operations.

---

Drift Detection

Detect when the actual IAM role permissions have drifted from expected:

# Compare your base role against a known-good policy
tryaudex drift --role-arn arn:aws:iam::123456789012:role/MyRole \
  --expected-policy s3-readonly

# Output shows:
# Role has additional permissions not in profile:
#   ec2:DescribeInstances
#   dynamodb:ListTables
# Consider updating the role or profile definition

Useful for detecting accidental permission creep or infrastructure drift.

---

Resource Restrictions

Limit credentials to specific resources (AWS only, currently):

# Read-only from a specific bucket
tryaudex run --allow "s3:GetObject,s3:ListBucket" \
  --resource "arn:aws:s3:::my-bucket/*,arn:aws:s3:::my-bucket" \
  -- aws s3 ls s3://my-bucket/

# Write only to specific DynamoDB table
tryaudex run --allow "dynamodb:PutItem" \
  --resource "arn:aws:dynamodb:us-east-1:123456789012:table/my-table" \
  -- aws dynamodb put-item --table-name my-table --item '{"id":{"S":"123"}}'

---

Best Practices

1. Start with profiles: Use built-in profiles when possible. They’re tested and documented.
2. Use universal syntax for multi-cloud: If you support multiple clouds, use universal permissions.
3. Learn first, restrict later: Use tryaudex learn to find actual permissions, then restrict further.
4. Scope resources: Use --resource to limit to specific buckets, tables, etc. when possible.
5. Use short, specific actions: Prefer s3:GetObject over s3:* or *:*.
6. Review deny lists: Ensure critical destructive actions are in your deny list.
7. Rotate profiles: Periodically check for permission drift and update profiles.