🇺🇸 English | 🇷🇺 Русский

repo-auditor

Objective GitHub repository audit: a compact terminal card and a full Markdown report. Four balanced categories (purpose · security · quality · maturity), transparent methodology, optionally powered by gitleaks, osv-scanner, tokei, semgrep.

Pure Python 3.12+, zero third-party dependencies. Networking via urllib with gh/curl fallback; TOML via tomllib.

👋 Not a programmer but want to check a project? Open GETTING_STARTED.ru.md (Russian) — a step-by-step guide in plain language, from installing Python to reading your first report.

What you'll see

After running, a card is printed to the terminal:

┌─ vercel/turbo ──────────────────────────────── Rust · MIT · ★30258
│ Purpose          ██████████  10/10
│ Security         ██████░░░░  6/10
│ Code Quality     ██████████  10/10
│ Maturity         ██████████  10/10
├─ TOTAL: 90/100 · ~ reliable
│ Key: 0 high + 5 medium security findings (heuristic)
│ Suggestion: review .devcontainer/Dockerfile, .github/workflows/turborepo-library-release.yml
└─ full report: data/github.com/vercel__turbo/runs/2026-04-25_071849/report.ru.md

At the same time, data/.../latest/ receives:

• report.ru.md — full Markdown report (8 sections, methodology, delta with previous run);
• report.json — versioned JSON (schema_version) for automation;
• card.txt — copy of the terminal card;
• raw/ — raw tool outputs for manual drill-down.

Note: Reports are generated in Russian by default. Use --language en for English output.

Quick start

# One-off audit — no installation needed
python3 -m repo_auditor https://github.com/pallets/flask

# View the full report
cat data/github.com/pallets__flask/latest/report.ru.md

That's enough to get your first result. External scanners (gitleaks, osv-scanner, tokei, semgrep) are optional — built-in heuristics work without them.

Installation

Base requirements: Python 3.12+ and git.

# Install from PyPI (recommended)
pip install sfild-repo-auditor

# Verify
repo-audit --version

Or install from source:

git clone https://github.com/SfilD/repo-auditor.git
cd repo-auditor
pip install -e .

Also works without pip install — invoke via python3 -m repo_auditor.

Docker (alternative to local install)

# Build image
 docker build -t repo-auditor .

# Run an audit
 docker run --rm -v $(pwd)/data:/data repo-auditor \
   https://github.com/pallets/flask --output-root /data

The image is based on python:3.13-slim (Debian 12 trixie-slim) and includes all external tools (gitleaks, osv-scanner, tokei, semgrep, gh). It is single-stage by design — prioritising simplicity and fast rebuilds for audit environments over minimal runtime size.

The container runs as a non-root user (uid 10001). Make the mounted output directory writable by that uid, e.g. mkdir -p data && chmod 777 data before the run, or chown 10001 data.

GitHub Actions

- uses: SfilD/repo-auditor@v1.8.0
  with:
    target: 'owner/repo'
    fail-below: '60'
    format: 'json'
    exclude: 'vendor/**,*.min.js'
    clone-depth: '1'

Action outputs: total, verdict, output-path.

External tools (optional but recommended)

The more you install, the more accurate the assessment.

Authentication for private repos and rate-limit removal:

gh auth login                       # interactive via browser
# or
export GITHUB_TOKEN=ghp_xxxxxxxx    # personal access token

Adapter prerequisites

v0.8.0 adds optional adapters that normalize external-tool signals into the report. They do not affect the four-category score in this release.

Token for Scorecard: any GitHub personal access token with public_repo scope (repo scope for private repositories). Export it as GITHUB_AUTH_TOKEN.

Both adapters are optional. If prerequisites are missing, the adapter returns UNAVAILABLE and the audit continues. Use --no-external-tools to disable all adapters.

MCP server

repo-auditor can run as an MCP (Model Context Protocol) server, exposing the audit pipeline to AI agents such as Claude Desktop, Claude Code, Cline, and Continue.

This is opt-in — the default CLI install has zero extra dependencies.

pip install 'sfild-repo-auditor[mcp]'

Launch the server:

repo-audit-mcp

Then wire it into your MCP client. See docs/mcp.md for full setup instructions, tool reference, resource reference (audit-evidence://, adapter-summary://, compare-history://), and trust-model notes.

Usage

repo-audit <target> [flags]

Target:

• owner/repo — short form
• https://github.com/owner/repo — repository
• https://github.com/owner — organization or user

Flags:

Exit codes:

• 0 — success
• 1 — clone/collection error
• 2 — invalid target / --gc without --keep-last
• 3 — organization URL with --org-mode off
• 4 — total below --fail-below (CI gate)
• 5 — no suitable repos in organization (all forks/archived)
• 6 — regression detected (--since)
• 8 — policy threshold breach (--fail-on); if both 4 and 8 trigger, 4 wins
• 16 — regression detected in compare mode (--regression-fail)

Repository configuration

repo-auditor looks for .repo-auditor.toml in the root of the cloned repository. It can contain scoring overrides and security suppression rules.

Security suppressions

You can suppress known-false-positive security findings with [[security.suppress]] tables:

[[security.suppress]]
tool = "gitleaks"
path_pattern = "tests/fixtures/*"
check_id_prefix = "generic-api-key"

Each rule matches when all specified fields match a finding. Fields act as wildcards when omitted:

• tool — scanner name (gitleaks, osv-scanner, semgrep)
• path_pattern — glob pattern against the file path
• check_id_prefix — prefix of the check/rule identifier

Trust boundary

.repo-auditor.toml inside the audited repository is repo-local config. When you audit a third-party repository you do not control, that config is untrusted — the repository could hide findings via local suppressions or override scoring.

For high-trust audits of third-party repositories, use --ignore-repo-config to skip loading .repo-auditor.toml from the cloned repository. This disables all repo-local config, including:

• scoring overrides;
• [[security.suppress]] rules;
• repo-local executable [[plugins]];
• [[scoring.plugins]] rules.

Repo-local executable plugins execute code and remain disabled by default unless --allow-repo-plugins is provided. --ignore-repo-config still wins even when --allow-repo-plugins is passed.

Trusted suppressions passed programmatically via AuditConfig.security_suppressions are always honored and remain separate from repo-local suppressions. Trusted CLI plugins from --plugin PATH are also always honored.

Plugin scoring documentation is in docs/plugins.md.

Where to find results

After a run, the report lives here:

data/github.com/<owner>__<repo>/latest/report.ru.md

Handy commands:

# Latest report
cat data/github.com/pallets__flask/latest/report.ru.md

# Just the JSON score section (for scripts)
jq '.score' data/github.com/pallets__flask/latest/report.json

# List all audited repos
jq '.entries[] | "\(.slug)\t\(.total)/100\t\(.verdict)"' data/index.json

# Open in editor
$EDITOR data/github.com/pallets__flask/latest/report.ru.md

Policy scoring (v0.9.0+)

v0.9.0 introduces optional policy profiles that map adapter evidence (OpenSSF Scorecard, GitHub Community Profile) into bounded per-category contributions. The default profile preserves backward compatibility; use --profile to opt in.

See docs/scoring.md for profiles, trust matrix, CI gating with --fail-on, and migration notes.

Cross-repo compare (v1.0+)

Compare two repositories side-by-side before adoption or track your own repository over time.

# Pairwise library evaluation
repo-audit pallets/click --compare-with pallets/flask

# Regression mode against latest stored run
repo-audit owner/repo --diff-previous --regression-fail

Compare produces a terminal card, Markdown report, JSON document, and SARIF export. Repo-local config is always ignored for trust; use --plugin <path> for explicit scoring rules.

See docs/compare.md for the full reference: trust boundary, storage layout, SARIF structure, schema evolution, and exit code 16.

Report viewer + import (v1.1+)

Offline viewer

Open docs/viewer/index.html in any browser. Drag-and-drop a report.json or compare.json to render the Russian 4-category card client-side. Zero build, zero CDN, no network.

Re-render saved reports

# Re-render a saved report as a card (no re-audit, no network)
repo-audit --import-report data/github.com/pallets__flask/latest/report.json --format card

# Re-render as Markdown
repo-audit --import-report data/github.com/pallets__flask/latest/report.json --format json

# Read from stdin
repo-audit --import-report - --format card < report.json

--import-report is schema-version aware and safe: it performs no clone, no adapter execution, and no pipeline instantiation.

Scoring explained

Categories (each 0..10)

Total = sum(categories) × 100 / 40. Red flag = any category ≤ 3.

Verdicts

Storage layout

data/
  github.com/
    <owner>__<repo>/
      repo/                       ← git clone; deleted after a successful audit unless --keep-clone
      runs/
        YYYY-MM-DD_HHMMSS/        ← UTC timestamp
          report.ru.md
          report.json
          card.txt
          raw/
            gitleaks.json
            osv-scanner.json
            tokei.json
      latest -> runs/<ts>
    <org>__org/
      runs/...
  index.json                      ← aggregate entry per slug

Retention

runs/ grow linearly — each run writes a new UTC directory. Cleanup:

• --keep-last N — after a successful audit, keep N latest runs, delete older ones.
• --gc --keep-last N — standalone pass over index.json: apply retention to all slugs at once (without a new audit).

Invariant: the target of the latest symlink is never deleted.

The clone (repo/) is deleted right after a successful audit: it weighs hundreds of MB against well under 1 MB of reports (django/django: 408 MB vs 660 KB), and reusing it saves only ~3.6 % on a re-audit. --keep-clone keeps it (then it is refreshed via git fetch on the next run); a failed audit always keeps it for post-mortem.

# Clean entire storage, keeping 3 latest runs per repo
repo-audit --gc --keep-last 3

Examples

# Basic audit
python3 -m repo_auditor https://github.com/pallets/flask

# Fast run without heavy external tools
python3 -m repo_auditor pallets/flask --quick

# Built-in heuristics only (no gitleaks/osv/tokei)
python3 -m repo_auditor pallets/flask --no-external-tools

# Primary repo of an organization
python3 -m repo_auditor https://github.com/amnezia-vpn

# Top-3 by stars in an organization
python3 -m repo_auditor https://github.com/amnezia-vpn \
    --org-mode multiple --org-limit 3

# JSON to stdout for pipelines
python3 -m repo_auditor pallets/flask --format json | jq '.score.total'

# SARIF for GitHub Advanced Security
python3 -m repo_auditor pallets/flask --format sarif --output-root ./sarif

# Exclude vendor and minified assets
python3 -m repo_auditor pallets/flask --exclude 'vendor/**' --exclude '*.min.js'

# CI gate: fail if total < 60
python3 -m repo_auditor pallets/flask --fail-below 60 || echo "Audit failed"

# With retention — keep only 5 latest runs
python3 -m repo_auditor pallets/flask --keep-last 5

Auditing large repositories

Repositories like torvalds/linux, chromium/chromium, or semgrep/semgrep can take a long time to clone and consume significant disk space.

# Example: audit a very large repo without downloading full history
python3 -m repo_auditor torvalds/linux --quick

# CI pipeline: minimal clone, fail gate
python3 -m repo_auditor owner/repo --clone-depth 1 --fail-below 60

Tip: semgrep/semgrep clones at ~170 MB. --quick brings it down to ~50 MB and cuts scan time by half because semgrep and osv-scanner are skipped.

Troubleshooting

gh: command not found or 403 rate-limit GitHub API without auth = 60 requests/hour. Install gh (gh auth login) or export GITHUB_TOKEN.

fatal: could not read Username for 'https://github.com' (private repo) Auth required. gh auth login or git config --global credential.helper store + GITHUB_TOKEN.

Score seems low for model-card / dataset repos The rubric is geared toward software projects. Repos without tests/, CI, pyproject.toml will score low on quality. This is by design.

tool unavailable for osv-scanner/tokei/gitleaks in JSON Scanner not installed — pipeline falls back to built-in heuristics. For full accuracy install the tools (see table above) or run with --no-external-tools to suppress warnings.

Clone hangs / consumes a lot of disk Use --quick (clone_depth=50). Large repos (100+ MB) can be audited without cloning via --no-external-tools + GitHub API only — but the card will be poorer (no file-walk findings).

Card breaks on CJK/emoji in owner/name Known limitation: alignment is character-based, not cell-width. Use --format json for machine-readable output without the visual card.

Want just the header without the full report --format json | jq '.score' or cat data/.../latest/card.txt.

Limitations

• Does not replace manual security review or CodeQL.
• Heuristic mode (without gitleaks) may produce rare false positives — e.g. on 12-character PowerShell cmdlets ('Get-Location' after pwd:).
• Without tokei, todo_density is approximated via source LOC from code_analysis — lower accuracy.
• Monorepo with nested manifests: each manifest is counted separately, no aggregation across "total" dependencies.
• HTML fallback for organization listing is not implemented — requires working gh or GitHub REST API.

See also

• README.ru.md — Russian version of this README.
• GETTING_STARTED.ru.md — step-by-step guide for non-programmers (Russian).
• AUDIT_GUIDE.md — for external auditors / AI tools before review (load-bearing constraints, hot zones, regression baseline).
• ARCHITECTURE.md — 30-second overview of layers and data flow.
• ROADMAP.md — public direction of development.
• SECURITY.md — disclosure policy.
• CHANGELOG.md — release history.
• CONTRIBUTING.md — dev cycle, conventional commits, stdlib-only rule.
• docs/compare.md — cross-repo compare reference.
• CLAUDE.md — architecture, data flow, scoring rules, false-positive filters (for contributors and Claude Code).
• LICENSE — MIT.