quaid-scanner

Agent-first OSS repository health scanner for measuring sociotechnical health — not just code quality. Evaluates any open source project across six strategic pillars: security posture, governance soundness, community sustainability, AI-native readiness, inclusive language, and technical rigor. Returns structured findings designed for agents, CI pipelines, and humans alike.

Built on OpenSSF Scorecard, CHAOSS metrics, The Open Source Way 2.0, and the Inclusive Naming Initiative.

Who This Is For

OSPO and foundation teams evaluating the health of a dependency portfolio, an incubation candidate, or a grant recipient — and need a consistent, framework-grounded signal rather than a gut-check on GitHub stars and commit frequency.

Foundation and governance managers assessing whether a project meets incubation criteria, has sound governance, and is sustainable without a single-vendor dependency.

Developers building agent workflows over OSS repos — scan-to-backlog pipelines, pre-adoption dependency audits, CI health gates — who need machine-parseable structured output, not a PDF report.

Prerequisites

| Requirement | Version | Notes | | --- | --- | --- | | Node.js | ≥ 18.0.0 | Required | | Git | any | Required for local repo scanning | | GitHub token | — | Optional — unlocks branch protection checks, OpenSSF Scorecard API, and issue/PR metrics | | ZeroLocal (GitHub) | local instance | Optional — required for scan history, trend tracking, and OSS social graph. Open source; cloud with free tier also available. |

GitHub token: set either GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN in your environment. A classic token with public_repo scope is sufficient for public repos. The token is never written to disk.

ZeroLocal: set ZERODB_API_URL (defaults to http://localhost:8100), ZERODB_API_KEY, and ZERODB_PROJECT_ID. Without ZeroLocal, scanning and reporting work normally — persistence and graph features are silently skipped.

Install

npm install -g quaid-scanner

Or run without installing:

npx quaid-scanner . --depth quick

Quick Start

# Scan the current directory
quaid-scanner .

# Scan a GitHub repository (public or private)
GITHUB_TOKEN=ghp_xxxx quaid-scanner https://github.com/owner/repo

# GITHUB_PERSONAL_ACCESS_TOKEN is also accepted as a fallback
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx quaid-scanner https://github.com/owner/repo

# Scan with markdown output to file
quaid-scanner . --format markdown --output report.md

# Scan with a minimum score threshold (exits 2 if score < 6.0)
quaid-scanner . --threshold 6.0

# Include ecosystem intelligence (rivals, partners, strategy)
quaid-scanner . --ecosystem

# Full thorough scan with everything
quaid-scanner . --depth thorough --ecosystem --format markdown --output full-report.md

Using a .env file? Variables must be exported to reach the scanner process:

set -a; source .env; set +a
quaid-scanner https://github.com/owner/repo --depth quick

What It Scans

43 scanners across six weighted pillars:

| Pillar | Weight | What it measures | |--------|--------|-----------------| | Security | 25% | Binary artifacts, branch protection, dependency pinning, token permissions, OpenSSF Scorecard | | Governance | 20% | License detection/validation/compatibility, bus factor, vendor neutrality, asset protection | | Community | 15% | Contributor funnel, burnout signals, response time, psychological safety, funding, support channels | | AI Readiness | 15% | Model cards, agentic rules (Claude/Cursor/Windsurf), dataset provenance, multi-model detection | | Inclusive Language | 15% | INI term scanning in source, docs, and naming; diminishing and assumed-knowledge language | | Technical Rigor | 10% | Linter config, test coverage, SemVer/release cadence, interaction templates |

CLI Reference

quaid-scanner [target] [options]

Arguments:
  target                  Local path or GitHub URL (default: current directory)

Options:
  --depth <level>         quick (~5s), standard (~15s), thorough (~60s)  [default: standard]
  --format <type>         json or markdown  [default: json]
  --output <file>         Write output to file instead of stdout
  --config <file>         Path to .quaid-scanner.yaml config file
  --threshold <score>     Minimum acceptable score (0–10); exit 2 if below
  --maturity <level>      sandbox | incubating | graduated | archived | auto  [default: auto]
  --ecosystem             Run ecosystem intelligence (rivals, partners, communities, strategy)
  --ecosystem-depth       static | assisted  [default: static]
  --quiet                 Suppress progress output (clean stdout for piping)
  --verbose               Show per-scanner progress
  -h, --help              Show help
  -V, --version           Show version

Exit Codes

| Code | Meaning | |------|---------| | 0 | Score ≥ 8.0 — Low Risk | | 1 | Score 5.0–7.9 — Medium Risk | | 2 | Score < 5.0 — High/Critical Risk, or --threshold not met |

Maturity Scoring

A sandbox project that hasn't written down its governance yet is not failing — it is behaving normally for its stage. quaid-scanner adjusts severity thresholds by maturity level so findings reflect where a project should be, not where a graduated Apache project is.

| Maturity Level | What it means | Auto-detected when | |---|---|---| | sandbox | Early-stage, experimental | < 10 contributors, < 6 months old, or no releases | | incubating | Growing, not yet stable | 10–50 contributors, < 2 years, pre-1.0 releases | | graduated | Stable, production-grade | Semantic versioning, sustained contributor base, governance docs present | | archived | Frozen, read-only | No commits in 12+ months |

Auto-detection reads git history, package.json metadata, and contributor data. To override:

# Treat a young project as incubating (relaxes governance expectations)
quaid-scanner . --maturity incubating

# Full strictness regardless of age
quaid-scanner . --maturity graduated

At sandbox maturity, missing governance documents produce WARNING findings rather than CRITICAL. At graduated, the same gaps are CRITICAL. The maturity level used is included in every JSON report as "maturity": "incubating".

Example Output

{
  "repo": "owner/my-project",
  "overallScore": 7.2,
  "riskLevel": "MEDIUM",
  "maturity": "incubating",
  "pillars": {
    "security": { "score": 6.1, "weight": 0.25 },
    "governance": { "score": 8.4, "weight": 0.20 },
    "community": { "score": 7.8, "weight": 0.15 },
    "ai_readiness": { "score": 5.5, "weight": 0.15 },
    "inclusive": { "score": 9.0, "weight": 0.15 },
    "technical": { "score": 7.0, "weight": 0.10 }
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "pillar": "security",
      "category": "dep-pinning-packages",
      "message": "package-lock.json absent — dependencies not pinned",
      "suggestion": "Run npm install to generate a lock file and commit it",
      "dataSource": "local",
      "referenceUrl": "https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies"
    }
  ],
  "recommendations": [
    { "priority": 1, "action": "Add package-lock.json to version control", "impact": "high", "effort": "low" }
  ]
}

Severity values are always human-readable strings: "PASS", "INFO", "WARNING", "CRITICAL".

Every finding carries dataSource ("api" / "local" / "heuristic") and referenceUrl linking to the authoritative source or spec. In markdown output, critical findings show the triggering context as a code snippet, and the report ends with a Score Rationale table explaining the weighted pillar calculation.

Suppressing False Positives

Place a .quaid-scanner-ignore file at the root of any scanned repository to exclude paths from inclusive language scanning. Uses .gitignore conventions — one glob pattern per line, # for comments:

# Exclude generated files
coverage/
dist/

# Test fixtures that deliberately contain flagged terms
tests/fixtures/term-corpus/**

# Third-party reference documents
docs/vendor-spec.md

This file is read at scan time from the target repo root. Absence is graceful — the scanner skips it silently and applies its built-in defaults (node_modules/, vendor/, .git/, dist/, build/).

Configuration

CLI flags cover the most common options directly:

quaid-scanner . --depth thorough --threshold 7.0 --maturity incubating

A .quaid-scanner.yaml config file is on the roadmap. Until then, all options are set via CLI flags — see CLI Reference above.

Full options: docs/usage/configuration.md

Agentic Use

quaid-scanner is designed agent-first. JSON output is the primary interface; markdown is secondary. The full value of the tool emerges when an agent drives the complete workflow end-to-end.

Claude Code Skill

If you use Claude Code, the /quaid-scan skill is included:

/quaid-scan .
/quaid-scan https://github.com/owner/repo --depth thorough
/quaid-scan . --ecosystem

The skill interprets findings, explains severity, and suggests next steps in plain language.

MCP Server

Add to your .mcp.json to expose scan_repository and graph_query as agent tools:

{
  "mcpServers": {
    "quaid-scanner": {
      "command": "npx",
      "args": ["quaid-scanner/dist/mcp.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "quaid-scanner": {
      "command": "node",
      "args": ["/path/to/node_modules/quaid-scanner/dist/mcp.js"]
    }
  }
}

MCP tools exposed:

| Tool | What it does | |------|-------------| | scan_repository | Full health scan — returns ScanReport JSON | | graph_query | Query the OSS social graph for a repo (requires ZeroDB) |

Prompt Patterns

Before adopting a dependency:

Scan https://github.com/owner/repo with quaid-scanner at standard depth.
Summarize the top 3 risks and whether I should depend on this project.

Before a release:

Run quaid-scanner on the current directory at thorough depth with --threshold 7.0.
Block the release if exit code is 2. For any CRITICAL findings, open GitHub issues.

Portfolio audit:

Scan these 5 repos with quaid-scanner --depth quick --format json --quiet,
sort by overallScore ascending, and summarize the bottom 2 for remediation.

Ecosystem positioning:

Run quaid-scanner . --ecosystem --format json.
From the ecosystem section, identify the top 3 rivals and suggest one
differentiation message for each based on our pillar scores.

Agent-Friendly Flags

# Silent JSON — ideal for piping into jq or agent parsers
quaid-scanner . --quiet --format json

# Capture to variable in bash
REPORT=$(quaid-scanner . --quiet --format json)
SCORE=$(echo "$REPORT" | jq '.overallScore')

# Write to file then read (avoids stdout buffering on large repos)
quaid-scanner . --quiet --format json --output /tmp/scan.json

Full agentic patterns: docs/usage/agentic-usage.md

Portfolio Scanning

The recommended agent workflow for auditing an organization's OSS portfolio:

1 — Scan all repos in parallel

# Scan every repo in an org
for repo in repo-a repo-b repo-c; do
  quaid-scanner "https://github.com/org/${repo}" \
    --depth quick --format json --quiet \
    --output "/tmp/scan-${repo}.json" &
done
wait

2 — Fill the report template

Open docs/scans/portfolio-report-template.md. Each section contains inline agent instructions (as HTML comments) explaining exactly how to populate it from the scan JSON files:

• Executive summary with cross-portfolio patterns
• Score table (all repos, all pillars)
• Per-repo analysis with pillar bars, grouped findings, and recommendations
• Backlog appendix with user stories derived from findings

The template includes a Common Story Templates bank that maps finding categories (e.g. vendor-neutrality, openssf-scorecard, dependency-pinning) to pre-written As a [role], I want … so that … stories — copy rather than compose.

3 — Turn stories into issues

Read the backlog appendix from the portfolio report.
For each user story, open a GitHub issue in the relevant repo
with the story as the description and the finding category as a label.

Example portfolio prompt (all-in-one)

Scan all public repos in the org https://github.com/my-org using
quaid-scanner --depth quick --format json --quiet, one scan per repo in parallel.
Then fill docs/scans/portfolio-report-template.md from the scan results,
following the agent instructions in each section.
Save the completed report to docs/scans/my-org-report-YYYY-MM-DD.md.

Persistence & History

Requires ZeroLocal (GitHub) — open source, runs locally. A cloud option with a free tier is also available. Set ZERODB_API_URL, ZERODB_API_KEY, and ZERODB_PROJECT_ID.

Each scan result can be stored for trend analysis and regression detection. Over time, you can answer: Is this project's security posture improving or declining?

# Store results automatically — set env vars before scanning
export ZERODB_API_URL=http://localhost:8100   # ZeroLocal default
export ZERODB_API_KEY=your-key
export ZERODB_PROJECT_ID=your-project-id

quaid-scanner https://github.com/owner/repo --quiet --format json
# scan result is stored automatically when ZeroLocal vars are present

Library usage:

import { storeScanHistory, queryTrend, renderTrendAscii, alertOnDrop, ZeroDBClient } from 'quaid-scanner';

const client = new ZeroDBClient({ baseUrl: 'http://localhost:8100', apiKey: 'your-key', projectId: 'your-project-id' });

// Store after a scan
await storeScanHistory(report, client);

// Retrieve 90-day trend
const trend = await queryTrend('owner/repo', 90, client);

// Render as ASCII sparkline
console.log(renderTrendAscii(trend));
// owner/repo (90d): ▃▄▅▆▇▇█  5.2 → 8.1 (+2.9)

// Alert if score drops > 1.0 point from previous scan
const alert = alertOnDrop(trend);
if (alert) console.error(alert);

Use alertOnDrop in CI to catch score regressions before they merge:

- name: Check for score regression
  run: |
    node -e "
      const { alertOnDrop } = require('quaid-scanner');
      // ... query trend and alert
    "

Ecosystem Intelligence

The --ecosystem flag runs a parallel analysis that does not affect overallScore:

quaid-scanner . --ecosystem --format json | jq '.ecosystem'

Returns:

• profile — detected domain, foundations, standards, topics
• rivals — competing projects with similarity scores
• partners — integration/dependency relationships
• userCommunities — forums, Slack, Discord, conferences to engage
• recommendations — ranked strategic actions (join a foundation, adopt a standard, etc.)
• dataSource — static | zerodb-assisted | zerodb-full

OSS Social Graph

Requires ZeroLocal (ZERODB_API_URL, ZERODB_API_KEY, ZERODB_PROJECT_ID).

Each scan registers the scanned repo as a graph node in ZeroLocal. After scanning related projects, the graph captures the sociotechnical relationships between them — who contributes to what, which projects depend on each other, which orgs concentrate influence.

Node types: contributor, project, organization

Edge types: commits_to, maintains, depends_on, related_to, forks

CollaborationSpectrum score: a per-repo composite that measures cross-org contributor diversity and depth of collaboration network. Higher scores indicate a healthier contributor ecosystem with less single-vendor lock-in.

After scanning a portfolio, the graph enables:

# Who depends on this repo?
quaid-scanner . --format json | jq '.graph.reverseDependents'

# Discovery feed — what adjacent repos should you know about?
quaid-scanner . --format json | jq '.graph.discoveryFeed'

# CollaborationSpectrum score for this repo
quaid-scanner . --format json | jq '.graph.collaborationScore'

Via the MCP graph_query tool:

# Traverse 2 hops of dependency relationships from a repo
graph_query(repo: "owner/my-project", hops: 2, edgeTypes: ["depends_on"])

# Find all contributors shared across two repos
graph_query(repo: "owner/my-project", hops: 1, edgeTypes: ["commits_to"], intersect: "owner/other-project")

The graph builds incrementally — each scan adds or updates nodes and edges. No data is required upfront; the graph becomes useful after scanning 5–10 related repos.

CI/CD Integration

# GitHub Actions
- name: OSS Health Check
  run: |
    npx quaid-scanner . --depth standard --threshold 5.0 --format json --output scan-report.json
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Upload scan report
  uses: actions/upload-artifact@v4
  with:
    name: quaid-scan-report
    path: scan-report.json

Using as a Library

npm install quaid-scanner

import {
  Orchestrator,
  createDefaultRegistry,
  buildContext,
  buildScanReport,
  serializeJson,
  Severity,
  Pillar,
} from 'quaid-scanner';

const registry = createDefaultRegistry();
const orchestrator = new Orchestrator(registry);

const { context, cleanup } = await buildContext({
  target: 'https://github.com/owner/repo',
  githubToken: process.env.GITHUB_TOKEN,
  depth: 'standard',
});

try {
  const results = await orchestrator.runAll(context);
  const report = buildScanReport(context, results);

  // Agent-friendly JSON with string severity labels ("CRITICAL", not 2)
  const json = serializeJson(report);
  console.log(json);

  // Filter CRITICAL findings from the security pillar
  const criticalSecurity = report.findings.filter(
    f => f.severity === Severity.CRITICAL && f.pillar === Pillar.SECURITY
  );
} finally {
  await cleanup();
}

All exported types: ScanReport, ScanFinding, ScanContext, Severity, Pillar, MaturityLevel, RiskLevel, ScanDepth, OutputFormat, and more — see src/index.ts.

Development

git clone https://github.com/quaid/quaid-scanner.git
cd quaid-scanner
npm install
npm run build
npm test
npm run test:coverage

Adding a scanner: See docs/usage/scanners.md for the plugin interface. All scanners implement Scanner from src/types/index.ts.

Project Health

quaid-scanner scans itself. Current score as of v0.1.2:

| Pillar | Score | Weight | Weighted | |--------|-------|--------|---------| | Security & Supply Chain | 3.5/10 | 25% | 0.88 | | Governance & Legal | 3.0/10 | 20% | 0.60 | | Community Health | 4.0/10 | 15% | 0.60 | | AI-Native & Agentic Readiness | 8.0/10 | 15% | 1.20 | | Inclusive Language | 0.0/10 | 15% | 0.00 | | Technical Rigor | 8.5/10 | 10% | 0.85 | | Overall | 4.1/10 | | |

The score is honest. A solo-maintainer project at v0.1.x will have real gaps:

Open findings being tracked:

| Finding | Severity | Issue | |---------|----------|-------| | GitHub Actions not pinned to commit SHAs | WARNING | #123 | | diminishing-scanner doesn't respect .quaid-scanner-ignore (inflating inclusive score) | Bug | #122 | | OpenSSF Scorecard not yet indexed (new project) | WARNING | — | | Bus factor: 1 (solo maintainer) | WARNING | contribute | | Contributor funnel: 0% conversion (new project) | WARNING | contribute |

Known false positives being tracked:

| Finding | Reason | Issue | |---------|--------|-------| | Inclusive CRITICAL: "master" in dep-pinning-docker.ts | Detection target string, not usage | #124 | | Welcoming score 0/100 | diminishing-scanner ignores the ignore file — see #122 | #122 |

The AI readiness (8.0) and technical rigor (8.5) scores reflect the tool's strengths: MCP server, Claude Code skill, dataset provenance scanner, 80%+ test coverage. The security and governance scores reflect real gaps that contributions and time will close.

Documentation

| Doc | Contents | |-----|---------| | Getting Started | Installation, first scan, scan depth | | Scanner Reference | All 43 scanners with thresholds and remediation | | Agentic Usage | Prompt patterns, agent workflows, MCP setup | | Configuration | .quaid-scanner.yaml full reference | | Examples | CI/CD, portfolio scanning, security audits | | Portfolio Report Template | Agent-fillable template for org-wide health reports |

License

Apache-2.0 — Karsten Wade