--- title: RepoGuard -- Repo Health & Security Scanner --- # RepoGuard -- Repo Health & Security Scanner ## What it is RepoGuard is an Omniscio plugin that scans repositories for security vulnerabilities, dependency issues, configuration problems, and code quality concerns. It produces a composite health score (0-100, letter grade A-F) from 7 scanner categories and generates actionable findings with fix suggestions. ## Where to find it ### How to Enable **Marketplace-only plugin (2026-05-28):** Install or uninstall via the Marketplace, same as PRD Stack and NightyTidy. There is no separate Settings → Features toggle — the Marketplace is the single control surface. When installed, the plugin adds a virtual project in the sidebar with a dashboard showing all your Omniscio projects and their health scores. ## How it behaves ### Scanner Categories RepoGuard runs 7 independent scanner agents. Each produces a score (0-100) and findings: | Category | Weight | What It Checks | Requires | | ------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | --------------- | | Security (SAST) | 25% | SQL injection, XSS, command injection, auth issues in security-relevant source files | Claude API | | Secrets Exposure | 20% | Hardcoded API keys, passwords, tokens, private keys (40+ regex patterns + Claude false-positive filtering) | Claude API | | Dependencies (SCA) | 15% | npm audit vulnerabilities, wildcard versions, missing lockfile | Network | | Code Quality | 10% | README quality, linting/formatting config, TypeScript strict, test setup, LICENSE | Claude API | | CI/CD & Config | 10% | CI pipeline existence, .gitignore completeness, hardcoded secrets in workflows, debug flags | -- | | Container Security | 10% | Dockerfile root user, latest tags, secrets in build args, docker-compose privileges | Optional Claude | | Runtime Health | 10% | Sentry unresolved issues, error trends, crash rates | Sentry API | **Scan types:** - **Quick Scan**: Secrets + Dependencies + Code Quality (fast, minimal API cost) - **Full Audit**: All 7 categories (comprehensive, uses Claude API) ### Scoring System Each category produces a score (0-100). The overall score is a weighted average of non-skipped categories (weights redistribute proportionally when categories are skipped). **Letter grades:** A (>=90), B (>=80), C (>=70), D (>=60), F (<60) **Remediation priorities** (severity x effort): - **Fix Now**: Critical/high severity, low effort - **Plan Fix**: Critical/high severity, high effort - **Improve**: Medium severity - **Nice to Have**: Low severity ### Dashboard The RepoGuard dashboard (visible when clicking the RepoGuard virtual project) shows: 1. **Fleet Health Card**: Average score across all scanned projects 2. **Ad-hoc Scan Bar**: Paste any GitHub URL to scan a public repo 3. **Projects Table**: All Omniscio projects with scores, grades, last scan time, trend arrows, and Quick/Full scan buttons ### Project Detail View Click any project row to see: - Hero section with score, grade, and project metadata - Category cards grid showing each scanner's score and finding count - Expandable findings list with severity badges, priority labels, and fix suggestions - Filter controls (by category and severity) - Export buttons (Markdown report copied to clipboard) - **Fix Issues** button (appears only when there are findings to fix) ### Fix Issues button (one-click remediation) When a project's most recent scan has at least one finding, the project detail view shows a blue **Fix Issues** button next to the export controls. Clicking it spawns a fresh Claude Code session in that project's folder, pre-loaded with the scan's full markdown report and a category-aware fix prompt — you don't have to copy/paste anything or open a session manually. What the launched session is told to do: 1. **Address every finding** — no triaging or skipping. Critical and High severity first, then the rest. The prompt explicitly says "nothing is out of scope" so Claude doesn't try to be conservative and quietly drop findings. 2. **Dependency vulnerabilities** — update affected packages to patched versions, run the package manager's audit fix command where applicable. 3. **Secrets exposure** — first run `gh repo view --json isPrivate -q .isPrivate` to check repo visibility: - If **private**: move secrets to env vars (`.env`), gitignore `.env`, update code to read from env, scrub git history via `git filter-repo` or BFG. The secrets themselves don't need rotating since the repo was never public. - If **public**: the secrets are already compromised. Do the same env-var migration AND flag every secret for immediate rotation so you can rotate them at the source. 4. **Code quality & hygiene** — add missing CI/CD, tests, linters, formatter configs, LICENSE, `.editorconfig`, package.json fields. Flagged as non-optional. 5. **Configuration & best practices** — apply security headers, dependency pinning, and any config-hardening suggestions. The session is launched via the plugin bridge's `amc.session.launchWithDraft({ projectId, draftText, autoSend: true })`. `autoSend: true` means the prompt is sent immediately when the session is ready — you don't have to click Send. A "Launching fix session…" toast confirms; on failure (rare — usually a transient scan-export error) a red "Failed to launch fix session" toast appears and nothing is launched. Implementation: [src/plugins/repoguard/ui/plugin.js](/src/plugins/repoguard/ui/plugin.js) — `fixIssues(projectId, scanId)` function at the bottom of the file. The scan-to-markdown render path goes through `amc.scan.exportReport(scanId, 'markdown')`, which uses [src/plugins/repoguard/report-generator.ts](/src/plugins/repoguard/report-generator.ts). The session-launch bridge is documented in the plugin SDK; the preload exposure is in [src/preload/plugin-bridge-preload.ts](/src/preload/plugin-bridge-preload.ts). ### Sentry Integration For runtime health monitoring, configure your Sentry auth token at Settings -> `sentryAuthToken`. Then link individual projects to their Sentry project in the project detail view. **Requirements:** Sentry free tier is sufficient. Needs an org-level bearer token with project:read scope. ### File Layout ``` src/plugins/repoguard/ manifest.json # Plugin registration types.ts # Shared types, scoring, weights scanner.ts # Orchestrator -- runs agents in parallel scanner-bridge.ts # IPC bridge -- storage + scan execution scan-storage-schema.ts # Self-heals scan tables from the bundled manifest (app-bundled backend owns its schema) repo-access.ts # File access abstraction (local + GitHub) claude-helper.ts # Anthropic SDK wrapper for agents sentry-client.ts # Sentry REST API client report-generator.ts # Markdown + JSON export agents/ sast-agent.ts # Security (SAST) secrets-agent.ts # Secrets Exposure sca-agent.ts # Dependencies (SCA) quality-agent.ts # Code Quality config-agent.ts # CI/CD & Config container-agent.ts # Container Security runtime-agent.ts # Runtime Health (Sentry) ui/ index.html # Plugin webview shell plugin.js # View routing + UI logic styles.css # Dark-theme CSS ``` ### API Cost Claude API calls are used by SAST, Secrets, Quality, and Container agents. A full audit of a medium-sized repo (~500 files) typically costs $0.02-0.10 in API tokens. Quick scans use no Claude API calls. Costs are tracked via Omniscio's standard API cost ledger (`trackApiCost`). ## For agents ### Code Entry Points - **Plugin bridge**: `src/main/ipc/plugin-bridge-handler.ts` routes `scan` namespace to `handleScanBridgeCall` - **Preload API**: `src/preload/plugin-bridge-preload.ts` exposes `amc.scan.*` methods - **Settings**: `sentryAuthToken` field on `AppSettings` in `src/shared/types.ts` ## Related RepoGuard has no sibling page of its own in the library. [INDEX.md](INDEX.md) is the library index, and it is the fastest way to reach the other Omniscio areas this page leans on — the Marketplace where the plugin is installed and toggled, and the sidebar project list whose repos it scans.