Metadata-Version: 2.4
Name: cloudglass
Version: 0.2.0
Summary: See through your cloud's security posture — open-source cloud misconfiguration scanner.
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Requires-Dist: PyYAML>=6.0

# CloudGlass

See through your cloud's security posture. An open-source CLI scanner that
checks your AWS account for common misconfigurations — public S3 buckets,
missing MFA, permissive security groups, unencrypted RDS, disabled CloudTrail,
KMS rotation, and Lambda function URL exposure.

## Install

```bash
pip install -e .
```

## Usage

```bash
cloudglass scan --profile your-aws-profile --region us-east-1
```

### Common flags

| Flag | Default | Description |
|---|---|---|
| `--profile` | (default chain) | AWS named profile |
| `--region` | `us-east-1` | Primary region |
| `--all-regions` | off | Scan every enabled region |
| `--output` | `table` | `table`, `json`, or `sarif` |
| `--fail-on` | `HIGH` | Exit 1 when severity ≥ this (`CRITICAL`/`HIGH`/`MEDIUM`/`LOW`/`NONE`) |
| `--severity` | all | Comma-separated filter e.g. `HIGH,CRITICAL` |
| `--service` | all | Comma-separated service filter e.g. `s3,rds` |
| `--rule-id` | all | Specific rule IDs e.g. `CG-S3-001` |
| `--rules-file` | none | Path to YAML custom rules file |
| `--compliance` | off | Show CIS/SOC2/PCI-DSS tags in table output |

## What it checks (v0.2)

| Rule ID | Check | Severity | CIS | SOC2 | PCI-DSS |
|---|---|---|---|---|---|
| CG-S3-001 | S3 bucket is publicly accessible | CRITICAL | 2.1.5 | CC6.1 | 1.3 |
| CG-S3-002 | S3 bucket missing default encryption | MEDIUM | 2.1.1 | CC6.7 | 3.4 |
| CG-IAM-001 | IAM user has no MFA device | HIGH | 1.10 | CC6.1 | 8.3 |
| CG-IAM-002 | Root account has no MFA | CRITICAL | 1.5 | CC6.1 | 8.3 |
| CG-IAM-003 | Root account has active access keys | CRITICAL | 1.4 | CC6.3 | 7.1 |
| CG-EC2-001 | Security group open to 0.0.0.0/0 or ::/0 | HIGH | 5.2 | CC6.6 | 1.2 |
| CG-RDS-001 | RDS instance is publicly accessible | CRITICAL | 2.3.2 | CC6.1 | 1.3 |
| CG-RDS-002 | RDS instance storage not encrypted | HIGH | 2.3.1 | CC6.7 | 3.4 |
| CG-CT-001 | CloudTrail not enabled in region | HIGH | 3.1 | CC7.2 | 10.1 |
| CG-CT-002 | No multi-region CloudTrail trail | MEDIUM | 3.1 | CC7.2 | — |
| CG-KMS-001 | KMS CMK rotation disabled | MEDIUM | 3.7 | CC6.7 | 3.6 |
| CG-LAMBDA-001 | Lambda function URL with no auth | HIGH | — | CC6.1 | 8.3 |

> **Note:** Compliance tags are indicative starting points, not certified mappings.

## Custom rules (YAML)

Create a YAML file and pass it with `--rules-file`:

```yaml
- id: MY-S3-001
  title: S3 bucket is not encrypted
  severity: HIGH
  resource_type: storage_bucket
  conditions:
    - field: encrypted
      op: is_false
  remediation: Enable SSE-KMS encryption on all buckets.
  compliance:
    - "CIS 2.1.1"
```

Supported `op` values: `equals`, `not_equals`, `contains`, `is_true`, `is_false`, `exists`.
Use `field: metadata.<key>` to access nested metadata fields.

## CI/CD integration

```bash
# Fail the pipeline if CRITICAL findings exist
cloudglass scan --output json --fail-on CRITICAL | jq .

# SARIF output for GitHub Code Scanning
cloudglass scan --output sarif > results.sarif
```

## Required IAM permissions

CloudGlass is **read-only**. Minimum managed policies:

- `arn:aws:iam::aws:policy/SecurityAudit`
- `arn:aws:iam::aws:policy/job-function/ViewOnlyAccess`

Never grant this tool write permissions.

## Architecture

```
collectors/   → pull raw resources from AWS APIs, normalize into Resource objects
models.py     → the shared Resource schema (provider-agnostic)
rules/        → checks that run against normalized resources
engine.py     → matches resources to applicable rules, produces findings
cli.py        → entrypoint: scan, collect, run rules, print results
```

## Roadmap

- [ ] Azure collector (App Registration / Reader role)
- [ ] GCP collector (Workload Identity Federation)
- [ ] Additional services: EKS, ECS, SNS, SQS, Secrets Manager

## License

MIT
