# User Guide

This comprehensive guide covers how to use the AWS CIS Controls Compliance Assessment Framework effectively - a production-ready, enterprise-grade solution with complete CIS Controls coverage.

## Production Framework Overview

**✅ Complete Implementation**
- 138 AWS Config rules implemented (133 CIS Controls + 5 bonus security rules)
- 100% coverage across all Implementation Groups (IG1, IG2, IG3)
- Production-tested architecture with enterprise-grade error handling
- Ready for immediate deployment in production environments
- **NEW:** AWS Backup service controls for infrastructure assessment

## Table of Contents

1. [Quick Start](#quick-start)
2. [Basic Usage](#basic-usage)
3. [Assessment Options](#assessment-options)
4. [Output Formats](#output-formats)
5. [Advanced Features](#advanced-features)
6. [Best Practices](#best-practices)
7. [Common Workflows](#common-workflows)

## Quick Start

### Your First Assessment

```bash
# Run a basic assessment with default settings
aws-cis-assess assess

# This will:
# - Assess all Implementation Groups (IG1, IG2, IG3)
# - Use all enabled AWS regions
# - Generate a JSON report
# - Use default AWS credentials
```

### Quick IG1 Assessment

```bash
# Focus on essential controls only
aws-cis-assess assess --implementation-groups IG1 --regions us-east-1
```

### Generate HTML Report

```bash
# Create an interactive web report
aws-cis-assess assess --output-format html --output-file compliance-report.html
```

## Basic Usage

### Command Structure

```bash
aws-cis-assess [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]
```

### Global Options

- `--verbose, -v`: Enable verbose output
- `--debug`: Enable debug logging
- `--version`: Show version information
- `--help`: Show help information

### Main Commands

#### assess
Run CIS Controls compliance assessment

```bash
aws-cis-assess assess [OPTIONS]
```

#### list-controls
List available CIS Controls and their Config rules

```bash
aws-cis-assess list-controls [OPTIONS]
```

#### list-regions
List available AWS regions

```bash
aws-cis-assess list-regions [OPTIONS]
```

#### show-stats
Show assessment statistics and scope

```bash
aws-cis-assess show-stats [OPTIONS]
```

#### validate-credentials
Test AWS credentials and permissions

```bash
aws-cis-assess validate-credentials [OPTIONS]
```

#### validate-config
Validate CIS Controls configuration files

```bash
aws-cis-assess validate-config [OPTIONS]
```

## Assessment Options

### Implementation Groups

Choose which CIS Controls Implementation Groups to assess:

```bash
# Assess only IG1 (Essential Cyber Hygiene)
aws-cis-assess assess --implementation-groups IG1

# Assess IG1 and IG2
aws-cis-assess assess --implementation-groups IG1,IG2

# Assess all groups (default)
aws-cis-assess assess --implementation-groups IG1,IG2,IG3
```

### Specific Controls

Target specific CIS Controls:

```bash
# Assess specific controls
aws-cis-assess assess --controls 1.1,3.3,4.1

# Exclude specific controls
aws-cis-assess assess --exclude-controls 7.1,12.8
```

### Regional Scope

Control which AWS regions to assess:

```bash
# Specific regions
aws-cis-assess assess --regions us-east-1,us-west-2,eu-west-1

# Exclude regions
aws-cis-assess assess --exclude-regions us-gov-east-1,us-gov-west-1

# Single region
aws-cis-assess assess --regions us-east-1
```

### AWS Credentials

Specify AWS credentials and profiles:

```bash
# Use specific AWS profile
aws-cis-assess assess --aws-profile production

# Use short flag for profile
aws-cis-assess assess -p production

# Use access keys directly
aws-cis-assess assess --aws-access-key-id AKIA... --aws-secret-access-key ...

# Use temporary credentials
aws-cis-assess assess --aws-access-key-id AKIA... --aws-secret-access-key ... --aws-session-token ...
```

## Output Formats

### JSON Format (Default)

Machine-readable format for automation:

```bash
aws-cis-assess assess --output-format json --output-file results.json
```

JSON structure:
```json
{
  "assessment_metadata": {
    "account_id": "123456789012",
    "timestamp": "2024-01-15T10:30:00Z",
    "regions_assessed": ["us-east-1", "us-west-2"],
    "assessment_duration": "PT15M30S"
  },
  "compliance_summary": {
    "overall_compliance_percentage": 78.5,
    "ig1_compliance_percentage": 85.2,
    "ig2_compliance_percentage": 72.1,
    "ig3_compliance_percentage": 65.8
  },
  "detailed_results": {
    "IG1": {
      "controls": {
        "1.1": {
          "compliance_percentage": 90.0,
          "findings": [...]
        }
      }
    }
  }
}
```

### HTML Format

Interactive web-based report with enhanced readability features:

```bash
aws-cis-assess assess --output-format html --output-file report.html
```

Features:
- Executive dashboard with charts
- Control display names with AWS Config rule names
- Unique controls per Implementation Group (eliminates duplication)
- IG membership badges for easy identification
- Consolidated detailed findings (each resource listed once)
- Drill-down capabilities
- Responsive design
- Remediation guidance
- Export capabilities

> **Note:** See [HTML Report Improvements](html-report-improvements.md) for detailed documentation on the enhanced features, customization options, and examples.

### CSV Format

Spreadsheet-compatible format:

```bash
aws-cis-assess assess --output-format csv --output-file results.csv
```

Includes:
- Summary CSV with overall scores
- Detailed findings CSV
- Remediation guidance CSV

### Multiple Formats

Generate multiple formats simultaneously:

```bash
aws-cis-assess assess --output-format json,html,csv --output-dir ./reports/
```

## Advanced Features

### Performance Tuning

Control assessment performance:

```bash
# Limit parallel workers
aws-cis-assess assess --max-workers 2

# Set timeout
aws-cis-assess assess --timeout 1800

# Quiet mode for automation
aws-cis-assess assess --quiet
```

### Error Handling

Configure error handling behavior:

```bash
# Enable error recovery
aws-cis-assess assess --enable-error-recovery

# Disable audit trail
aws-cis-assess assess --disable-audit-trail
```

### Logging

Control logging output:

```bash
# Set log level
aws-cis-assess assess --log-level DEBUG

# Log to file
aws-cis-assess assess --log-file assessment.log

# Verbose console output
aws-cis-assess assess --verbose
```

### Dry Run

Validate configuration without running assessment:

```bash
aws-cis-assess assess --dry-run
```

## Best Practices

### 1. Start Small

Begin with IG1 controls in a single region:

```bash
aws-cis-assess assess --implementation-groups IG1 --regions us-east-1
```

### 2. Use Dry Run

Always validate before running full assessments:

```bash
aws-cis-assess assess --dry-run
```

### 3. Preview Scope

Check what will be assessed:

```bash
aws-cis-assess show-stats --implementation-groups IG1,IG2
```

### 4. Focus on Critical Controls

Start with the most important controls:

```bash
aws-cis-assess assess --controls 1.1,3.3,5.2,6.1
```

### 5. Generate Multiple Formats

Create both viewing and automation formats:

```bash
aws-cis-assess assess --output-format html,json --output-dir ./reports/
```

### 6. Use Appropriate Regions

Focus on your primary regions:

```bash
aws-cis-assess assess --regions us-east-1,us-west-2,eu-west-1
```

### 7. Control Resource Usage

For large assessments, limit workers:

```bash
aws-cis-assess assess --max-workers 2 --timeout 3600
```

### 8. Enable Detailed Logging

For troubleshooting:

```bash
aws-cis-assess assess --log-level DEBUG --log-file debug.log
```

## Common Workflows

### Initial Security Assessment

```bash
# 1. Validate credentials
aws-cis-assess validate-credentials

# 2. Check available controls
aws-cis-assess list-controls

# 3. Preview assessment scope
aws-cis-assess show-stats

# 4. Run IG1 assessment
aws-cis-assess assess --implementation-groups IG1 --output-format html

# 5. Review results and plan improvements
```

### Regular Compliance Monitoring

```bash
# Monthly comprehensive assessment
aws-cis-assess assess \
  --output-format json,html \
  --output-dir ./monthly-reports/ \
  --log-file monthly-assessment.log

# Weekly IG1 check
aws-cis-assess assess \
  --implementation-groups IG1 \
  --quiet \
  --output-format json \
  --output-file weekly-ig1.json
```

### Focused Security Review

```bash
# Focus on specific security areas
aws-cis-assess assess \
  --controls 3.3,5.2,6.1,8.1 \
  --regions us-east-1,us-west-2 \
  --output-format html \
  --output-file security-review.html
```

### Multi-Account Assessment

```bash
# Account 1
aws-cis-assess assess \
  --aws-profile account1-prod \
  --output-file account1-results.json

# Account 2
aws-cis-assess assess \
  --aws-profile account2-prod \
  --output-file account2-results.json

# Account 3
aws-cis-assess assess \
  --aws-profile account3-prod \
  --output-file account3-results.json
```

### Troubleshooting Workflow

```bash
# 1. Enable debug logging
aws-cis-assess assess \
  --log-level DEBUG \
  --log-file debug.log \
  --verbose

# 2. Check specific regions
aws-cis-assess list-regions --aws-profile problematic-profile

# 3. Test credentials
aws-cis-assess validate-credentials --aws-profile problematic-profile

# 4. Validate configuration
aws-cis-assess validate-config

# 5. Run limited scope
aws-cis-assess assess \
  --controls 1.1 \
  --regions us-east-1 \
  --verbose
```

## Understanding Results

### Compliance Scores

- **Overall Compliance**: Weighted average across all Implementation Groups
- **IG1 Compliance**: Essential cyber hygiene controls
- **IG2 Compliance**: Enhanced security controls (includes IG1)
- **IG3 Compliance**: Advanced security controls (includes IG1+IG2)

### Finding Status

- **COMPLIANT**: Resource meets the control requirements
- **NON_COMPLIANT**: Resource violates the control requirements
- **NOT_APPLICABLE**: Control doesn't apply to this resource
- **INSUFFICIENT_PERMISSIONS**: Cannot assess due to permission issues
- **ERROR**: Assessment failed due to technical issues

### Remediation Guidance

Each non-compliant finding includes:
- Specific remediation steps
- AWS documentation links
- Priority level (HIGH, MEDIUM, LOW)
- Estimated effort

## Next Steps

- **Configuration Guide**: Learn about customizing assessments
- **Troubleshooting Guide**: Resolve common issues
- **CLI Reference**: Complete command reference
- **Developer Guide**: Extend and customize the tool


## AWS Backup Controls (New in v1.0.10)

### Overview

Two new controls have been added to assess AWS Backup service infrastructure:

1. **backup-plan-min-frequency-and-min-retention-check**
   - Validates backup plans have appropriate frequency and retention policies
   - Ensures backups happen regularly (daily minimum)
   - Checks retention periods meet minimum requirements (7 days default)
   - Validates lifecycle policies for cold storage transitions

2. **backup-vault-access-policy-check**
   - Ensures backup vaults have secure access policies
   - Detects publicly accessible backup vaults
   - Identifies overly permissive access policies
   - Warns about dangerous permissions

### Usage

These controls are automatically included in IG1 assessments:

```bash
# Run assessment including new backup controls
aws-cis-assess assess --implementation-groups IG1

# Focus on backup-related controls
aws-cis-assess assess --controls 11.2
```

### Benefits

- **Comprehensive Coverage**: Assesses both resource protection AND backup infrastructure
- **Security Validation**: Ensures backup vaults aren't publicly accessible
- **Compliance Checking**: Validates backup policies meet organizational requirements
- **Ransomware Protection**: Helps identify backup vulnerabilities

### Documentation

For detailed information about AWS Backup controls, see:
- [AWS Backup Controls Implementation Guide](adding-aws-backup-controls.md)
- [AWS Backup Controls Summary](../AWS_BACKUP_CONTROLS_IMPLEMENTATION_SUMMARY.md)
