diff --git a/.github/BRANCH_PROTECTION.md b/.github/BRANCH_PROTECTION.md new file mode 100644 index 0000000..22c3eb9 --- /dev/null +++ b/.github/BRANCH_PROTECTION.md @@ -0,0 +1,28 @@ +# Branch Protection Checklist + +These settings live in GitHub repository settings and cannot be enforced by files alone. + +Protect `master`: + +- Require a pull request before merging. +- Require approvals. +- Require review from Code Owners. +- Dismiss stale approvals when new commits are pushed. +- Require status checks to pass before merging. +- Required checks: + - `Tests on ubuntu-latest` + - `Tests on macos-latest` + - `Tests on windows-latest` + - `Android tools smoke test` + - `Rooted emulator integration` +- Require branches to be up to date before merging. +- Block force pushes. +- Block deletions. +- Restrict who can push to matching branches. +- Do not allow administrators or repository owners to bypass these rules for normal development. + +Recommended workflow: + +- All changes land through PRs. +- Dependabot PRs are merged only after CI is green. +- Release tags are created from protected `master`. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..280d580 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,9 @@ +# Require maintainer review for all repository changes. +* @Codeblin + +# Release, CI, and supply-chain surfaces are especially sensitive. +/.github/ @Codeblin +/dexmachina/ @Codeblin +/pyproject.toml @Codeblin +/THREAT_MODEL.md @Codeblin +/SECURITY.md @Codeblin diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 0cec7b3..bc03c0e 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,3 +5,12 @@ updates: schedule: interval: weekly open-pull-requests-limit: 5 + labels: + - dependencies + groups: + python-dev-dependencies: + patterns: + - pytest* + python-runtime-dependencies: + patterns: + - "*" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 91a5ed9..e3bb886 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,11 +13,13 @@ on: permissions: contents: write + id-token: write jobs: validate-and-release: - name: Validate release metadata + name: Validate, release, and publish runs-on: ubuntu-latest + environment: pypi steps: - name: Check out repository shell: bash @@ -47,6 +49,12 @@ jobs: python -m pip install -e ".[dev]" python -m pytest + - name: Build distributions + shell: bash + run: | + python -m pip install --upgrade uv + python -m uv build + - name: Create GitHub release shell: bash env: @@ -104,3 +112,7 @@ jobs: else: raise PY + + - name: Publish to PyPI + shell: bash + run: python -m uv publish --trusted-publishing always dist/* diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fc02c7..89e7925 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,9 +20,12 @@ All notable changes to DexMachina are documented here. This project follows Sema - Lockfile artifact digest recording and restore-time digest enforcement. - Safe archive extraction that rejects path traversal members. - Release metadata validation and GitHub release workflow for `v*` tags. +- PyPI Trusted Publishing workflow using GitHub OIDC and `uv publish`. +- CODEOWNERS and branch protection checklist. +- Release process documentation. ### Known Gaps - GitHub Release assets are checksum-verified only when upstream publishes a discoverable checksum file or a lockfile digest is available. - Signature verification is not implemented yet. -- PyPI publication is still pending. +- PyPI project Trusted Publisher configuration still must be completed in PyPI/GitHub settings before the first upload. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78daa57..377f4ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,6 +55,8 @@ Tool( ## Pull Requests +All changes should go through pull requests once branch protection is enabled. See `.github/BRANCH_PROTECTION.md` for the repository settings maintainers should enforce. + Before opening a PR: ```bash @@ -64,3 +66,7 @@ dexmachina status --offline ``` If your change affects device flows, include the emulator/device setup you tested against, for example rooted AVD, Genymotion, or Corellium. + +## Releases + +Release tags and PyPI publishing are documented in `docs/RELEASE.md`. diff --git a/README.md b/README.md index 08181fc..d067a4e 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ It is not a replacement for MobSF, Corellium, Burp, or manual reverse-engineerin - Trust model: [THREAT_MODEL.md](THREAT_MODEL.md) - Vulnerability reporting: [SECURITY.md](SECURITY.md) - Contributing and adding tools: [CONTRIBUTING.md](CONTRIBUTING.md) +- Release process: [docs/RELEASE.md](docs/RELEASE.md) +- Branch protection checklist: [.github/BRANCH_PROTECTION.md](.github/BRANCH_PROTECTION.md) - Release history: [CHANGELOG.md](CHANGELOG.md) ### Support matrix diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000..9fdf0e0 --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,56 @@ +# Release Process + +DexMachina releases are tag-driven. + +## One-Time PyPI Setup + +Create the PyPI project and configure Trusted Publishing before pushing the first release tag. + +PyPI Trusted Publisher fields: + +- PyPI project: `dexmachina` +- Owner: `Codeblin` +- Repository: `DexMachina` +- Workflow: `release.yml` +- Environment: `pypi` + +GitHub environment: + +- Create environment `pypi` in repository settings. +- Require reviewer approval for the environment. +- Restrict deployment branches/tags to release tags if available. + +This matches PyPI's Trusted Publishing model: GitHub Actions gets a short-lived OIDC token, PyPI validates that token against the configured publisher, and PyPI mints a short-lived upload token. No long-lived PyPI token is stored in GitHub. + +## Cut A Release + +1. Make sure `pyproject.toml`, `dexmachina/__init__.py`, and `CHANGELOG.md` all reference the same version. +2. Run: + +```bash +python scripts/verify_release.py v0.1.0 +python -m pytest +``` + +3. Commit the release changes. +4. Tag and push: + +```bash +git tag -a v0.1.0 -m "v0.1.0" +git push origin v0.1.0 +``` + +The release workflow will: + +- validate release metadata, +- run tests, +- build distributions, +- create a GitHub Release, +- publish to PyPI through Trusted Publishing. + +## If Publishing Fails + +- Confirm the PyPI Trusted Publisher fields match this repository and workflow exactly. +- Confirm the GitHub environment is named `pypi`. +- Confirm the workflow has `id-token: write`. +- Re-run the tag workflow after fixing configuration. diff --git a/pyproject.toml b/pyproject.toml index f3b1f1a..328a382 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,14 +8,13 @@ version = "0.1.0" description = "Android pentesting tool manager — install, update, and version-lock your toolkit" readme = "README.md" requires-python = ">=3.10" -license = { text = "MIT" } +license = "MIT" authors = [{ name = "DexMachina Contributors" }] keywords = ["android", "pentesting", "frida", "security"] classifiers = [ "Development Status :: 3 - Alpha", "Environment :: Console", "Intended Audience :: Developers", - "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", @@ -44,6 +43,8 @@ dexmachina = "dexmachina.cli:main" [project.urls] Homepage = "https://github.com/Codeblin/dexmachina" Repository = "https://github.com/Codeblin/dexmachina" +Issues = "https://github.com/Codeblin/dexmachina/issues" +Documentation = "https://github.com/Codeblin/dexmachina#readme" Changelog = "https://github.com/Codeblin/dexmachina/blob/main/CHANGELOG.md" "Security Policy" = "https://github.com/Codeblin/dexmachina/security/policy"