OSS Protector developer docs

OSS Protector exposes a small public REST API (used by other tools and automations to read the public account directory) and a set of authenticated maintainer endpoints (used by the dashboard at /dashboard). All responses are JSON.

The shape stabilises through schema_version; breaking changes bump the date.

https://oss-protector.raedbahri90.workers.dev

Every public response includes "schema_version" (an ISO date). When we bump this, the response shape changed. Pin consumers to a date and re-test before upgrading.

Current: 2026-05-30

Three public read endpoints. All are throttled per client IP — see Rate limits.

All filterable endpoints (/api/accounts, /api/protectors) accept the same pagination params and return a page_info block.

{
  "accounts": [...],
  "count": 50,
  "page_info": {
    "limit": 50,
    "offset": 0,
    "total": 149,
    "hasMore": true
  },
  "filters": { ... },
  "schema_version": "2026-05-30"
}

count is this page's row count; total is the full matched set. To iterate, increment offset by limit until hasMore is false.

Authenticated endpoints used by the dashboard. They require an active Better Auth session cookie — sign in at /login. Not rate-limited by the public 60 req/min bucket. All return 401 when called without a session.

Invalid filter values (unknown status/ reason, out-of-range limit/offset/min_score) return HTTP 400 with a structured body so you can correct the request without scraping the message:

{
  "error": "Invalid limit \"1000\". Allowed: 1–500.",
  "field": "limit",
  "value": "1000",
  "allowed": ["1–500"]
}

Bot-driven endpoints — invoked by mentioning @oss-protector in a PR or issue comment.

Anyone can file a report by mentioning the bot. Submitted / needs-review reports are tracked but only validated or corroborated reports affect shared scores.

@oss-protector review this user
@oss-protector flag this user reason: fake bounty
@oss-protector recommend block reason: malicious code

Repo owners and members (author_association of OWNER, MEMBER, or COLLABORATOR) can correct the system from any PR comment. Each correction is applied silently and recorded as an in-app notification — no reply is posted to the PR.

@oss-protector dismiss     # false positive: dismiss all open reports
@oss-protector confirm     # validate the latest open report
@oss-protector allow       # allowlist the PR author (sticky)
@oss-protector reset       # clear a prior allowlist; recompute from current signals

Each repo can tune the analyzer with .github/oss-protector.json:

{
  "enabled": true,
  "analyzePrivateRepositories": false,
  "minimumLikelyAbuseConfidence": 80,
  "trustedAuthors": ["dependabot[bot]", "renovate[bot]"],
  "ignoredPaths": ["docs/", "examples/"]
}

The same fields can be edited from the Repo policy tab in the dashboard. When both exist, the committed file wins per-field; the dashboard value fills in any field the file doesn't set.

OSS Protector uses Better Auth for end-user sign-in and an installation-token model (@octokit/auth-app) for webhook actions.

The default sign-in path. Better Auth handles the OAuth round trip — clicking Continue with GitHub on /login POSTs to /api/auth/sign-in/social, which returns a github.com authorize URL the browser follows. Callback URL: /api/auth/callback/github.

Optional email-only sign-in. Requires RESEND_API_KEY to be set on the Worker. Without it, the send is rejected with a clear error in non-localhost environments (codes log to the server console in local dev).