Clanker Docs

Appearance

AWS ​

AWS is the primary cloud provider in Clanker. It offers the deepest integration, including read-only infrastructure queries, intelligent agent investigation, IAM security analysis, and the maker pipeline for infrastructure provisioning.

Authentication ​

Clanker authenticates with AWS through local CLI profiles. It does not store raw access keys in its configuration.

Setting up a profile ​

bash
# Standard credentials
aws configure --profile my-dev-profile

# SSO-based authentication
aws configure sso --profile my-dev-profile

# Verify
aws sts get-caller-identity --profile my-dev-profile

Configuring Clanker ​

Reference the profile in ~/.clanker.yaml:

yaml
infra:
  default_provider: aws
  default_environment: dev
  aws:
    environments:
      dev:
        profile: my-dev-profile
        region: us-east-1
      prod:
        profile: my-prod-profile
        region: us-west-2

Profile resolution order ​

When Clanker needs an AWS profile, it resolves in this order:

  1. --profile CLI flag
  2. Profile from the environment configured in infra.default_environment
  3. aws.default_profile (legacy config key)
  4. "default" (the AWS CLI default profile)

Region resolution order ​

  1. AWS_REGION environment variable
  2. AWS_DEFAULT_REGION environment variable
  3. Region configured for the profile via aws configure get region --profile <name>
  4. Region from the matched environment in infra.aws.environments
  5. us-east-1 (fallback)

Querying AWS ​

Explicit flag ​

bash
clanker ask --aws "What EC2 instances are running?"

Automatic routing ​

If no provider flag is specified, Clanker infers the cloud provider from your question using keyword analysis. If the question mentions AWS services (EC2, Lambda, S3, RDS, etc.), it routes to AWS automatically:

bash
clanker ask "What Lambda functions have high error rates?"

Three-Stage Query Pipeline ​

AWS queries use a three-stage pipeline:

  1. Stage 1 (Analysis): The configured AI provider analyzes your question and determines which AWS CLI operations are needed (e.g., describe-instances, list-functions).
  2. Stage 2 (Execution): Clanker executes the selected AWS CLI operations in parallel using your configured profile and region.
  3. Stage 3 (Response): The results are combined with your original question and sent to the AI for a comprehensive answer.

For queries involving logs, errors, or service investigation, Clanker may use the intelligent agent investigation pipeline instead, which performs multi-step analysis with dependency-aware parallel execution.

Supported Services ​

Clanker can query any AWS service accessible through the AWS CLI. The most commonly used services include:

  • Compute: EC2, Lambda, ECS, Fargate, Elastic Beanstalk
  • Storage: S3, EBS, EFS
  • Database: RDS, DynamoDB, ElastiCache, Redshift
  • Networking: VPC, Route 53, CloudFront, ELB/ALB/NLB, API Gateway
  • Security: IAM, Security Groups, KMS, Secrets Manager
  • Monitoring: CloudWatch (logs, metrics, alarms)
  • Messaging: SQS, SNS, Kinesis
  • Containers: ECR, ECS, EKS
  • Serverless: Lambda, Step Functions
  • CI/CD: CodePipeline, CodeBuild
  • Analytics: Athena, Glue, Redshift
  • ML: SageMaker, Bedrock

IAM Security Analysis ​

Clanker includes a dedicated IAM agent for security auditing:

bash
# Comprehensive IAM analysis
clanker ask --iam "Analyze IAM roles for overpermissive policies"

# Scope to a specific role
clanker ask --iam --role-arn arn:aws:iam::123456789012:role/MyRole "What permissions does this role have?"

# Scope to a specific policy
clanker ask --iam --policy-arn arn:aws:iam::123456789012:policy/MyPolicy "Is this policy least-privilege?"

The IAM agent checks for:

  • Overpermissive roles and policies
  • Wildcard permissions
  • Cross-account trust relationships
  • Unused roles and access keys
  • MFA status for IAM users
  • Admin-level access

Maker Pipeline (Infrastructure Provisioning) ​

The maker feature generates and executes AWS CLI plans for infrastructure changes:

Generating a plan ​

bash
clanker ask --maker "Create an S3 bucket called my-data-bucket with versioning enabled"

This outputs a JSON plan to stdout. The plan includes the AWS CLI commands that will be executed.

Applying a plan ​

bash
# Pipe the plan directly
clanker ask --maker "Create an S3 bucket" | clanker ask --apply

# Or save and review first
clanker ask --maker "Create an S3 bucket" > plan.json
cat plan.json  # Review the plan
clanker ask --apply --plan-file plan.json

Destructive operations ​

By default, maker plans are read-only or create-only. To allow destructive operations (deletion, modification), use --destroyer:

bash
clanker ask --maker --destroyer "Delete the unused EC2 instances in us-east-1"

Plan enrichment ​

AWS maker plans are automatically enriched before output. Clanker resolves VPC IDs, subnet IDs, and security group IDs by querying your AWS account, so the plan uses real resource references rather than placeholders.

Error remediation during execution ​

When applying a plan, the execution engine includes sophisticated error handling:

  • Classifies AWS errors by category (not_found, already_exists, conflict, etc.)
  • Learns placeholder bindings from command outputs (VPC_ID, SUBNET_ID, etc.)
  • Rewrites and retries commands for recoverable errors
  • Escalates to AI-assisted remediation when built-in fixes are insufficient
  • Waits for asynchronous operations like CloudFormation stack completion

Discovery and Compliance Mode ​

Infrastructure discovery ​

bash
clanker ask --discovery "What infrastructure is deployed?"

Discovery mode enables comprehensive scanning across all AWS services and Terraform state.

Compliance reporting ​

bash
clanker ask --compliance

Compliance mode generates a System Security Plan (SSP) "Services, Ports, and Protocols" report covering all active AWS services, their ports, protocols, external access, and security controls.

Backend Credentials ​

For team environments, Clanker can retrieve AWS credentials from the Clanker backend:

bash
# Store credentials (one-time setup)
clanker credentials store aws --profile my-dev-profile

# Query using backend credentials
clanker ask --api-key ck_live_abc123 "What EC2 instances are running?"

This allows team members to query infrastructure without needing direct access to AWS CLI profiles on their local machines.