feat(phase-2): real AWS mode, 4 new S3 checks, tests, CI

- AWS real-mode is default; --simulated flag for explicit opt-in
- 4 new S3 checks: PUBLIC-ACL, PUBLIC-POLICY, NO-LOGGING, NO-MFA-DELETE
- Fix XSS in HTML reporter (html.escape)
- Fix i18n (simulated findings now in English)
- Fix exit codes (1 on findings, 2 on usage error, 3 on runtime)
- Fix STS lazy init (no longer crashes in __init__)
- Fix Account BPA empty-dict logic
- Wire YAML rules to AWS scanner via RuleRegistry
- 36 tests with moto (92.44% coverage)
- GitHub Actions CI (pytest + ruff on Python 3.9-3.12)
- pyproject.toml for pip install -e .
- CLI: --output, --severity, --simulated flags

Author: frangelbarrera

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
+          pip install -e .
+
+      - name: Lint with ruff
+        run: ruff check cms tests
+
+      - name: Run tests with coverage
+        run: pytest -v
+
+      - name: Upload coverage to artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: |
+            .coverage
+            htmlcov/
+          if-no-files-found: ignore

CONTRIBUTING.md

@@ -28,30 +28,45 @@ Thanks for your interest in improving cloud security! This tool aims to be a lig
 git clone https://github.com/frangelbarrera/Cloud-Misconfig-Scanner.git
 cd Cloud-Misconfig-Scanner
 pip install -r requirements.txt
-python cms.py --provider aws --simulated  # verify it runs
+pip install -r requirements-dev.txt
+pip install -e .
+
+# Run tests with coverage (>=80% enforced)
+pytest -v
+
+# Lint
+ruff check cms tests
+
+# Verify the CLI works
+python cms.py --provider aws --simulated  # simulated mode
 ```
 
 ## Code Style
-- **Python**: PEP 8, type hints encouraged
-- **Imports**: stdlib → third-party → local (isort)
+- **Python**: PEP 8, type hints encouraged (modern `X | None` syntax with `from __future__ import annotations`)
+- **Imports**: stdlib → third-party → local (enforced by `ruff`/isort)
 - **Docstrings**: Google style for public functions
 - **Tests**: Required for new checks (use `moto` for AWS mocking)
+- **Lint**: `ruff check cms tests` must pass before merge
+- **Coverage**: `pytest --cov=cms --cov-fail-under=80` is enforced by CI
 
 ## Adding a New AWS S3 Check
 
-1. Add the check logic to `cms/providers/aws_s3.py`
-2. Add a rule entry to `cms/checks/aws_s3_rules.yaml`
-3. Test with `moto` mock or real AWS sandbox
+1. Add the rule entry to `cms/checks/aws_s3_rules.yaml` (id, title, severity, description, remediation)
+2. Add the check logic to `cms/providers/aws_s3.py` (call `self._add_finding(res, "RULE-ID", resource, evidence=...)`)
+3. Add a test in `tests/test_aws_s3_scanner.py` using `moto` to mock the bucket state
 4. Update README if user-facing
+5. Run `pytest` and `ruff check cms tests` before committing
 
 ## Adding a New Cloud Provider
 
 1. Create `cms/providers/<provider>_<service>.py`
-2. Subclass `ProviderScanner` from `cms/providers/base.py`
-3. Implement `scan()` method with real API calls
-4. Add YAML rules in `cms/checks/<provider>_<service>_rules.yaml`
-5. Update `cms.py` CLI to support the new provider
-6. Add IAM permissions docs in `docs/iam/`
+2. Subclass `ProviderScanner` from `cms/providers/base.py` and set `provider` and `service` class attributes
+3. Implement the `scan()` method with real API calls
+4. Load rules via `RuleRegistry(load_registry(path))` so finding metadata comes from YAML
+5. Add YAML rules in `cms/checks/<provider>_<service>_rules.yaml`
+6. Register the provider in `cms/cli.py` (`_scan_all` function)
+7. Add IAM permissions docs in `docs/iam/`
+8. Add tests using `moto` (AWS) or the equivalent mock framework
 
 ## Security Considerations
 
@@ -64,10 +79,10 @@ python cms.py --provider aws --simulated  # verify it runs
 
 - [ ] Azure Blob real API implementation (`azure-storage-blob`)
 - [ ] GCP Storage real API implementation (`google-cloud-storage`)
-- [ ] Test coverage with `pytest` + `moto`
-- [ ] GitHub Actions CI pipeline
+- [ ] AWS IAM scanning module
 - [ ] SARIF output format
 - [ ] Docker container support
+- [ ] Slack webhook notifications
 
 ## License
 

README.md

@@ -1,23 +1,27 @@
 # Cloud Misconfig Scanner
 
+[![CI](https://github.com/frangelbarrera/Cloud-Misconfig-Scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/frangelbarrera/Cloud-Misconfig-Scanner/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![AWS](https://img.shields.io/badge/AWS-S3-orange.svg)](https://aws.amazon.com/s3/)
 [![Last Commit](https://img.shields.io/github/last-commit/frangelbarrera/Cloud-Misconfig-Scanner)](https://github.com/frangelbarrera/Cloud-Misconfig-Scanner)
 
-> A Python CLI tool for detecting misconfigurations in cloud storage services. Currently supports **AWS S3 with real API scanning**. Azure Blob and GCP Storage are on the roadmap.
+> A Python CLI tool for detecting misconfigurations in cloud storage services. **AWS S3 is fully supported with real API scanning.** Azure Blob and GCP Storage currently run in simulated mode (roadmap).
 
 ## Features
 
 ### AWS S3 (Active)
-- **Real API scanning** via boto3 (uses your AWS credentials)
-- **Account-level Public Access Block** verification
-- **Bucket-level Public Access Block** per bucket
+- **Real API scanning** via boto3 (auto-detects your AWS credentials)
+- **Account-level Block Public Access (BPA)** verification
+- **Bucket-level BPA** per bucket (all four flags checked)
 - **Server-side encryption** detection
 - **Versioning** status check
-- **Bucket ACL** analysis (public-read, public-read-write)
-- **Bucket Policy** analysis (public `Principal: *`)
-- **Access logging** verification
+- **Bucket ACL** analysis — flags `AllUsers` / `AllAuthenticatedUsers` grants as CRITICAL
+- **Bucket Policy** analysis — flags `Principal: "*"` Allow statements as CRITICAL
+- **Server access logging** verification
+- **MFA Delete** status check (when versioning is enabled)
+- **Simulated mode** as a graceful fallback when no AWS credentials are present
+- **YAML-driven rules** — all finding metadata lives in `cms/checks/aws_s3_rules.yaml`, consistent with Azure/GCP
 
 ### Azure Blob (Roadmap)
 - Simulated mode only (real SDK integration planned)
@@ -30,38 +34,63 @@
 ### Prerequisites
 - Python 3.9+
 - AWS account with read-only S3 permissions (for real scanning)
-- AWS credentials configured (`~/.aws/credentials` or environment variables)
+- AWS credentials configured (`~/.aws/credentials` or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` env vars)
 
 ### Installation
 
 ```bash
 git clone https://github.com/frangelbarrera/Cloud-Misconfig-Scanner.git
 cd Cloud-Misconfig-Scanner
+
+# Runtime dependencies
 pip install -r requirements.txt
+
+# OR: editable install (also registers the console script)
+pip install -e .
 ```
 
 ### Usage
 
-#### Real AWS S3 Scan
+#### Real AWS S3 Scan (default behaviour)
 ```bash
-# Using default AWS profile
+# Auto-detects credentials and runs in real mode
 python cms.py --provider aws
 
-# Using specific profile
+# Using a specific profile
 python cms.py --provider aws --profile my-profile
 
 # JSON output
 python cms.py --provider aws --format json
 
-# HTML report (saved to report.html)
-python cms.py --provider aws --format html
+# HTML report to a specific file
+python cms.py --provider aws --format html -o report.html
+
+# Only show HIGH and CRITICAL findings
+python cms.py --provider aws --severity HIGH
+
+# Scan only specific buckets
+python cms.py --provider aws --targets bucket-a,bucket-b
 ```
 
-#### Simulated Mode (no AWS credentials needed)
+#### Simulated Mode
 
-The scanner automatically detects when AWS credentials are not available (`~/.aws/credentials` missing) and runs in simulated mode. No extra flag is needed — just run:
+Simulated mode emits one finding per rule in `cms/checks/aws_s3_rules.yaml` against a fake bucket, so you can exercise the CLI/reporters without cloud credentials.
 
-python cms.py --provider aws
+```bash
+# Force simulated mode (useful for CI / sandbox testing)
+python cms.py --provider aws --simulated
+```
+
+If no AWS credentials are detected at all, the scanner auto-falls-back to simulated mode.
+
+### Exit Codes
+
+| Code | Meaning                            |
+|------|------------------------------------|
+| 0    | No findings (posture looks clean)  |
+| 1    | Findings detected                  |
+| 2    | CLI usage error                    |
+| 3    | Scanner runtime error              |
 
 ### Required AWS IAM Permissions
 
@@ -76,69 +105,105 @@ Key permissions:
 - `s3:GetBucketPolicy`
 - `s3:GetBucketLogging`
 - `s3control:GetPublicAccessBlock`
+- `sts:GetCallerIdentity`
 
 ## Architecture
 
 ```
 Cloud-Misconfig-Scanner/
-├── cms.py                    # CLI entry point
+├── cms.py                    # Legacy CLI entry point (delegates to cms.cli)
 ├── cms/
+│   ├── __init__.py
+│   ├── __main__.py           # Allows `python -m cms`
+│   ├── cli.py                # CLI implementation (argparse + exit codes)
 │   ├── core/                 # Core engine
 │   │   ├── models.py         # Resource, Finding, ScanResult dataclasses
-│   │   ├── rules.py          # YAML rule loader
-│   │   ├── reporter.py       # Text/JSON output
-│   │   └── html_reporter.py  # HTML report generator
-│   ├── providers/            # Cloud providers
-│   │   ├── base.py           # ProviderScanner ABC
-│   │   ├── aws_s3.py         # AWS S3 scanner (real API)
+│   │   ├── rules.py          # YAML rule loader + RuleRegistry
+│   │   ├── reporter.py       # Text/JSON output + severity filtering
+│   │   └── html_reporter.py  # HTML report (XSS-safe, CRITICAL supported)
+│   ├── providers/            # Cloud providers (all subclass ProviderScanner)
+│   │   ├── base.py           # ProviderScanner ABC + shared helpers
+│   │   ├── aws_s3.py         # AWS S3 scanner (real API + simulated fallback)
 │   │   ├── azure_blob.py     # Azure Blob (simulated, roadmap)
 │   │   └── gcp_storage.py    # GCP Storage (simulated, roadmap)
 │   └── checks/               # YAML rule definitions
 │       ├── aws_s3_rules.yaml
 │       ├── azure_blob_rules.yaml
 │       └── gcp_storage_rules.yaml
-└── docs/
-    └── iam/
-        └── aws_least_privilege.json
+├── tests/                    # pytest + moto test suite
+│   ├── conftest.py
+│   ├── test_rules.py
+│   ├── test_reporter.py
+│   ├── test_html_reporter.py
+│   ├── test_aws_s3_scanner.py
+│   └── test_cli.py
+├── docs/
+│   └── iam/
+│       ├── aws_least_privilege.json
+│       ├── azure_least_privilege.md
+│       └── gcp_least_privilege.md
+├── .github/workflows/ci.yml  # GitHub Actions: pytest + ruff on push/PR
+├── pyproject.toml            # pip install -e . support + tool config
+├── requirements.txt          # Runtime deps
+└── requirements-dev.txt      # Test/lint deps
 ```
 
 ## Output Formats
 
 ### Text (default)
 ```
-[CRITICAL] S3-BUCKET-PUBLIC-ACL
-  Resource: my-bucket
-  Description: Bucket ACL allows public read access
-  Remediation: Remove AllUsers grant from bucket ACL
-
-[HIGH] S3-NO-ENCRYPTION
-  Resource: another-bucket
-  Description: Server-side encryption is not enabled
-  Remediation: Enable SSE-S3 or SSE-KMS on the bucket
+Findings:
+- [CRITICAL] AWS-S3-PUBLIC-ACL | Bucket ACL allows public access -> aws:my-bucket
+- [HIGH] AWS-S3-ENCRYPTION | No default server-side encryption -> aws:another-bucket
 ```
 
 ### JSON
 ```json
-{
-  "findings": [
-    {
-      "rule_id": "S3-BUCKET-PUBLIC-ACL",
-      "severity": "CRITICAL",
-      "resource": "my-bucket",
-      "description": "Bucket ACL allows public read access",
-      "remediation": "Remove AllUsers grant from bucket ACL"
-    }
-  ]
-}
+[
+  {
+    "rule_id": "AWS-S3-PUBLIC-ACL",
+    "title": "Bucket ACL allows public access",
+    "severity": "CRITICAL",
+    "description": "...",
+    "remediation": "...",
+    "resource": {
+      "provider": "aws", "service": "s3", "account": "123456789012",
+      "region": "us-east-1", "name": "my-bucket", "meta": {}
+    },
+    "evidence": { "public_grants": [{"grantee": "http://acs.amazonaws.com/groups/global/AllUsers", "permission": "READ"}] }
+  }
+]
 ```
 
 ### HTML
-Interactive HTML report with severity color-coding (CRITICAL=red, HIGH=orange, MEDIUM=yellow, LOW=blue).
+Self-contained HTML report with severity color-coding (CRITICAL=red, HIGH=pink, MEDIUM=yellow, LOW=blue). All fields are HTML-escaped to prevent XSS.
+
+## Development
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+pip install -e .
+
+# Run tests with coverage (>=80% enforced)
+pytest -v
+
+# Lint
+ruff check cms tests
+```
 
 ## Roadmap
 
 - [x] AWS S3 real API scanning
-- [ ] AWS S3 Bucket Policy deep analysis
+- [x] AWS S3 Bucket Policy deep analysis (Principal: "*" detection)
+- [x] AWS S3 Bucket ACL analysis (AllUsers / AllAuthenticatedUsers)
+- [x] AWS S3 Access Logging verification
+- [x] AWS S3 MFA Delete verification
+- [x] YAML-driven AWS rules (consistency with Azure/GCP)
+- [x] Tests with moto + pytest (>=80% core coverage)
+- [x] GitHub Actions CI (pytest + ruff)
+- [x] CLI improvements: --output, --severity, exit codes
+- [x] HTML reporter: XSS fix, CRITICAL severity
 - [ ] AWS IAM scanning (overly permissive policies)
 - [ ] Azure Blob real API scanning
 - [ ] GCP Storage real API scanning
@@ -155,8 +220,8 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
 Areas needing help:
 - Azure Blob real API implementation
 - GCP Storage real API implementation
-- Test coverage (pytest + moto)
-- CI/CD pipeline
+- AWS IAM scanning module
+- SARIF output format
 
 ## Security