Metadata-Version: 2.4
Name: opsfabric-discovery
Version: 0.2.1
Summary: Read-only AWS reliability audit. Alarm coverage assessment for ECS, Lambda, RDS, Aurora, and SQS.
Author: Vaishal Shah
License: MIT
License-File: LICENSE
Keywords: alarms,audit,aws,cloudwatch,observability,ops,reliability,sre
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: boto3>=1.34.0
Requires-Dist: jinja2>=3.1.4
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: weasyprint>=62
Description-Content-Type: text/markdown

# opsfabric-discovery

A read-only AWS reliability audit you run on your own laptop. Produces an executive PDF assessing CloudWatch alarm coverage across ECS, Lambda, RDS, Aurora, and SQS workloads against the OpsFabric reliability baseline.

## See what your audit would look like (no AWS needed)

[**Download a sample report (PDF, ~68 KB)**](docs/sample-audit.pdf)

Or run it yourself in 30 seconds without any AWS credentials:

```bash
pip install opsfabric-discovery
opsfabric-discovery audit --demo
# → out/audit-demo.pdf
```

`--demo` runs against a baked-in synthetic dataset that exercises every feature of the audit (DEGRADED alarm detection, ALB→ECS bridge, critical-gap cards, coverage breakdown). No AWS calls, no credentials needed. Same matching engine, same PDF — only the input is fake.

## What it does

- Discovers AWS resources via Resource Explorer 2 across one or all enabled regions.
- Maps CloudWatch alarms to those resources using a five-strategy matcher (exact dimensions, ALB target-group bridge for ECS, namespace + partial dimensions, log-group → metric-filter linkage, naming heuristic).
- Detects alarms that exist but won't notify (actions disabled / no SNS target / `INSUFFICIENT_DATA`) and surfaces them as DEGRADED — they don't count toward coverage.
- Scores required-check coverage against a baseline pack (`discovery_fabric/data/alarm_pack.yaml`).
- Renders an executive PDF (3 pages, McKinsey-style) plus JSON appendices for every artifact.

## Trust statement

- **Read-only.** Calls only AWS describe / list APIs. Never creates, modifies, or deletes any resource.
- **Runs on your laptop.** No telemetry, no phone-home. Your data never leaves your machine.
- **Source is auditable.** Open the installed Python files — every AWS call is visible.
- **Minimum IAM permissions:** `sts:GetCallerIdentity`, `ec2:DescribeRegions`, `resource-explorer-2:ListViews`/`GetView`/`Search`, `tag:GetResources`, `cloudwatch:DescribeAlarms`, `logs:DescribeLogGroups`/`DescribeMetricFilters`, `ecs:ListClusters`/`ListServices`/`DescribeServices`/`DescribeTaskDefinition`, `lambda:ListFunctions`/`GetFunction`, `rds:DescribeDBInstances`/`DescribeDBClusters`, `sqs:ListQueues`/`GetQueueAttributes`. Read-only across the board.

## Install

```bash
pip install opsfabric-discovery
opsfabric-discovery --help
```

## Quickstart

Once installed, from any directory:

```bash
# Audit a profile from ~/.aws/credentials
opsfabric-discovery audit --profile prod --regions all --account-alias acme-prod

# Or via STS assume-role (cross-account)
opsfabric-discovery audit \
  --assume-role-arn arn:aws:iam::CUSTOMER_ACCOUNT:role/OpsFabricAuditor \
  --external-id agreed-secret \
  --regions all \
  --account-alias acme-prod

# Outputs land in ./out/ by default; override with --output-dir
ls out/
# audit-<account-id>-<YYYYMMDD>.pdf
# alarm-coverage-score.json
# alarm-coverage-missing.json
# resource-mapping.json
# all-resources.json
# audit-meta.json
```

