RepoGuardAI

Tool-independent repository auditing framework that guides any AI coding agent — Codex, Claude Code, Cursor, Gemini CLI, or another — through a repeatable, evidence-driven security and code audit.

RepoGuardAI inspects any software repository, runs whichever security and dependency scanners you already have installed plus its own deterministic scanners, and generates precise, evidence-driven instructions that drive a coding agent to review the code for bugs, security vulnerabilities, API security issues, missing rate limiting, dependency risk, configuration problems, and missing tests.

It is not tied to any AI provider. The deterministic work runs locally; the reasoning is delegated to whichever agent runs the generated instructions.

Why

Pointing an LLM at a whole repo and asking "find the bugs" is unreliable: it hallucinates findings, misses what tools would catch, and gives you different results every run. RepoGuardAI fixes that by splitting the work:

Deterministic tools do the objective checks (secrets, dependency hygiene, route inventory, config flags, headers, CVEs) — repeatable, no hallucination.
The AI agent does what tools can't: architecture, business logic, authorization, code flow, and validating or rejecting every lead with concrete file:line evidence.

The result is a consistent, auditable process regardless of which agent you run.

Design: deterministic first, AI second

Automated scanners  →  Collected evidence  →  AI code review  →  Finding validation  →  Final report

Every finding must carry code evidence (file:line). The in-house scanners never emit confirmed — they surface potential / manual-verification leads for the agent to prove or reject.

The pipeline

Discovery — languages, frameworks, package managers, API/test frameworks, databases, integrations, CI, Docker/infra, auth and config files, and a best-effort API route inventory. → discovery.json
Evidence — external scanners (when installed) + six in-house scanners, fused with the enriched API inventory. → evidence.json
Instructions — agent-specific playbooks assembled from the prompt library and YAML rule packs, injected with discovery + evidence context. → instructions/<agent>-instructions.md
AI review — the agent validates leads, finds what scanners miss, and writes findings.json.
Validation & report — deterministic threshold pass, then Markdown, JSON, and SARIF reports. → reports/audit-report.{md,json,sarif}

Features

🔌 Provider-neutral — works with Codex, Claude Code, Cursor, Gemini CLI, or any agent that can read files.
🧰 9 external scanners, availability-gated — gitleaks, semgrep, trivy, osv-scanner, npm/pnpm audit, pip-audit, govulncheck, cargo-audit. Never installed automatically; unavailable ones are skipped, not fatal.
🔎 6 in-house deterministic scanners — secrets, dependencies, routes, permissions, configuration, security-headers. Zero external dependencies.
📋 15 YAML rule packs across security, API, and quality.
🧭 API inventory with honest control detection (? when a control isn't visible — never a false claim).
🧱 Zod-validated artifacts + JSON Schema mirrors.
📄 Markdown + JSON + SARIF reports (upload SARIF to GitHub code scanning).
⏱️ Daily GitHub security — reusable Semgrep, OSV, Gitleaks, SARIF, issue, Dependabot, and CodeQL automation with least-privilege jobs.
🛡️ Read-only by default — never modifies the repo under audit.
✅ Strict TypeScript, 60 tests, CI on Node 18/20/22.

Requirements

Node.js ≥ 18
pnpm

External scanners are optional and detected at runtime — install any of them to add coverage: gitleaks · semgrep · trivy · osv-scanner · npm audit · pnpm audit · pip-audit · govulncheck · cargo-audit.

Install

git clone https://github.com/SUDARSHANCHAUDHARI/RepoGuardAI.git
cd RepoGuardAI
pnpm install
pnpm build
pnpm link --global   # optional: expose the `repoguardai` binary globally

Run without building during development:

pnpm dev -- discover ../some-repo   # tsx src/cli.ts discover ../some-repo

Quick start

# Full pipeline against a target repo
repoguardai audit /path/to/target-repo

# Point your agent at the generated instructions, e.g. open in Claude Code:
#   /path/to/target-repo/repoguard-results/instructions/claude-instructions.md
# The agent validates findings and writes repoguard-results/findings.json

# Then finalize:
repoguardai validate /path/to/target-repo
repoguardai report   /path/to/target-repo

Command reference

Command	Description
`repoguardai init [repo]`	Create the output workspace and a starter `repoguard.config.yaml`.
`repoguardai discover <repo>`	Detect stack, APIs, config; write `discovery.json`.
`repoguardai scan <repo> [--security] [--api]`	Run external + in-house scanners; write `evidence.json`.
`repoguardai instructions <repo> --agent <a>`	Generate instructions for `codex`, `claude`, `cursor`, `gemini`, or `generic`.
`repoguardai audit <repo> [--security] [--api]`	Full pipeline: discover → evidence → instructions → report.
`repoguardai validate [repo]`	Deterministic pass that reclassifies low-confidence potentials (< `minimumConfidence`).
`repoguardai report [repo]`	Rebuild `audit-report.{md,json,sarif}` from existing artifacts.
`repoguardai fix <finding-id> [repo]`	Generate a remediation plan for one finding (never edits code unless `mode.modifyFiles`).

Scope flags: --security limits a run to security + dependency + config checks; --api limits it to API-security + rate-limiting checks. Both override the audit.* toggles for that run only.

Examples

repoguardai init
repoguardai discover .
repoguardai scan . --security
repoguardai instructions . --agent codex
repoguardai audit ../my-api --api
repoguardai fix RG-AUTH-001 ../my-api

Batch / portfolio scripts

Helper scripts in scripts/ run RepoGuard across many repos at once. Point them at a directory that contains your repos (or category folders) via REPOGUARD_ROOT (defaults to the current directory):

# audit every repo under a directory, writing repoguard-results/ into each
REPOGUARD_ROOT=~/code ./scripts/portfolio-audit.sh

# safe, in-range dependency refresh (pnpm update + dedupe) + audit delta
REPOGUARD_ROOT=~/code ./scripts/dependency-sweep.sh --criticals

# AI deep-pass: have Claude Code validate seed findings into findings.json
#   (restricted to read + write-file tools, per-repo $ budget cap)
cd some-repo && ./scripts/claude-deep-pass.sh

These are optional convenience wrappers around the core repoguardai CLI.

Output layout

repoguard-results/
├── discovery.json                     # detected stack + raw API endpoints
├── evidence.json                      # external + in-house scanner output + API inventory + seed findings
├── findings.json                      # seeded from evidence; the agent overwrites this
├── scans/
│   ├── scan-report.json
│   └── <tool>.stdout.txt / <tool>.stderr.txt
├── instructions/
│   ├── codex-instructions.md
│   ├── claude-instructions.md
│   ├── cursor-instructions.md
│   ├── gemini-instructions.md
│   └── generic-instructions.md
├── reports/
│   ├── audit-report.md
│   ├── audit-report.json
│   └── audit-report.sarif
└── fixes/
    └── <finding-id>.md                # from `repoguardai fix`

Finding schema

Agents write repoguard-results/findings.json:

{
  "repository": "/path/to/target-repo",
  "generatedAt": "2026-07-12T00:00:00.000Z",
  "findings": [
    {
      "id": "RG-AUTH-001",
      "title": "Login endpoint has no rate limiting",
      "severity": "high",
      "category": "api-security",
      "status": "confirmed",
      "confidence": 95,
      "file": "src/routes/auth.ts",
      "line": 42,
      "endpoint": "POST /api/login",
      "description": "The login endpoint accepts unlimited authentication attempts.",
      "evidence": "No rate-limit middleware is applied to the route or router.",
      "impact": "An attacker can perform credential-stuffing or brute-force attacks.",
      "triggerCondition": "Repeated POST /api/login requests from one client.",
      "reproduction": ["Send repeated invalid logins", "Observe no throttling"],
      "recommendedFix": "Apply a distributed limiter keyed on account + client IP."
    }
  ]
}

Field	Values
`severity`	`critical` · `high` · `medium` · `low` · `informational`
`status`	`confirmed` · `potential` · `manual-verification` · `rejected`
`category`	`bug` · `security` · `api-security` · `authentication` · `authorization` · `rate-limiting` · `dependency` · `configuration` · `secrets` · `test-coverage` · `other`
`id`	`RG-<AREA>-<NNN>`, e.g. `RG-AUTH-001`

Validated with Zod (src/schemas.ts) and mirrored as JSON Schema in schemas/finding.schema.json. Invalid findings.json is ignored with a warning rather than corrupting the report.

Configuration

Optional repoguard.config.yaml in the target repo. All keys are optional; see repoguard.config.example.yaml and schemas/config.schema.json.

project:
  name: auto
  repository: .
audit:                    # per-area toggles
  bugs: true
  security: true
  apiSecurity: true
  rateLimiting: true
  dependencies: true
  configuration: true
  tests: true
mode:
  modifyFiles: false      # RepoGuard never edits files unless this is true
  validateFindings: true
  minimumConfidence: 75   # `validate` reclassifies potentials below this
exclude: [node_modules, dist, build, coverage, vendor, .git]
report:
  formats: [markdown, json, sarif]
  outputDirectory: repoguard-results
scanners:
  disabled: []            # e.g. [semgrep, trivy]
  timeoutMs: 120000
discovery:
  maxFiles: 200000
  maxEndpointScanFiles: 5000

What gets scanned

In-house scanners (scanners/, no external deps):

Scanner	Checks
`secrets`	Committed API keys, tokens, private keys (placeholder-aware).
`dependencies`	Floating versions (`*`/`latest`), missing lockfiles.
`routes`	API route inventory + sensitive endpoints lacking visible auth/limits.
`permissions`	Absence of any authorization/ownership checks across the code.
`configuration`	TLS verification off, wildcard CORS, debug mode, insecure cookies.
`security-headers`	Missing helmet / HTTP security headers in Node HTTP apps.

Rule packs (rules/), summarized into the agent instructions:

security/ — authentication, authorization, injection, secrets, file-upload, sensitive-data
api/ — rate-limiting (incl. bypass vectors), request-limits, pagination, cors, error-responses
quality/ — bugs, race-conditions, error-handling, test-coverage

Supported agents

codex · claude · cursor · gemini · generic. Each gets a tailored adapter (adapters/) plus the shared prompt library and rule packs.

Agent	Reads
Codex	`AGENTS.md`, `CODEX.md`, `repoguard-results/instructions/codex-instructions.md`
Claude Code	`CLAUDE.md`, `AGENTS.md`, `repoguard-results/instructions/claude-instructions.md`
Others	`repoguardai instructions <repo> --agent generic` → one combined prompt

CI / SARIF integration

audit-report.sarif is SARIF 2.1.0 — upload it to GitHub code scanning:

- run: npx repoguardai audit .
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: repoguard-results/reports/audit-report.sarif

This repo's own CI (.github/workflows/ci.yml) runs one Node 18 compatibility job with typecheck, tests, build, and committed-Action verification. Superseded runs on the same branch are cancelled.

Daily GitHub security

RepoGuardAI includes a packaged Node 24 Action and a reusable security workflow. It does not schedule scans of itself; target repositories choose their own schedule and triggers. The workflow runs target code with read-only permissions, preserves reports before applying --fail-on, and isolates SARIF/issue writes in trusted jobs. Dependabot opens reviewable dependency PRs; RepoGuardAI does not automatically merge them or rewrite application code.

See GitHub Security Automation for public/private callers, permissions, version pinning, troubleshooting, and the Website pilot.

Use as a GitHub Action

Add RepoGuardAI to any workflow to run a read-only audit and gate on severity:

name: RepoGuard audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SUDARSHANCHAUDHARI/RepoGuardAI@v0.1.0
        with:
          target: .          # repository path to scan (default: .)
          scope: security     # full | security | api (default: security)
          fail-on: high       # lowest severity that fails the job (default: high)

Outputs: report-directory, json-report, and sarif-report (SARIF 2.1.0, ready for github/codeql-action/upload-sarif). Pin to a released tag such as @v0.1.0. See GitHub Security Automation for permissions, private callers, and version pinning.

Repository layout

prompts/    reusable review steps (system-audit, bug, api-security, rate-limiting, …)
rules/      declarative YAML rule packs (security/, api/, quality/)
adapters/   per-agent operating instructions (codex, claude-code, cursor, gemini-cli, generic)
scanners/   in-house deterministic scanners + shared util
schemas/    JSON Schema mirrors of finding / audit / config
templates/  report, finding, and remediation-plan templates
src/        cli, discovery, scanner-runner, evidence-collector, agent-instructions,
            report-generator, schemas, types, config
tests/      vitest suites

Development

pnpm typecheck    # tsc --noEmit (strict)
pnpm test         # vitest run  (36 tests)
pnpm build        # tsup -> dist/

Extend the design without touching unrelated code:

External scanner → add to SCANNERS in src/scanner-runner.ts.
In-house scanner → add to INTERNAL_SCANNERS in scanners/index.ts.
Agent → add an adapter in adapters/ and wire ADAPTER_FILE in src/agent-instructions.ts.
Data shape → change the Zod schema in src/schemas.ts first, then the code.

Safety guarantees

Never modifies the repository under audit (read-only; fix writes a plan, not code, unless mode.modifyFiles is enabled).
Never installs scanners automatically.
Skips unavailable / disabled / non-applicable scanners without failing the run.
Excludes its own output directory from scanning (no self-pollution).
In-house scanners never emit confirmed — only validatable leads.
Instructions forbid claiming a vulnerability confirmed without code evidence and require separating Confirmed / Potential / Manual-verification / Rejected.

Limitations

Static analysis only; the target app is never executed.
API discovery and control detection are lexical scans of common Node patterns — other frameworks or dynamically-built routes may be missed, and a control is marked present only when visible on the route line (otherwise ? = verify).
Access-control, tenant-isolation, and business-logic depth depend on the driving agent.
A clean report does not certify a repository as secure — see SECURITY.md.

Roadmap

✅ Parse external scanner JSON (semgrep, gitleaks, npm/pnpm audit, osv-scanner, trivy) into structured seed findings.
✅ Packaged GitHub Action + --fail-on <severity> exit gate.
✅ Reusable security workflow, weekly Dependabot, and redacted issue synchronization.
Route extractors for Python / Go / Rust / Java frameworks (currently Node only).
Config-declared custom scanners without code changes.
Diff-only audit mode for pull requests.

Navigation Menu

Repository files navigation

RepoGuardAI

Table of contents

Why

Design: deterministic first, AI second

The pipeline

Features

Requirements

Install

Quick start

Command reference

Examples

Batch / portfolio scripts

Output layout

Finding schema

Configuration

What gets scanned

Supported agents

CI / SARIF integration

Daily GitHub security

Use as a GitHub Action

Repository layout

Development

Safety guarantees

Limitations

Roadmap

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
action-dist		action-dist
adapters		adapters
docs		docs
prompts		prompts
rules		rules
scanners		scanners
schemas		schemas
scripts		scripts
src		src
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CODEX.md		CODEX.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
repoguard.config.example.yaml		repoguard.config.example.yaml
repoguard.config.yaml		repoguard.config.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

RepoGuardAI

Table of contents

Why

Design: deterministic first, AI second

The pipeline

Features

Requirements

Install

Quick start

Command reference

Examples

Batch / portfolio scripts

Output layout

Finding schema

Configuration

What gets scanned

Supported agents

CI / SARIF integration

Daily GitHub security

Use as a GitHub Action

Repository layout

Development

Safety guarantees

Limitations

Roadmap

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages