Authentication

AWS Authentication

Overview

The RegScale AWS CLI supports multiple authentication methods to connect to your AWS environment. Choose the method that best fits your security requirements and operational workflow.

Authentication Methods

1. AWS Profile (Recommended)

Use AWS CLI profiles configured in ~/.aws/credentials or ~/.aws/config:

Bash

regscale aws sync_assets \
  --regscale_id 123 \
  --profile my-aws-profile

Benefits:

• Secure credential storage
• Easy switching between environments
• Supports AWS SSO
• No credentials in command history

Setup:

Bash

# Configure AWS profile
aws configure --profile my-aws-profile

# Use with RegScale
regscale aws sync_compliance \
  --regscale_id 123 \
  --profile production

2. Explicit Credentials

Pass AWS credentials directly as command-line arguments:

Bash

regscale aws sync_compliance \
  --regscale_id 123 \
  --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
  --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Use Cases:

• CI/CD pipelines with environment variables
• Temporary credentials
• Testing and development

⚠️ Security Note: Never hard-code credentials. Use environment variables or secrets management.

3. Cached Session with RegScale AWS Auth

Cache AWS credentials using the regscale aws auth command for reuse across multiple operations:

Login and Cache Credentials

Bash

# Cache standard credentials
regscale aws auth login \
  --session-name my-session \
  --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
  --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Cache temporary credentials with session token
regscale aws auth login \
  --session-name federated-session \
  --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
  --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  --aws-session-token FwoGZXIvYXdzEA4aDHz...EXAMPLETOKEN

Use Cached Credentials

Bash

# Use cached session in commands
regscale aws sync_compliance \
  --regscale_id 123 \
  --session-name my-session

# Works across all AWS commands
regscale aws sync_findings \
  --regscale_id 123 \
  --session-name my-session

View Stored Sessions

Bash

# List all cached sessions
regscale aws auth list

# Show specific session details
regscale aws auth show --session-name my-session

Remove Cached Sessions

Bash

# Remove specific session
regscale aws auth logout --session-name my-session

# Remove all sessions
regscale aws auth logout --all

Benefits:

• Credential reuse across multiple commands
• Secure storage in RegScale configuration
• Supports temporary session tokens
• Convenient for automation scripts

Use Cases:

• Long-running automation workflows
• Temporary AWS credentials (federated access)
• Multi-step compliance processes
• Shared credential management

4. Default AWS Credential Chain

Use the standard AWS credential resolution order (environment variables, AWS config files, IAM roles):

Bash

# Set AWS profile via environment
export AWS_PROFILE=my-profile

# RegScale automatically uses default credentials
regscale aws sync_assets --regscale_id 123

# Or set credentials via environment variables
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=FwoGZXIvYXdzEA4aDHz...EXAMPLETOKEN

regscale aws sync_compliance --regscale_id 123

AWS Credential Resolution Order:

1. Command-line arguments (--aws-access-key-id, etc.)
2. Cached RegScale session (--session-name)
3. Environment variables (AWS_ACCESS_KEY_ID, etc.)
4. AWS profile (--profile or AWS_PROFILE environment variable)
5. AWS credentials file (~/.aws/credentials)
6. AWS config file (~/.aws/config)
7. IAM role (for EC2 instances, ECS tasks, Lambda functions)

Use Cases:

• EC2 instances with IAM roles
• CI/CD environments with pre-configured credentials
• Docker containers with mounted AWS config
• Lambda functions with execution roles

RegScale AWS Auth Commands

regscale aws auth login

Cache AWS credentials for reuse:

Options:

• --session-name (required): Name for the cached session
• --aws-access-key-id (required): AWS access key ID
• --aws-secret-access-key (required): AWS secret access key
• --aws-session-token (optional): AWS session token for temporary credentials
• --region (optional): Default AWS region for the session

Examples:

Bash

# Standard credentials
regscale aws auth login \
  --session-name prod-session \
  --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
  --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  --region us-east-1

# Temporary credentials (from AWS STS assume-role)
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/MyRole --role-session-name my-session

regscale aws auth login \
  --session-name temp-role-session \
  --aws-access-key-id <AccessKeyId-from-STS> \
  --aws-secret-access-key <SecretAccessKey-from-STS> \
  --aws-session-token <SessionToken-from-STS>

regscale aws auth list

List all cached credential sessions:

Bash

# List all sessions
regscale aws auth list

Output:

Cached AWS Sessions:
- prod-session (region: us-east-1)
- staging-session (region: us-west-2)
- temp-role-session (region: us-east-1)

regscale aws auth show

Display details for a specific session:

Bash

# Show session information
regscale aws auth show --session-name prod-session

Output:

Session: prod-session
Region: us-east-1
Access Key ID: AKIA...MPLE (masked)
Created: 2025-10-30 10:15:00

regscale aws auth logout

Remove cached credentials:

Bash

# Remove specific session
regscale aws auth logout --session-name prod-session

# Remove all sessions
regscale aws auth logout --all

Authentication Best Practices

1. Use IAM Roles When Possible

For AWS resources (EC2, ECS, Lambda), use IAM roles instead of access keys:

Bash

# No credentials needed on EC2 with IAM role
regscale aws sync_assets --regscale_id 123

2. Rotate Credentials Regularly

• Set up automatic key rotation for IAM users
• Update cached sessions after credential rotation
• Remove unused sessions with regscale aws auth logout

3. Use Temporary Credentials

For federated access or cross-account access:

Bash

# Assume role and get temporary credentials
aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/ComplianceRole \
  --role-session-name compliance-scan

# Cache temporary credentials
regscale aws auth login \
  --session-name compliance-temp \
  --aws-access-key-id <Temp-AccessKeyId> \
  --aws-secret-access-key <Temp-SecretAccessKey> \
  --aws-session-token <SessionToken>

4. Separate Environments

Use different profiles or sessions for each environment:

Bash

# Production
regscale aws sync_compliance \
  --regscale_id 123 \
  --profile production

# Staging
regscale aws sync_compliance \
  --regscale_id 456 \
  --profile staging

# Or with cached sessions
regscale aws sync_compliance --regscale_id 123 --session-name prod-session
regscale aws sync_compliance --regscale_id 456 --session-name staging-session

5. Secure Credential Storage

• Never commit credentials to source control
• Use AWS Secrets Manager or parameter store for automation
• Encrypt credentials at rest
• Use environment variables in CI/CD pipelines

6. Least Privilege Access

Grant only the permissions needed for RegScale operations. See Required IAM Permissions.

Required IAM Permissions

Minimum Permissions for Asset Sync

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "rds:Describe*",
        "lambda:List*",
        "iam:List*",
        "iam:Get*"
      ],
      "Resource": "*"
    }
  ]
}

Audit Manager Permissions

JSON

{
  "Effect": "Allow",
  "Action": [
    "auditmanager:GetAssessment",
    "auditmanager:ListAssessments",
    "auditmanager:GetEvidence",
    "auditmanager:ListAssessmentFrameworks",
    "auditmanager:GetEvidenceFolder",
    "auditmanager:GetEvidenceFoldersByAssessmentControl"
  ],
  "Resource": "*"
}

Security Hub Permissions

JSON

{
  "Effect": "Allow",
  "Action": [
    "securityhub:GetFindings",
    "securityhub:DescribeHub",
    "securityhub:GetEnabledStandards"
  ],
  "Resource": "*"
}

Full Compliance Monitoring Permissions

For comprehensive compliance monitoring, use the AWS ReadOnlyAccess managed policy with additions:

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "auditmanager:*",
        "securityhub:*",
        "config:*",
        "guardduty:*",
        "inspector2:*"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting Authentication

Error: "Unable to locate credentials"

Cause: No credentials found in any source.

Solution:

1. Verify AWS credentials are configured: aws configure list
2. Check environment variables: echo $AWS_ACCESS_KEY_ID
3. Verify profile exists: cat ~/.aws/credentials
4. Try explicit credentials: --aws-access-key-id and --aws-secret-access-key

Error: "The security token included in the request is expired"

Cause: Temporary credentials or session token has expired.

Solution:

1. Generate new temporary credentials
2. Update cached session: regscale aws auth logout --session-name <session-name> then login again
3. For IAM roles, the token refresh is automatic

Error: "Access Denied" or "UnauthorizedOperation"

Cause: IAM permissions insufficient for the requested operation.

Solution:

1. Review required permissions above
2. Check IAM policy attached to your user/role
3. Verify service control policies (SCPs) in AWS Organizations
4. Test with AWS CLI: aws <service> <operation> to isolate permission issues

Error: "Session name not found"

Cause: Attempting to use a session that doesn't exist.

Solution:

1. List available sessions: regscale aws auth list
2. Login with the correct session name
3. Verify typos in --session-name argument

Examples

Example 1: Production with AWS Profile

Bash

# Configure AWS profile
aws configure --profile production

# Use profile with RegScale
regscale aws sync_compliance \
  --regscale_id 123 \
  --profile production \
  --tags Environment=production

Example 2: CI/CD Pipeline with Environment Variables

Bash

# Set in CI/CD environment
export AWS_ACCESS_KEY_ID=$PROD_AWS_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=$PROD_AWS_SECRET_ACCESS_KEY
export AWS_REGION=us-east-1

# Run without explicit auth parameters
regscale aws sync_findings --regscale_id 123

Example 3: Cross-Account Compliance with Assumed Role

Bash

# Step 1: Assume role in target account
aws sts assume-role \
  --role-arn arn:aws:iam::999999999999:role/ComplianceRole \
  --role-session-name regscale-compliance

# Step 2: Cache temporary credentials
regscale aws auth login \
  --session-name cross-account-compliance \
  --aws-access-key-id <AccessKeyId> \
  --aws-secret-access-key <SecretAccessKey> \
  --aws-session-token <SessionToken>

# Step 3: Run compliance sync
regscale aws sync_compliance \
  --regscale_id 123 \
  --session-name cross-account-compliance

Example 4: Multi-Environment Automation Script

Bash

#!/bin/bash

# Cache credentials for each environment
regscale aws auth login \
  --session-name prod \
  --aws-access-key-id $PROD_ACCESS_KEY \
  --aws-secret-access-key $PROD_SECRET_KEY

regscale aws auth login \
  --session-name staging \
  --aws-access-key-id $STAGING_ACCESS_KEY \
  --aws-secret-access-key $STAGING_SECRET_KEY

# Sync each environment
regscale aws sync_assets --regscale_id 123 --session-name prod
regscale aws sync_assets --regscale_id 456 --session-name staging

# Cleanup
regscale aws auth logout --all

Next Steps

• AWS Integration Overview - Learn about available workflows
• AWS Audit Manager - Set up compliance assessments
• AWS Security Hub - Configure security findings sync

Support

For authentication issues, contact RegScale support at [email protected] or consult the RegScale documentation.