Scanning
GitHub Scanning
Point VulnRadar at a repo you have connected instead of a live URL. It reads the repo's file tree over the GitHub API, runs the same pattern-based secret detectors the URL scanner uses, then sends the source through an AI code review for the flaws a regex never catches. You can push the findings straight back to the repo as a GitHub issue.
- Passes: secrets + AI review
- 2
- Files max per scan
- 300
- Repo content cap
- 5 MB
Overview
The GitHub scanner is a separate scanning mode from the live-URL scanner. Instead of fetching a website and inspecting its HTTP responses, it authenticates as your connected GitHub account, lists a repo's files, fetches the text ones, and reviews the source itself. Two passes run over that source: a deterministic secret scan that reuses the URL scanner's credential detectors verbatim, and an AI pass that reads whole files looking for injection, weak crypto, auth logic mistakes, and secrets the patterns missed.
The whole flow lives on /repos: connect an account, curate a working set of repos, scan one, read the findings, and file an issue. The sections below map each step to the endpoint behind it.
How a scan runs
POST /api/v3/scan/github runs the pipeline in order and short-circuits at the first gate that fails, so an oversized or empty repo is rejected before a single AI token is spent.
- Session check, then a per-user request throttle keyed on
scan-github:<userId>. Over the limit returns429. - Your decrypted GitHub token is loaded. No connection returns
400with “Connect your GitHub account first.” - A quota pre-check runs before any GitHub API call, so a request that has no review budget left never spends real GitHub API calls. Denied returns
403. - The repo's default branch and visibility are resolved, then its recursive file tree is fetched (a
refyou pass overrides the default branch). - The tree is filtered to scannable files and capped. An empty result returns
400. - A cheap token estimate from the tree's byte sizes is compared to the per-run ceiling. Too large returns
413before any file content is fetched. - File contents are fetched, the secret scan and AI review run, CVSS scores are attached, and the combined result is saved to history (private) and returned.
File selection
Filtering happens on tree metadata alone, before any content is fetched, so it is cheap enough to run as a gate. Directory segments like node_modules, vendor, dist, build, .next, target, and venv are skipped, as are binary-looking extensions (images, fonts, archives, compiled artifacts) and, deliberately, .lock and .map files. Anything not recognized as binary is fetched and only then size-checked, so an unusual-but-valid text extension is not silently dropped.
Three caps bound cost and abuse. They are runtime settings an admin can retune, shipped at:
| Cap | Constant | Default |
|---|---|---|
| Files per scan | CONFIG_GITHUB_REVIEW_MAX_FILES | 300 |
| Total content bytes | CONFIG_GITHUB_REVIEW_MAX_TOTAL_BYTES | 5,000,000 |
| Per-file bytes | CONFIG_GITHUB_REVIEW_MAX_FILE_BYTES | 300,000 |
When a cap cuts the list short, the scan still runs on what fit and the response reports filesSkippedByCaps: true.
Secret scanning
The secret pass runs every detector from the URL scanner's secrets-extended check set against each file's raw text. Those detectors already ignore the URL and headers and only read the body, so they run unmodified against source. Findings come back with confidence 70, detection method Source file pattern matching, and a location.file instead of a URL.
Line numbers are not populated on secret findings: the shared detectors return an evidence string, not a match position.
AI code review
The AI pass batches file contents (grouped by a character budget) and prompts a model to find new issues the pattern scan would miss: hardcoded secrets, injection (SQL, command, path traversal, XSS, SSRF), insecure cryptography, authentication/authorization logic flaws, and unsafe deserialization. The prompt tells the model this can be any kind of project, so it does not report missing HTTP headers or cookie flags that only make sense for a live web server.
Whether the repo is public or private is threaded into the prompt: a hardcoded secret in a public repo is treated as already compromised and needing rotation now, while the same secret in a private repo is a real risk that is not yet publicly disclosed. Findings come back with confidence 60, category code, and detection method AI code review, and only findings that name a file the scan actually sent are kept.
Connecting GitHub
GET /api/v3/account/github/connect starts an OAuth flow for an already-logged-in user. There is no sign-in variant: this always connects an account to an existing session. GitHub OAuth Apps allow only one registered callback URL, so this reuses the same callback the identity sign-in flow uses and disambiguates with a signed state bound to your user id.
OAuth scope
The connect flow requests the repo scope (read and write to public and private repositories). Classic GitHub OAuth Apps have no scope that grants read-only access to private repository contents, and public_repo would silently exclude private repos from listing and scanning entirely. The scan itself only ever reads. The one write the token is used for is filing an issue, and only when you explicitly ask for it.
Token storage
The access token is encrypted at rest with the same AES-256-GCM helper used for API keys and Discord tokens, stored in github_connections, and never returned by any endpoint. The status endpoint returns only your GitHub username, the granted scopes, timestamps, and your curated repo selection. Reconnecting rotates the token and re-records whatever scope GitHub actually granted. The server needs a GITHUB_CLIENT_ID configured, or connect returns 500.
Running a scan
On /repos, once connected, load your repositories and pick the set you want to keep visible. GET /api/v3/account/github/repos lists what the account can access, newest-updated first, up to 300 (three pages of 100). PUT to the same path saves your curated working set, which the status endpoint returns on the next load so the page has it without a second round trip.
To scan, send the repo in owner/repo form. ref is optional: leave it off to scan the default branch, or pass a branch name, tag, or commit SHA (GitHub resolves any of them).
curl -X POST https://your-instance/api/v3/scan/github \
-H "Content-Type: application/json" \
--cookie "session=..." \
-d '{"repoFullName":"octocat/hello-world","ref":"main"}'Credits and token budgets
The AI review pass costs real tokens, so it is metered per plan. The budget is measured in AI tokens, not a run count, because one large repo can burn as many tokens as hundreds of small ones. Usage resets on the same fixed 5-hour window as the rest of VulnRadar's AI features, and is tracked separately from AI chat and finding verification.
| Plan | Tokens per 5h window | Notes |
|---|---|---|
| Free | 0 | No standing budget, but a hidden free trial: one review every 24 hours so you can see the feature. |
| Core Supporter | 200,000 | Enough for a few small-to-medium repos per window. |
| Pro Supporter | 1,000,000 | Staff callers resolve to this cap. |
| Elite Supporter | 5,000,000 | Never unlimited: AI runs on subsidized provider capacity. |
Per-run ceiling
Independent of plan and of whose AI key is used, CONFIG_GITHUB_REVIEW_MAX_TOKENS_PER_RUN (default 300,000 estimated tokens) is a blunt guard against one run trying to push an enormous repo through the model. A repo whose estimated content exceeds it is rejected upfront with 413 rather than silently truncated.
Buying credits
When billing is on, a one-time top-up at /github-credits adds to a purchased balance that never expires and is spent only after the window allowance runs out. Credits and the plan window are separate balances with separate ledgers. Tiers:
| Price | Tokens | Tokens per dollar |
|---|---|---|
| $10 | 1,000,000 | 100,000 |
| $25 | 3,000,000 | 120,000 |
| $50 | 8,000,000 | 160,000 |
| $100 | 20,000,000 | 200,000 |
Filing findings as an issue
POST /api/v3/scan/github-issue pushes a scan's findings into a repo as a GitHub issue, using your connected token. It is owner-initiated only: you must own the scan (a teammate who can view it cannot file it), and you must have a GitHub connection. The scan referenced by scanId can be any scan you own, a URL scan as much as a repo scan, so this doubles as a way to open a tracked issue from any VulnRadar result.
What the issue contains
- Title:
[VulnRadar] Security findings for <host> (<count>). - A one-line summary, a severity breakdown (critical, high, medium, low, info), and the findings listed by severity, up to 50, each as
[SEVERITY] title. Beyond 50 it appends an “and N more” line. - A footer crediting the VulnRadar GitHub Scanner and linking the full report at
/host/<host>. - Labels
securityandvulnradar.
On success the response is the created issue's URL and number. If the token lacks write access or the repo has issues disabled, the call returns 502 with a message pointing at those two causes.
Privacy and limits
- Repo scans save private. A repo scan is written to history with
is_public = false, unlike a URL scan which defaults to public. Findings here can quote actual lines of private source, including the secrets the scan exists to find, so a share link is never one click away by default. - Separate history from URL scans.
GET /api/v3/scan/github/historyis its own list, excluded from the main history endpoint. With no query it returns the latest scan per repo plus a count; with?repo=owner/nameit returns that repo's timeline. Both respect your plan's retention window. - Token never exposed. The stored token is encrypted at rest and returned by no endpoint.
- GitHub calls target a fixed host. Every request goes to
api.github.com, never a user-supplied host, so these calls are not routed through the scanner's SSRF guard, which exists to stop a user pointing the scanner at an internal address.
API endpoints
Paths below drop the /api/v3 prefix. Every endpoint is session-authenticated; API keys are not accepted on any of them.
/scan/githubScan a repository
Runs the secret scan and AI code review against a connected repo's source. Session only.
Request Body
{
"repoFullName": "octocat/hello-world",
"ref": "main"
}Response 200 OK
{
"url": "octocat/hello-world",
"scannedAt": "2026-08-24T15:30:00.000Z",
"duration": 8421,
"summary": {
"critical": 0, "high": 1, "medium": 2, "low": 0, "info": 0, "total": 3
},
"findings": [ /* Vulnerability[] with location.file */ ],
"dangerScore": 34,
"engineConfidence": 78,
"scanHistoryId": 1234,
"ref": "main",
"filesScanned": 128,
"filesSkippedByCaps": false,
"aiTokensUsed": 41200,
"aiReviewSkipped": false
}Error Responses
/scan/github-issueFile findings as a GitHub issue
Opens an issue in a repo your connected account can write to, built from a scan you own. Owner-initiated only.
Request Body
{
"scanId": "aB3xY7",
"repo": "octocat/hello-world"
}Response 200 OK
{
"url": "https://github.com/octocat/hello-world/issues/42",
"number": 42
}Error Responses
Account and history endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /account/github | Connection status: username, granted scopes, timestamps, and selected repos. Never returns the token. |
| GET | /account/github/connect | Starts the OAuth connect flow and redirects to GitHub. Requires an existing session. |
| DELETE | /account/github | Disconnects the GitHub account. |
| GET | /account/github/repos | Lists repos the account can access, newest-updated first, up to 300. |
| PUT | /account/github/repos | Saves the curated working set of repo full names, replacing the previous selection (max 300). |
| GET | /scan/github/history | Repo scan history: latest per repo by default, or one repo's timeline with ?repo=owner/name. |