audit-labs/gh-attest

  1# gh-attest
  2
  3[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=audit-labs_gh-attest&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=audit-labs_gh-attest)
  4[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=audit-labs_gh-attest&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=audit-labs_gh-attest)
  5[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=audit-labs_gh-attest&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=audit-labs_gh-attest)
  6[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=audit-labs_gh-attest&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=audit-labs_gh-attest)
  7[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
  8
  9Turns GitHub security settings into auditor-ready evidence. A GitHub App that
 10records branch protection, scanning alerts, and organization access as they
 11change, maps them to SOC 2 and ISO 27001 controls, and exports point-in-time
 12CSV and PDF evidence packages.
 13
 14Read-only — it never modifies your repositories, permissions, or membership.
 15
 16## What it collects
 17
 18| Signal | Evidence for |
 19| --- | --- |
 20| Branch protection, repository rulesets | SOC 2 CC8.1 · ISO 27001 A.8.32 |
 21| Secret scanning alerts | SOC 2 CC6.6 |
 22| Dependabot alerts | SOC 2 CC7.1, CC7.2 |
 23| Code scanning alerts | ISO 27001 A.8.28, A.8.29 |
 24| Organization / team membership | SOC 2 CC6.2, CC6.3 · ISO 27001 A.5.18 |
 25| Repository inventory | ISO 27001 A.5.9 |
 26
 27Mappings live in `migrations/` and are applied as a join at query time, so a
 28mapping can be corrected without re-ingesting history.
 29
 30## How it works
 31
 32Webhooks capture changes as they happen; an hourly cron polls for state that
 33webhooks never announce (protection that existed before install, and current
 34membership). Each observation is stored as a timestamped snapshot in D1.
 35Exports render off the request path via a queue, into R2.
 36
 37**Stack:** Cloudflare Workers · D1 · R2 · Queues. All storage is provisioned
 38under Cloudflare's `eu` jurisdiction.
 39
 40## Endpoints
 41
 42| Route | Auth | Purpose |
 43| --- | --- | --- |
 44| `GET /` | session | Dashboard: current posture, exports |
 45| `GET /access-review` | session | Membership changes since a date |
 46| `POST /exports`, `/resync`, `/switch` | session | Dashboard actions |
 47| `GET /exports/:id[/download]` | session | Export status / file |
 48| `POST /webhooks/github` | HMAC | App events |
 49| `POST /webhooks/marketplace` | HMAC | Marketplace events |
 50| `POST /admin/{poll,export,cleanup,purge}` | bearer | Operations |
 51
 52Session routes are scoped by installation; admin routes require `ADMIN_TOKEN`.
 53
 54## Development
 55
 56```sh
 57npm install
 58cp .dev.vars.example .dev.vars   # fill in, see below
 59npm run db:migrate:local
 60npm run dev
 61```
 62
 63Type checking: `npm run typecheck`. Generate binding types after editing
 64`wrangler.jsonc`: `npm run types`.
 65
 66## Deployment
 67
 68```sh
 69npm run db:migrate:remote
 70npm run deploy
 71```
 72
 73Secrets are set with `wrangler secret put <NAME>` — never in `wrangler.jsonc`:
 74
 75| Secret | Purpose |
 76| --- | --- |
 77| `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY` | Mint installation tokens |
 78| `GITHUB_WEBHOOK_SECRET` | Verify webhook signatures |
 79| `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET` | Dashboard OAuth |
 80| `SESSION_SECRET` | Sign session cookies |
 81| `ADMIN_TOKEN` | Bearer for `/admin/*` |
 82
 83Pipe the private key from its file rather than pasting it:
 84`wrangler secret put GITHUB_APP_PRIVATE_KEY < key.pem`
 85
 86> Cron triggers occasionally stop firing after a deploy. If the hourly poll
 87> goes quiet, set `triggers.crons` to `[]`, deploy, restore it, and deploy
 88> again — a same-value redeploy does not clear it.
 89
 90## Data handling
 91
 92Evidence is retained for 13 months and exports for 90 days; everything for an
 93installation is deleted when the App is uninstalled. No source code or access
 94tokens are stored. See [PRIVACY.md](PRIVACY.md).
 95
 96Retention periods are defined in `src/index.ts` and restated in `PRIVACY.md` —
 97change both together.
 98
 99## License
100
101GPL-3.0. See [LICENSE](LICENSE).