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. Session Token Management (Preferred)

The RegScale CLI supports AWS session token management for improved security and MFA support. Session tokens are temporary credentials that automatically expire, reducing the risk of credential compromise.

Benefits of Session Tokens

• ✅ Temporary credentials - Auto-expire after 15 minutes to 12 hours
• ✅ MFA support - Require multi-factor authentication for sensitive operations
• ✅ Role assumption - Easily assume roles across AWS accounts
• ✅ Better security - Reduced risk if credentials are compromised
• ✅ Credential caching - Authenticate once, use across multiple commands

Authentication Priority Order

The CLI checks authentication methods in the following order:

1. Cached Session Tokens (--session-name) - Highest priority
2. AWS Profile (--profile) - Uses ~/.aws/credentials
3. Explicit Credentials (--aws-access-key-id, --aws-secret-access-key, --aws-session-token)
4. Environment Variables - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
5. Default AWS Credential Chain - EC2 instance profiles, etc.

Generating Session Tokens

Basic Session Token

Bash

regscale aws auth login --session-name my-session --profile default

Session Token with MFA

Bash

regscale aws auth login --session-name my-session --profile default \
    --mfa-serial arn:aws:iam::123456789012:mfa/username \
    --mfa-code 123456

Session Token with Role Assumption

Bash

regscale aws auth login --session-name cross-account --profile default \
    --role-arn arn:aws:iam::987654321098:role/CrossAccountRole \
    --role-session-name regscale-session \
    --mfa-serial arn:aws:iam::123456789012:mfa/username \
    --mfa-code 123456

Session Token with Explicit Credentials

Bash

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

Using Cached Sessions

Once a session is cached, use it with any AWS command:

Bash

# Sync assets
regscale aws sync_assets --session-name my-session --regscale-id 36

# Sync findings
regscale aws sync_findings --session-name my-session --regscale-id 36

# Collect inventory
regscale aws inventory collect --session-name my-session --output inventory.json

Managing Sessions

List All Sessions

Bash

regscale aws auth list

Output shows session status, expiration, and region:

Session: my-session
  Status:     ACTIVE
  Region:     us-east-1
  Expires:    2025-10-11T00:00:00+00:00

Clear a Specific Session

Bash

regscale aws auth logout --session-name my-session

Clear All Sessions

Bash

regscale aws auth logout-all

Session Token Options

Option	Required	Description
--session-name	Yes	Name for this session (used to cache credentials)
--profile	No	AWS profile from ~/.aws/credentials
--aws-access-key-id	No	Explicit AWS access key ID
--aws-secret-access-key	No	Explicit AWS secret access key
--mfa-serial	No	ARN of MFA device (e.g., arn:aws:iam::123456789012:mfa/username)
--mfa-code	No	6-digit MFA code from authenticator app
--role-arn	No	ARN of role to assume
--role-session-name	No	Name for the assumed role session
--duration	No	Duration in seconds (900-43200, default: 3600)
--region	No	AWS region (default: us-east-1)

Security Considerations

Storage Location:
Session tokens are cached in ~/.regscale/aws_sessions/<session-name>.json with restricted permissions (600).

Best Practices:

1. Always use MFA for production accounts (--mfa-serial and --mfa-code)
2. Use shorter durations for sensitive operations
3. Clear sessions when done (regscale aws auth logout)
4. Assume roles with minimal permissions needed
5. Rotate sessions regularly

What's Stored:
The cached session file contains temporary credentials (access key, secret key, session token) that automatically expire. Even if compromised, they have a limited lifetime.

2. AWS Profile

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

3. 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.

4. 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.