sica-fondt/knowledge/cyber-skills/skills/performing-aws-account-enumeration-with-scout-suite/references/api-reference.md

API Reference: AWS Account Enumeration with Scout Suite

Libraries Used

Library	Purpose
subprocess	Execute Scout Suite CLI scans
json	Parse Scout Suite JSON report output
boto3	AWS SDK for supplementary API calls
os	Read AWS credentials from environment

Installation

pip install scoutsuite boto3

# Or from source
git clone https://github.com/nccgroup/ScoutSuite
cd ScoutSuite
pip install -r requirements.txt
python scout.py --help

Authentication

Scout Suite uses standard AWS credential chain:

import os

# Option 1: Environment variables
os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..."
os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
os.environ["AWS_DEFAULT_REGION"] = "us-east-1"

# Option 2: AWS CLI profile
# scout aws --profile my-profile

# Option 3: IAM Role (EC2 instance profile / ECS task role)
# Automatically detected by boto3

CLI Reference

Full AWS Account Scan

scout aws --report-dir ./scout-report

Scan Specific Services

scout aws --services iam s3 ec2 rds lambda --report-dir ./scout-report

Scan Specific Regions

scout aws --regions us-east-1 us-west-2 eu-west-1 --report-dir ./scout-report

Use Named Profile

scout aws --profile production-readonly --report-dir ./scout-report

Key CLI Flags

Flag	Description
--provider	Cloud provider: aws, azure, gcp
--profile	AWS CLI named profile
--regions	Specific AWS regions to scan
--services	Specific services to audit
--report-dir	Output directory for HTML report
--no-browser	Don't open report in browser
--max-workers	Number of parallel API threads
--result-format	Output format: json, csv
--exceptions	Path to exceptions file (known acceptable findings)
--ruleset	Custom ruleset file for scoring

Python Integration

Run Scout Suite and Parse Results

import subprocess
import json
from pathlib import Path

def run_scout(services=None, regions=None, profile=None, report_dir="/tmp/scout"):
    cmd = ["scout", "aws", "--report-dir", report_dir, "--no-browser"]
    if services:
        cmd.extend(["--services"] + services)
    if regions:
        cmd.extend(["--regions"] + regions)
    if profile:
        cmd.extend(["--profile", profile])

    result = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)
    if result.returncode != 0:
        raise RuntimeError(f"Scout Suite failed: {result.stderr}")

    # Parse the JSON results
    report_path = Path(report_dir) / "scoutsuite-results" / "scoutsuite_results.json"
    if report_path.exists():
        with open(report_path) as f:
            return json.load(f)
    return None

Extract High-Risk Findings

def extract_findings(report, min_severity="warning"):
    severity_order = {"danger": 3, "warning": 2, "info": 1}
    min_level = severity_order.get(min_severity, 1)
    findings = []

    for service_name, service_data in report.get("services", {}).items():
        for rule_name, rule_data in service_data.get("findings", {}).items():
            level = severity_order.get(rule_data.get("level", "info"), 0)
            if level >= min_level:
                findings.append({
                    "service": service_name,
                    "rule": rule_name,
                    "severity": rule_data.get("level"),
                    "description": rule_data.get("description"),
                    "flagged_items": rule_data.get("flagged_items", 0),
                    "checked_items": rule_data.get("checked_items", 0),
                })
    return sorted(findings, key=lambda x: severity_order.get(x["severity"], 0), reverse=True)

Common Findings Categories

Service	Common Findings
IAM	Root account MFA, access key rotation, overly permissive policies
S3	Public buckets, missing encryption, no versioning
EC2	Security groups with 0.0.0.0/0, unencrypted EBS, public IPs
RDS	Public access, no encryption at rest, no multi-AZ
Lambda	Overly permissive roles, environment variable secrets
CloudTrail	Logging disabled, no log file validation
VPC	Default VPC in use, missing flow logs

Output Format

{
  "provider_code": "aws",
  "account_id": "123456789012",
  "last_run": {
    "time": "2025-01-15T10:30:00Z",
    "ruleset_name": "default",
    "run_parameters": {"services": ["iam", "s3", "ec2"]}
  },
  "services": {
    "iam": {
      "findings": {
        "iam-root-account-no-mfa": {
          "level": "danger",
          "description": "Root account does not have MFA enabled",
          "flagged_items": 1,
          "checked_items": 1
        }
      }
    },
    "s3": {
      "findings": {
        "s3-bucket-no-default-encryption": {
          "level": "warning",
          "description": "S3 bucket does not have default encryption",
          "flagged_items": 3,
          "checked_items": 15
        }
      }
    }
  }
}