reposec - Defensive, read-only GitHub repo scanner that find

项目说明

RepoSec

> Find the security gaps in your public GitHub repo — before attackers do.

RepoSec is a defensi scanner that audits a public GitHub repository and returns a clear, prioritized security report. It checks for exposed .env files, missing .gitignore rules, hardcoded secret patterns in source and deployed Ja bundles, missing SECURITY.md and CODEOWNERS, weak CI, Dockerfile misconfigurations, dependency hygiene, and more.

The scanner ne the target repository and ne its data. It is a hygiene tool, not an offensive one.

<p align="left">
<a href=" alt="Live Demo" src=" /></a>
<a href=" alt="License: MIT" src=" /></a>
<a href=" alt="" src=" /></a>
<a href=" alt="npm package" src=" /></a>
<a href=" alt="Stars" src=" /></a>
<a href=" alt="Issues" src=" /></a>
<a href=" alt="PRs" src=" /></a>
<img alt="Language" src=" />
<img alt="Framework" src=" />
<img alt="React" src=" />
<img alt="Last commit" src=" />
</p>

> 🚀 Try the live demo → — paste any public GitHub URL and get a security report in seconds. No signup, no token required.

---

🧭 Quick Links

| Link | Description |
| --- | --- |
| 🌐 Live demo | Hosted scanner at reposec.zanesense.dev |
| 📦 npm package | Run the local CLI with npx reposec |
| 📦 Repository | Source code, issues, and releases |
| 🐛 Issue tracker | Report bugs and request features |
| 🔀 Pull requests | Open a PR to contribute |
| ⭐ Stargazers | See who starred the project |
| 📄 License | MIT terms |

---

🗂️ Table of Contents

📖 O

✨ Features

🧠 How It Works

📂 Repository Structure

🧰 Technologies

📋 Requirements

🛠️ Installation

- npm CLI
- Production build

⚙️ Configuration

🛠️ Usage

- Web UI
- Local CLI
- Programmatic API
- Screenshots

🧪 Testing

🔄 Project Flow

🔌 API Reference

- POST /api/scan

💡 Examples

- Try these public repositories
- What a finding looks like

🚀 Deployment

- (recommended)
- Docker
- Self-hosted Node

🗺️ Roadmap

🤝 Contributing

📝 Changelog

🛟 Troubleshooting

🔐 Security

📄 License

❤️ Acknowledgements

---

📖 O

Most repository leaks do not start with a sophisticated exploit. They start with a committed .env, a missing SECURITY.md, or a CI workflow with write-all permissions. RepoSec is a fast, opinionated linter for your repository's public surface: paste a GitHub URL, get a security score, a category-by-category pass/fail breakdown, se findings, and copy-pasteable fixes.

It is built for:

🧑‍💻 Maintainers who want a quick hygiene check before tagging a release.

🛡️ Security engineers who need a free, no-signup pre-audit for open-source projects.

📚 Educators and students who want to teach the basics of repo hardening with a li.

🤖 LLM-assisted workflows — every finding ships with a fix prompt you can paste into your editor agent.

Why a defensive tool? Because catching mistakes early is cheaper, friendlier, and more effective than chasing them after a leak. RepoSec is intentionally framed as a scanner, not an exploit kit.

---

✨ Features

🔍 12 static check modules co en, secrets, docs, scripts, GitHub features, container hygiene, community health, CI quality, repo metadata, source patterns, and dependencies.

🧠 55+ secret patterns out of the box, ported from the gitleaks ruleset: OpenAI, Anthropic (incl. admin), Groq, HuggingFace (user + org), Perplexity, Notion, GitHub (classic + fine-grained), GitLab, npm, PyPI, Slack (tokens + webhook URLs), Discord, Bedrock ABSK + secret keys), Azure AD, Alibaba, Heroku, Pulumi, Fly.io, New Relic, Dynatrace, Grafana Cloud, Databricks, HashiCorp Vault (service + batch), Terraform Cloud, EasyPost, ReadMe, Prefect, Sourcegraph, Microsoft Teams webhooks, private key blocks, SSH public keys, generic JWTs, database URLs, curl auth in shell commands, and generic credential assignments.

📊 Security score (0–100) with bands: _Excellent_, _Good_, _Fair_, _Weak_, _Critical_.

🗂️ Per-category breakdown showing exactly which checks passed, failed, warned, or were missing.

🧾 Se findings with masked e and a "Fix it like this" panel.

📥 One-click exports for:

- Markdown report
- JSON report
- SARIF report for GitHub Code Scanning
- SECURITY.md template
- .en template
- GitHub issue checklist
- LLM fix prompt

🌗 Polished UI with a RepoSec design system, light/dark theming, and accessible shadcn-style primitives.

🧪 Read-only by design — no writes, no auth, no database, no telemetry beyond the GitHub API.

🐢 No GitHub auth required for public repos. Optional token raises the rate limit to 5000 req/h.

New scanner capabilities

Full-repo secret file selection: RepoSec fetches likely secret-bearing files across the tree, including JS/TS, Python, en, shell scripts, Terraform, config files, keys, SQL, and source maps while skipping dependencies, build output, binary-hea, and o blobs.

Deployed bundle scanning: paste an optional deployed app URL and RepoSec fetches the public page, discovers Ja bundles and source maps, and scans the same assets users can inspect in Chrome De Sources. If the repo metadata has a homepage URL, the API attempts that scan automatically.

SARIF export: reports can be exported as SARIF for GitHub Code Scanning and compatible security dashboards.

Baseline suppression: re findings can be ignored with .reposecignore, reposec-baseline.json, or .reposec-baseline.json by matching finding id, fingerprint, file, file:line, or title.

Local CLI: scan private/local repos without uploading contents using npx reposec .; add --history to scan recent git history, --format sarif for CI output, and --color or --no-color to control terminal formatting.

Confidence and fingerprints: secret findings include confidence, fingerprint, and optional metadata. Raw secret stay ser and e remains masked.

Opt-in : supported GitHub, Stripe, and HuggingFace tokens can be live with the web checkbox, API : true, or CLI --.

---

🧠 How It Works

RepoSec is a ser Next.js application. The browser is a thin client; the real work happens in app/api/scan/route.ts.

Key design choices:

Ser fetching keeps the GitHub token (if any) out of the browser and avoids CORS surprises.

Static rule engine in lib/scanner.ts — easy to extend, deterministic, easy to test.

Bounded client-bundle scanning only fetches public HTTPS pages/assets, caps file sizes, and blocks private/internal hosts.

No persistence: a scan is a single request/response cycle. There is no database to leak.

---

🗂️ Repository Structure

RepoSec is distributed under the MIT License. See LICENSE for the full terms.

---

📦 Technologies

| Layer | Choice |
| ---------------- | ----------------------------------------------------------------------------------- |
| Framework | Next.js 16 (App Router) |
| Language | TypeScript 5 (strict mode) |
| UI runtime | React 19 |
| Styling | Tailwind CSS v4 + RepoSec design tokens |
| UI primitives | shadcn-style components, locally authored (no CLI dependency) |
| Icons | Lucide |
| Toasts | Sonner |
| Class utilities | clsx, tailwind-merge, class- |
| Animations | tw-animate-css |
| Data source | GitHub REST API + raw file downloads (no auth required) |
| regression| Playwright (screenshot capture script) |
| Linting | ESLint 9 + eslint-config-next (core-web- + typescript) |
| Type checking | tsc --noEmit |

---

✅ Requirements

Node.js ≥ 18.18 (Node 20 LTS recommended)

npm ≥ 9 (or any compatible package manager: pnpm, yarn, bun)

A modern browser (the UI uses CSS :has(), color-mix, and modern flex/grid)

Optional: a GitHub personal access token for higher rate limits

> No database, no Docker, no cloud account required for the MVP.

---

🚀 Installation

Open < and paste a public GitHub URL, e.g. .

npm CLI

Run RepoSec on any local checkout without installing the web app:

Production build

---

🔧 Configuration

RepoSec is configured entirely through en . There are no config files to edit and no database to pro.

| | Description | Required | Example |
| -------------- | ----------------------------------------------------------------------------------------------- | -------- | ------------- |
| GITHUB_TOKEN | Personal access token (classic or fine-grained, public repos only). Raises rate limit to 5000/h. | No | ghp_xxx... |

Create a local .en (or .env) from the template:

If you skip this step, the scanner still works — you just share the 60 req/h anonymous rate limit. Rate-limit hits surface as a friendly error in the UI, courtesy of the GitHubError model in lib/github.ts:54.

---

🛠️ Usage

Web UI

1. Run npm run dev and open <
2. Paste a public GitHub URL (or pick a sample repo).
3. Optionally paste a deployed app URL to scan production Ja bundles and source maps.
4. Optionally enable supported-token for GitHub, Stripe, and HuggingFace tokens.
5. Watch the per-stage loader (metadata → tree → files → deployed bundles → rules → score).
6. Explore the report tabs:
- O — score gauge, se counts, repo metadata, category breakdown.
- Findings — every finding as a card with masked e and a "Fix it like this" panel.
- Fixes — consolidated checklist.
- Checks — full per-check pass/fail/warn table.
- Files — file-grouped view of findings.
- Export — copy or download the artifacts.

Local CLI

Scan a local checkout without using the web UI:

Inside this repository, npm run scan:local -- . runs the same CLI from source.

Baseline files are honored in both web/API and local CLI scans:

Programmatic API

The scanner is exposed as a single POST endpoint:

Successful response:

Error responses use stable code : not_found, private, rate_limited, invalid, unknown.

Screenshots

Landing page

!RepoSec landing page

Scanning state

!RepoSec scan-in-progress loader

Report o

!RepoSec report o

Findings tab

!RepoSec findings tab

Export tab

!RepoSec export tab

To regenerate them: npm run screenshots (builds the app, serves it on port 4001, and captures each route with Playwright).

---

🧪 Testing

RepoSec ships with scanner regression tests, a deployed-bundle fixture test, screenshot-dri baselines, and a strict type/lint pipeline.

---

📊 Project Flow

End-to-end scan lifecycle:

---

📚 API Reference

POST /api/scan

a public GitHub URL, fetches repo data, runs the static scanner, and returns a ScanReport.

Request body

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| url | string | yes | Full public GitHub URL, e.g. . Trailing slashes and .git suffixes are tolerated. |
| siteUrl | string | no | Optional public deployed app URL. RepoSec fetches public JS bundles and source maps from this site and scans them for secrets. HTTPS is enforced outside tests. |
| | boolean | no | Opt in to supported li . Currently GitHub, Stripe, and HuggingFace are checked with bounded requests. Defaults to false. |

Response (200)

Where ScanReport is defined in lib/types.ts and includes repo, score, scoreBand, summary, findings, filesChecked, fileGroups, scannedAt, and durationMs. Secret findings may also include confidence, fingerprint, and metadata.

Error responses

| Status | code | Meaning |
| ------ | -------------- | ------------------------------------------------------------- |
| 400 | — | Invalid JSON body or unparseable URL. |
| 404 | not_found | The repository does not exist or is not public. |
| 502 | rate_limited | GitHub rate limit reached (anonymous or token). |
| 502 | private | The repository is private or access is restricted. |
| 500 | unknown | Unexpected ser. |

Example error body:

---

🧩 Examples

Try these public repositories

| Repository | Why scan it |
| ---------- | -------------------------------------------- |
| /next.js | Large, well-run project — should score in the _Good_ band. |
| facebook/react | Tests CI and metadata heuristics at scale. |
| expressjs/express | Classic Node.js project — interesting .gitignore and CI behavior. |

What a finding looks like

The scanner masks secrets to prefixsuffix before they e the server, so the UI ne the raw value.

---

🚢 Deployment

RepoSec is a standard Next.js 16 app. It works on any platform that supports the Node.js runtime.

(recommended)

Add GITHUB_TOKEN as an en in the project settings if you want a higher rate limit.

Docker

> TODO: A Dockerfile is not yet committed. The recommended shape is:
>
>

Self-hosted Node

The ser on port 3000 by default. O with PORT=4000 npm run start.

---

🧭 Roadmap

Planned and aspirational impro:

🧠 Optional LLM layer — "Bring Your Own Key" provider to add narrati to the report.

🧪 Unit tests — expand the current scanner regression suite into co for lib/scanner.ts, lib/rules.ts, and lib/scoring.ts.

🐳 Container hardening — committed Dockerfile and docker-compose.yml.

🌐 i18n — multi-language report exports.

🔌 GitHub App mode — comment the report on PRs via a public GitHub App.

📦 More ecosystems — Python (requirements.txt, pyproject.toml), Go (go.mod), Rust (Cargo.toml) lockfile and audit checks.

🪝 Webhooks — scheduled scans for the repos you watch.

🪪 License detection — extend SPDX detection beyond the GitHub API metadata.

🔐 More — add safe opt-in support for more pro without exposing raw secrets in reports.

> TODO: A separate ROADMAP.md is not currently checked in. The list above is the source of truth until it is.

---

🤝 Contributing

Contributions are very welcome — especially new secret patterns and new check modules.

1. Fork the repository on GitHub.
2. Clone your fork and create a feature branch:

3. Install dependencies and start the de:

4. Make your changes. When adding a new secret pattern, edit lib/rules.ts:10 and follow the existing SecretPattern shape.
5. Run the quality checks before committing:

6. Commit with a descripti:

7. Push your branch and open a pull request against main:

Please open an issue first if your change is large or design-related.

---

📝 Changelog

> TODO: A CHANGELOG.md is not yet committed. Notable milestones to seed it with:

0.1.0 — Initial M page, 12 check modules, 55+ secret patterns (ported from the gitleaks ruleset), score + band, exports (Markdown, JSON, SECURITY.md, .en, issue checklist, fix prompt), Playwright screenshot baseline.

0.2.0 — Full-tree secret target selection, deployed Ja bundle scanning, SARIF export, local CLI, git-history scanning, baseline suppression, confidence/fingerprint metadata, opt-in supported-token , and bundle scanner regression tests.

---

🐛 Troubleshooting

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| API rate limit exceeded on the first scan | Anonymous GitHub limit (60 req/h) was hit. | Add GITHUB_TOKEN to .en and restart the de. |
| Repository not found for a repo you can see in the browser | The URL is wrong, the repo is private, or it was renamed. | Double-check the URL. RepoSec only scans public repos. |
| Scan returns 0 findings and a perfect score | The repo is small or has no scannable files (yet). | Try a larger public repo, e.g. /next.js. |
| .en is missing after cp .en .en on Windows PowerShell | cp is not a nati. | Use Copy-Item .en .en instead. |
| npm run screenshots fails | Playwright browsers are not installed. | Run npx playwright install once before the first capture. |
| Deployed bundle scan finds no assets | The site URL is missing, not HTTPS, blocks ser requests, or does not expose JS bundles through normal script/modulepreload tags. | Enter the public production URL manually and confirm the bundles are reachable without authentication. |
| CLI SARIF output is empty | No findings matched after baseline suppression. | Run npx reposec . --format json and inspect summary.checks and filesChecked. |
| A re finding keeps returning | No baseline entry matches its id, fingerprint, file, or file:line. | Add the exact finding location or fingerprint to .reposecignore or reposec-baseline.json. |
| Build complains about a missing next-env.d.ts | The file is generated by Next.js on first run. | Run npm run dev once, or delete .next and rebuild. |
| Type errors after pulling new code | The incremental cache is stale. | Run npm run clean followed by npm run typecheck. |

---

🔒 Security

RepoSec is a defensive security tool. It is designed to help maintainers find their own mistakes, not to weaponize findings.

✅ The scanner is read-only. It ne to the target repository.

✅ The scanner is stateless. No scan data is stored on the server.

✅ The scanner masks secrets before they appear in the UI or exports.

✅ Li is opt-in and raw candidates are discarded before reports are returned.

✅ Deployed bundle scanning is bounded to public HTTPS assets and blocks private/internal hosts.

✅ The scanner is branded defensively — the copy and code avoid language like "hack", "exploit", "bypass", or "steal".

To report a in RepoSec itself, please open a private security ad on GitHub:

For supported and response timelines, see SECURITY.md.

Never commit real secrets to this repository. The included .gitignore already excludes .env* (with .en whitelisted as a template).

---

📄 License

RepoSec is licensed under the MIT License. See LICENSE for the full license text.

---

❤️ Acknowledgements

🛡️ Inspired by the public hardening checklists from GitHub, OWASP, and Snyk.

🎨 UI primiti from the shadcn/ui patterns, locally authored and customised.

🖼️ Icons by Lucide.

🔔 Toasts by Sonner.

🤖 Build tooling by Next.js, React, Tailwind CSS, and TypeScript.

🧪 baseline by Playwright.

💛 Thanks to every maintainer who takes repo hygiene seriously.

---

<p align="center">
<a href="#reposec">⬆️ Back to top</a>
&nbsp;·&nbsp;
<a href=" Live demo</a>
&nbsp;·&nbsp;
<a href=" Repository</a>
&nbsp;·&nbsp;
<a href=" Report a bug</a>
&nbsp;·&nbsp;
<a href=" MIT License</a>
</p>

项目信息

开发语言：TypeScript

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive, read-only GitHub repo scanner that finds secrets, exposed files, weak CI, missing security docs, Docker issues, and dependency risks.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。