https://github.com/superagent-ai/brin-github
A GitHub App that automatically scans pull requests for security threats and evaluates contributor trust profiles
https://github.com/superagent-ai/brin-github
agents contributor-security llm-security prompt-injection security
Last synced: 2 months ago
JSON representation
A GitHub App that automatically scans pull requests for security threats and evaluates contributor trust profiles
- Host: GitHub
- URL: https://github.com/superagent-ai/brin-github
- Owner: superagent-ai
- Created: 2026-04-03T06:19:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-15T06:32:20.000Z (3 months ago)
- Last Synced: 2026-04-15T08:25:25.357Z (3 months ago)
- Topics: agents, contributor-security, llm-security, prompt-injection, security
- Language: TypeScript
- Homepage: https://brin.sh
- Size: 61.5 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Brin GitHub App
A GitHub App that automatically scans pull requests for security threats and evaluates contributor trust profiles using the [Brin](https://brin.sh) API.
## What it does
When installed on a repository, the app reacts to pull request events and runs two parallel checks:
**PR Security Scan** -- Analyzes the PR diff for security threats (credential leaks, obfuscated payloads, dependency attacks, etc.) and reports a score from 0-100 with a verdict.
**Contributor Trust Check** -- Evaluates the PR author's GitHub profile across identity, behavior, content, and social graph dimensions to flag accounts that warrant additional review.
Results are surfaced as:
- **Check runs** on the PR commit (pass/fail/neutral) that integrate with branch protection rules
- **PR comments** with detailed findings and dimension breakdowns
- **Labels** (`pr:verified`, `pr:flagged`, `contributor:verified`, `contributor:flagged`)
### Verdict flow
| Verdict | Check run | Label | Comment | Blocks merge |
| ---------------------- | --------- | -------------------------------------- | ------- | ------------ |
| clean / safe | success | `pr:verified` / `contributor:verified` | removed | no |
| suspicious / caution | neutral | `pr:flagged` / `contributor:flagged` | posted | no |
| dangerous / score < 30 | failure | `pr:flagged` / `contributor:flagged` | posted | yes |
| pending deep scan | neutral | -- | -- | no |
## Setup
### 1. Register a GitHub App
Create a new GitHub App at `https://github.com/settings/apps/new` with these settings:
**Permissions:**
- Checks: Read & Write
- Pull requests: Read & Write
- Issues: Read & Write (for PR comments)
- Contents: Read (for `.github/brin.yml` config)
- Metadata: Read
**Webhook events:**
- Pull request
- Check run
- Check suite
- Installation
Set the webhook URL to `https:///api/github/webhook`.
### 2. Configure environment
Copy `.env.example` to `.env` and fill in:
```
APP_ID=
PRIVATE_KEY=
WEBHOOK_SECRET=
```
### 3. Install dependencies and run
```bash
npm install
npm run dev # development with hot reload
npm run build # compile TypeScript
npm start # run compiled output
```
The server starts on port 3000 by default (override with `PORT` env var).
### 4. Install the app on repositories
Go to your app's installation page and install it on the repositories you want to protect.
## Repo configuration
Repositories can optionally add a `.github/brin.yml` file to customize behavior:
```yaml
prScan:
enabled: true
blockBelowScore: 30
suspiciousVerdicts: [suspicious]
tolerance: conservative
contributorTrust:
enabled: true
safeVerdicts: [safe]
trustedAuthors: [dependabot[bot], renovate[bot]]
comments:
mode: detailed # or "minimal"
```
All fields are optional. Missing fields fall back to the defaults shown above.
## Architecture
```
src/
├── index.ts # Hono server, webhook route, health check
├── app.ts # GitHub App instance (octokit)
├── events/
│ ├── index.ts # Event handler registration
│ ├── pullRequest.ts # pull_request event handler
│ ├── checkRun.ts # check_run.rerequested handler
│ └── installation.ts # installation.created handler
├── services/
│ ├── prScan.ts # PR scan orchestration
│ ├── contributorTrust.ts # Contributor trust orchestration
│ ├── checkRuns.ts # GitHub Check Runs API wrapper
│ ├── comments.ts # Marker-based comment management + rendering
│ ├── labels.ts # Label ensure/set logic
│ └── config.ts # .github/brin.yml loader
└── lib/
├── env.ts # Environment variable validation
├── logger.ts # Structured logging (pino)
├── types.ts # Shared types, constants, label/marker defs
├── brinApi.ts # Brin API HTTP client
└── policy.ts # Verdict evaluation and threshold logic
```
## Re-running checks
Maintainers can re-run any Brin check from the GitHub UI by clicking "Re-run" on the check run. The app handles `check_run.rerequested` events and re-executes the corresponding scan.
## Development
```bash
npm run dev # start with tsx watch (hot reload)
npm run typecheck # type-check without emitting
npm run build # compile to dist/
```
For local webhook testing, use a tunnel like [smee.io](https://smee.io) or [ngrok](https://ngrok.com) to forward GitHub webhooks to `localhost:3000/api/github/webhook`.