preflight-cli 0.1.0__tar.gz

preflight_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear, concise description of what went wrong.
+
+**To reproduce**
+Steps to reproduce, e.g.:
+1. Run `preflight scan --profile ...`
+2. ...
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- Preflight version: `preflight --version`
+- OS/platform:
+- Python version (if run from source):
+- Install method (curl / pipx / brew / docker):
+
+**Logs / output**
+Paste relevant output. **Please redact account IDs, resource names/ARNs, and any credentials before pasting.**
+
+**Additional context**
+Anything else that's relevant.

preflight_cli-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/jetonecloud/preflight/security/policy
+    about: Please do not report security vulnerabilities as public issues — see SECURITY.md instead.

preflight_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new check, module, or capability
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+**What problem does this solve?**
+Describe the gap. If this is a new check, which module does it belong to (Cost, Security/IAM, Reliability, Delivery & IaC, Observability, Bus factor)?
+
+**Proposed approach**
+How would this be detected? Which read-only AWS API(s) would it need (`Get*`/`List*`/`Describe*` only)?
+
+**False positive risk**
+How could this check produce a false positive, and how would you guard against it?
+
+**Alternatives considered**
+Any other ways to solve this, including existing tools that might already cover it.

preflight_cli-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What does this change do, and why? -->
+
+## What does this read from AWS?
+
+<!-- List any new API calls. Confirm each is Get*/List*/Describe* only and has been added to iam/policy.json and the module's declared permissions. -->
+
+- [ ] No new AWS API calls, OR
+- [ ] New calls added, all read-only, and added to `iam/policy.json`
+- [ ] `SECURITY.md` updated if this changes what Preflight reads
+
+## Test plan
+
+- [ ] Added/updated tests, including a no-finding case and a false-positive guard case
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check . && uv run ruff format --check .` passes
+
+## Checklist
+
+- [ ] No credentials, secrets, or raw API responses are logged or transmitted
+- [ ] No write/mutating AWS calls introduced
+- [ ] License-compatible if logic was adapted from another project (attribution added to `NOTICE`)

preflight_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  # Release reuses these jobs, so a tag can't ship something that doesn't pass.
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  install-script:
+    # The installer is what most people will actually run, so hold it to the
+    # same bar as the Python: POSIX sh only, no shellcheck warnings.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: shellcheck --shell=sh install.sh
+      - run: sh -n install.sh
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run pytest --cov --cov-report=term-missing
+
+  policy-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify IAM policy contains no write/wildcard actions
+        run: |
+          python3 - <<'EOF'
+          import json, sys
+          with open("iam/policy.json") as f:
+              policy = json.load(f)
+          allowed_prefixes = ("Get", "List", "Describe")
+          # Read-only actions that don't follow Get/List/Describe naming but
+          # perform no mutation. Keep in sync with tests/test_policy.py.
+          exceptions = {"cloudtrail:LookupEvents"}
+          bad = []
+          for stmt in policy.get("Statement", []):
+              actions = stmt.get("Action", [])
+              if isinstance(actions, str):
+                  actions = [actions]
+              for action in actions:
+                  if action == "*" or ":" not in action:
+                      bad.append(action)
+                      continue
+                  if action in exceptions:
+                      continue
+                  verb = action.split(":", 1)[1]
+                  if not verb.startswith(allowed_prefixes) or verb == "*":
+                      bad.append(action)
+          if bad:
+              print("Non-read-only actions found in iam/policy.json:", bad)
+              sys.exit(1)
+          print("iam/policy.json is read-only. OK.")
+          EOF

preflight_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,172 @@
+name: Release
+
+# Tag a commit on main to cut a release:
+#
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Nothing ships unless CI passes and the tag matches preflight.__version__.
+# Assets are named without a version, so the installer can always fetch
+# .../releases/latest/download/preflight-<platform> without calling the API.
+
+on:
+  push:
+    tags: ["v*"]
+  # Dry run: builds and smoke-tests the binaries, publishes nothing.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  version-check:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Tag must match the packaged version
+        # Both places: __version__ is what the binary reports, the project
+        # metadata is what PyPI publishes. A release where they disagree
+        # ships a binary that misreports itself.
+        run: |
+          set -eu
+          uv sync --all-extras --dev
+          tag="${GITHUB_REF_NAME#v}"
+          attr=$(uv run python -c 'import preflight; print(preflight.__version__)')
+          meta=$(uv run python -c 'from importlib.metadata import version; print(version("preflight-cli"))')
+          echo "tag=$tag  __version__=$attr  metadata=$meta"
+          if [ "$tag" != "$attr" ] || [ "$tag" != "$meta" ]; then
+            echo "::error::tag v$tag doesn't match the package ($attr / $meta)."
+            echo "Bump src/preflight/__init__.py and pyproject.toml together, or retag."
+            exit 1
+          fi
+          echo "v$tag matches the package. OK."
+
+  build:
+    needs: [ci]
+    strategy:
+      fail-fast: false
+      matrix:
+        # Oldest available image per platform: a binary built against an older
+        # glibc/macOS SDK runs on newer systems, but not the other way round.
+        # macos-15-intel is the Intel runner now that macos-13 is retired.
+        include:
+          - { os: ubuntu-22.04, target: linux-x86_64 }
+          - { os: ubuntu-22.04-arm, target: linux-aarch64 }
+          - { os: macos-15-intel, target: macos-x86_64 }
+          - { os: macos-14, target: macos-arm64 }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install the project and PyInstaller
+        run: |
+          uv sync --all-extras --dev
+          uv pip install pyinstaller
+
+      - name: Build a single-file binary
+        # --add-data is load-bearing: core/cfn.py reads the CloudFormation
+        # template through importlib.resources, which finds nothing in a
+        # frozen bundle unless the file is copied in alongside the package.
+        #
+        # boto3 needs no flags here. Nothing imports it yet, so it isn't
+        # bundled at all; once the checks do, PyInstaller's bundled
+        # boto3/botocore hooks collect the service data on their own. The
+        # smoke test below is what proves that, build by build.
+        run: |
+          uv run pyinstaller \
+            --onefile \
+            --name preflight \
+            --paths src \
+            --add-data "src/preflight/templates/role.cfn.yaml.j2:preflight/templates" \
+            src/preflight/cli.py
+
+      - name: Smoke-test the binary
+        # Catches a missing template, a missing boto3 data file, and a binary
+        # that can't start at all — none of which the test suite can see.
+        run: |
+          set -eu
+          ./dist/preflight --help > /dev/null
+          ./dist/preflight scan --list-modules
+          ./dist/preflight scan -m cost --print | grep -q "AWSTemplateFormatVersion"
+          ./dist/preflight scan -m cost --services ec2 --print | grep -q "ec2:DescribeVolumes"
+          ./dist/preflight scan -m cost --out "$RUNNER_TEMP/role.yaml"
+          grep -q "PreflightReadOnlyRole" "$RUNNER_TEMP/role.yaml"
+          echo "binary works on ${{ matrix.target }}"
+
+      - name: Name the asset after its platform
+        run: mv dist/preflight "preflight-${{ matrix.target }}"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: preflight-${{ matrix.target }}
+          path: preflight-${{ matrix.target }}
+          if-no-files-found: error
+
+  publish:
+    needs: [build, version-check]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the release and upload assets
+      id-token: write # OIDC, for build provenance
+      attestations: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: preflight-*
+          merge-multiple: true
+
+      - name: Checksums
+        run: |
+          cd dist
+          chmod +x preflight-*
+          sha256sum preflight-* > checksums.txt
+          cat checksums.txt
+
+      - name: Attest what built these binaries
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: dist/preflight-*
+
+      - name: Publish the release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/preflight-*
+            dist/checksums.txt
+            install.sh
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+
+  publish-pypi:
+    # Makes `pipx install preflight-cli` and `uv tool install preflight-cli`
+    # real. Needs a PyPI trusted publisher for this repo + workflow; delete
+    # this job if you'd rather not publish to PyPI yet.
+    needs: [build, version-check]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC, so there's no API token to store
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

preflight_cli-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.installed.cfg
+*.egg
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+uv.lock.bak
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# Type checking / lint caches
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Preflight output (never commit scan output — may contain account-identifying data)
+reports/
+*.preflight.json
+*.preflight.html
+preflight-report-*
+
+# AWS / secrets — defense in depth, these must never exist in this repo
+.aws/
+*.pem
+*.key
+credentials
+credentials.json
+.env
+.env.*
+!.env.example
+
+# Local drafts and notes
+.local/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

preflight_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- `preflight scan` first slice: pick modules, then generate the read-only CloudFormation role those modules need. Runs entirely offline — no AWS calls, no credentials.
+  - Interactive picker listing every module, with Cost Check selectable and the rest marked as coming soon.
+  - A second picker for the permissions themselves: every AWS service the selected modules need starts checked, and you can switch off the ones you'd rather not grant. Up/Down to move, Enter to check or uncheck, `a` for all and `n` for none, then Enter on the Continue row. Where keypresses can't be read one at a time — a pipe, CI — the same picker takes typed answers instead. `sts:GetCallerIdentity` is always included. Non-interactively that's `--services ec2,rds`.
+  - One step to a screen: each step clears the last and keeps the wordmark, and step 3 just asks where to save — press Enter for the directory you ran the command from.
+  - `--modules cost --save` for non-interactive use, plus `--services`, `--print`, `--out`, `--force` and `--list-modules`.
+  - Generated templates are deterministic, carry the command that reproduces them (including any service narrowing), and name only the actions the selected modules declare.
+- Module registry (`preflight.modules`) where each module declares the IAM actions its checks call. The union of all modules matches `iam/policy.json`, which a test enforces.
+- Generation-time read-only guard (`preflight.core.iam`): a module that declares a write or wildcard action fails the build rather than ending up in a deployed role.
+- `preflight --version`, on stdout, so scripts (including the installer) can read it.
+- Release pipeline: tagging `v*` reruns CI, checks the tag against `preflight.__version__`, builds a single-file binary per platform with PyInstaller, smoke-tests each one by generating a role template with it, then publishes the binaries, `checksums.txt`, a signed build provenance attestation, and `install.sh` to GitHub Releases — plus the sdist and wheel to PyPI via trusted publishing. See [`docs/release.md`](docs/release.md).
+- `install.sh`: detects platform, downloads from the latest release, verifies the SHA-256 against `checksums.txt` and refuses to install on a mismatch. Honours `PREFLIGHT_VERSION` and `PREFLIGHT_BIN`. This is what `curl -fsSL https://jetonecloud.com/preflight | sh` serves.
+- Project scaffolding: license, contribution guidelines, security policy, issue/PR templates, CI workflow.
+
+### Fixed
+- Repository links pointed at a `jet1-cloud/preflight` that doesn't exist; they're `jetonecloud/preflight` now.
+- `SECURITY.md` described a `.sig`/`.sha256` verification flow and a `docs/verifying-releases.md` that didn't exist. It now documents the checksum and `gh attestation verify` steps the release pipeline actually produces.
+
+### Notes
+- The checks themselves aren't wired up yet, so `--profile`, `--region` and `--role-arn` are accepted but inert. This release gets the permissions in place first.

preflight_cli-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, pull requests, discussions) and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers at **conduct@jetonecloud.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

preflight_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to Preflight
+
+Thanks for considering a contribution. Preflight is Apache-2.0 licensed and built in the open — see [`CLAUDE.md`](CLAUDE.md) for the full project context, principles, and roadmap before diving in.
+
+## Ground rules
+
+1. **Read-only, no exceptions.** Any code that calls a write/mutating AWS API will be rejected. Every new API call must be added to the relevant module's declared permissions and to [`iam/policy.json`](iam/policy.json), with only the minimal `Get*`/`List*`/`Describe*` action needed.
+2. **Never log or transmit credentials, secrets, or raw API responses.** Findings must be derived/minimized before they leave a module.
+3. **License hygiene.** Do not copy GPL/AGPL-licensed code into this repo. If you're porting check logic from another open-source project, confirm its license is compatible (Apache-2.0/MIT with attribution) and add the attribution to [`NOTICE`](NOTICE).
+4. **Avoid false positives over false negatives.** If a check can't confidently tell whether something is a real problem (e.g., "idle" without checking tags/recent activity), don't flag it, or lower its confidence and say why.
+5. **Plain language.** Findings and recommendations should read like something you'd say to a startup CTO on a call, not a raw API dump.
+
+## Development setup
+
+```sh
+git clone https://github.com/jetonecloud/preflight.git
+cd preflight
+uv sync
+uv run pytest
+```
+
+- Python 3.11+, managed via `uv` and `pyproject.toml`.
+- Lint/format with **Ruff**: `uv run ruff check . && uv run ruff format .`
+- Tests with **pytest** + **moto** for AWS mocking: `uv run pytest`
+
+## Adding or changing a module
+
+- Each module is a self-contained plugin under `modules/`; shared logic belongs in `core/`.
+- Declare the exact IAM actions the module needs. Update `iam/policy.json` and `SECURITY.md` if the set of data read changes.
+- Every finding must conform to the shared finding schema (`id`, `module`, `title`, `severity`, `resource`, `evidence`, `estimated_monthly_savings` (optional), `recommendation`, `confidence`).
+- Add tests for every new check, including at least:
+  - A case with no finding (the check correctly stays quiet)
+  - A false-positive guard case (e.g., a resource that looks idle but is tagged/recently active)
+- If the check estimates dollar savings, keep the estimate conservative and show the derivation (region, pricing API lookup, assumptions) in the finding's evidence.
+
+## Commit messages
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/): `<type>: <summary>`, optionally followed by a body explaining why.
+
+Common types: `feat`, `fix`, `docs`, `chore`, `ci`, `test`, `refactor`.
+
+```
+chore: scaffold enterprise repo structure
+
+Add README, contribution/security/conduct docs, GitHub issue/PR
+templates, CI workflow with a read-only IAM policy check, pyproject
+packaging, a minimal CLI skeleton, and the baseline read-only IAM
+policy and role template.
+```
+
+Prefer one commit per logical change where practical, but a single well-described commit is fine for a batch of related scaffolding/setup work.
+
+## Pull requests
+
+1. Open an issue first for anything beyond a small fix, so we can discuss approach before you invest time.
+2. Keep PRs focused — one module/feature/fix per PR.
+3. Include tests. CI (lint + tests) must pass.
+4. Describe what the change reads from AWS and why, so reviewers can verify it stays read-only.
+5. By submitting a PR, you agree your contribution is licensed under Apache-2.0.
+
+## Code of conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). Please read it before participating in issues, PRs, or discussions.
+
+## Reporting bugs vs. security issues
+
+- Functional bugs: open a GitHub issue using the bug report template.
+- Security vulnerabilities (especially anything that writes to AWS, leaks credentials, or transmits data without consent): follow [`SECURITY.md`](SECURITY.md) instead — do not open a public issue.