Metadata-Version: 2.5
Name: datapace-collector
Version: 0.3.0
Summary: Collect read-only RDS evidence from AWS accounts you choose into an allowlisted Datapace evidence bundle.
Project-URL: Homepage, https://datapace.ai
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: boto3
Description-Content-Type: text/markdown

# datapace-collector

Collects read-only RDS evidence from the AWS accounts you choose, for a Datapace Cloud
Self-Assessment. It writes one evidence bundle (`.tgz`) to send to Datapace, plus a
local `aliases.json` that maps each alias in the bundle back to the real resource and
never leaves your machine.

Python ≥ 3.10, one runtime dependency (boto3).

```
datapace-collector --profile 111111111111=prod --profile 222222222222=stage \
  [--billing-profile payer] --regions us-east-1,eu-west-1 --out ./evidence
```

- **Only the named profiles are opened.** Without `--profile` it exits 2; it never
  lists local profiles. Each profile must really be the account it is mapped to
  (`sts:GetCallerIdentity`), or it exits 3.
- **Preflight** probes every permission per account and region and prints each denial
  with the IAM action and the input it costs. `rds:DescribeDBInstances` denied
  everywhere → exit 3, nothing written.
- **Collects** inventory, 90 days of daily and monthly RDS cost, RI/Savings Plans
  coverage, reserved instances, manual snapshots and 30 days of hourly metrics.
- **`--billing-profile`** reads Cost Explorer from a payer; lines for accounts not
  selected are dropped.
- **Exit codes:** 0 bundle written (complete or partial), 1 internal error, 2 usage,
  3 preflight failed, 130 interrupted (partial bundle kept).

## Running it

Python ≥ 3.10. macOS's system `python3` is 3.9: the `.pyz` stops with a message
naming the minimum version and exits 2; install a newer Python (python.org, Homebrew
or uv) and run it with that. The same version ships three ways:

- **The `.pyz`**, for machines where nothing can be installed:
  `python3 datapace-collector-<v>.pyz --profile … --out …`. boto3 is inside the file,
  so it needs no network install. Bundles record `distribution: pyz`.
- **The downloaded wheel**: `pip install ./datapace_collector-<v>-py3-none-any.whl`,
  then `datapace-collector …`.
- **PyPI**: `uvx datapace-collector@0.3.0 …` <!-- x-release-please-version -->
  or `pip install datapace-collector==0.3.0`. <!-- x-release-please-version -->

PyPI and the downloaded wheel are the same file, so both record `distribution: wheel`
and the bundle cannot tell them apart.

On first run the `.pyz` unpacks itself into
`~/.shiv/datapace-collector-<v>.pyz_<build-id>/`, or under `$SHIV_ROOT` if set, and
reuses that copy afterwards. It unpacks before the version check, so a run refused
on Python 3.9 leaves the copy too. Remove it with `rm -rf ~/.shiv/datapace-collector-*`.

## What keeps the bundle safe

- The collector only makes read-only AWS calls, listed in
  `datapace_collector/operations.py` (`READ_ONLY_OPERATIONS`).
- Every record is built field by field from a closed schema: an allowlist, not a
  redaction. Raw ids become `HMAC(salt, kind|account|region|id)` aliases. Account ids,
  ARNs, endpoints, tags and usernames never reach the bundle.
- A denied input is `denied` with a reason code in the manifest, never empty data that
  looks like a result.
- `aliases.json` (mode 0600) sits beside the bundle, never inside it. A later run into
  the same `--out` reuses its salt, so aliases stay stable across bundles. It also
  holds the salt: keep it, and do not upload it.
