@agentbadge/scanner

@agentbadge/scanner

Agent Readiness Scanner — scans websites for AI agent readiness resources, scores them across 4 pillars, and produces signed integrity reports.

Install

npm install @agentbadge/scanner
# or
bun add @agentbadge/scanner
# or
yarn add @agentbadge/scanner

CLI Usage

scan

Scan a URL for agent readiness and produce a signed report.

# Basic scan
agentbadge-scan scan https://agentbadge.xyz/

# Force refetch all resources
agentbadge-scan scan https://agentbadge.xyz/ --no-cache

# Output as JSON only
agentbadge-scan scan https://agentbadge.xyz/ --json

# Output format: pretty (default), table, all, json
agentbadge-scan scan https://agentbadge.xyz/ --format table

# Custom report output path
agentbadge-scan scan https://agentbadge.xyz/ --output ./my-report.json

# Skip Ed25519 signing (dev mode)
agentbadge-scan scan https://agentbadge.xyz/ --skip-sign

# Enable anonymous telemetry (opt-in)
agentbadge-scan scan https://agentbadge.xyz/ --telemetry

# Run Lighthouse audit (requires Chrome)
agentbadge-scan scan https://agentbadge.xyz/ --lighthouse

# Generate premium PDF report (requires Chrome/Chromium)
agentbadge-scan scan https://agentbadge.xyz/ --pdf
agentbadge-scan scan https://agentbadge.xyz/ --pdf --pdf-output ./my-report.pdf
agentbadge-scan scan https://agentbadge.xyz/ --pdf --chrome-path /usr/bin/chromium-browser

# Limit resources to fetch
agentbadge-scan scan https://agentbadge.xyz/ --resources robots,sitemap,openapi

badge

Generate an SVG badge from a report.

agentbadge-scan badge agentbadge-report.json
agentbadge-scan badge agentbadge-report.json --output badge.svg --label "agent readiness"

fix

Generate fix suggestions from a report.

agentbadge-scan fix agentbadge-report.json
agentbadge-scan fix agentbadge-report.json --dry-run
agentbadge-scan fix agentbadge-report.json --output fix-suggestions.json

verify-report

Verify the integrity signature of a report.

agentbadge-scan verify-report agentbadge-report.json

Programmatic Usage

import {
  scanDomain,
  RuleEngine,
  runScoringEngine,
  assembleReport,
  getScanResult,
  AGENT_READINESS_RULESET,
  RULE_DESCRIPTIONS,
  PILLAR_DESCRIPTIONS,
  CATEGORY_DESCRIPTIONS,
  PILLARS,
  CATEGORY_TO_PILLAR,
  computeGrade,
} from "@agentbadge/scanner";

// Scan a domain
const sourceState = await scanDomain("https://agentbadge.xyz/");

// Run rule engine
const ruleResult = RuleEngine.run(sourceState);

// Run scoring engine (v2-pillars model)
const scoreResult = runScoringEngine({
  assertions: ruleResult.assertions,
  rulesetManifest: AGENT_READINESS_RULESET,
});

// Assemble signed report
const report = assembleReport({
  scope: { agent_id: "my-agent", agent_version: "1.0.0", endpoint_base_url: "https://agentbadge.xyz/" },
  assertions: ruleResult.assertions,
  scoreResult,
  previousHash: null,
  keyId: "my-key-id",
});

// Get structured scan result as JSON
const scanJson = await getScanResult("https://agentbadge.xyz/", { noCache: true });

Ruleset

159 rules (AB-001 through AB-160) across 17 categories and 4 pillars. Ruleset version: 2.0.0.

Categories

Category	Pillar	Description
discovery	Discovery	robots.txt, sitemap.xml, agent-guide.json
machine_readable	Discovery	Structured data, JSON-LD, semantic HTML
openapi	Discovery	OpenAPI spec presence and quality
skills	Discovery	Agent skills, .well-known/ai-plugin.json
agents_txt	Discovery	agents.txt protocol
webmcp	Discovery	WebMCP server descriptor
content_negotiation	Discovery	Content negotiation for AI agents
seo_aeo	Discovery	SEO/AEO meta tags, OpenGraph
documentation	Understandability	API docs, llms.txt, ai.txt
actionability	Understandability	Actionable instructions for agents
accessibility	Understandability	WCAG, screen-reader compatibility
pricing	Understandability	pricing.json endpoint
rate_limits	Understandability	Rate limit headers and docs
bot_auth	Executability	Bot authentication mechanisms
identity	Executability	Identity verification, owner proof
payments	Executability	Payment protocols (L402, x402)
bazaar	Executability	Marketplace listing, agent card
error_semantics	Executability	Error response schemas
retry_semantics	Executability	Retry headers and policies
sandbox	Executability	Sandbox/test mode availability
versioning	Executability	API versioning strategy
verification	Verifiability	Verification mechanisms
infrastructure	Verifiability	Infrastructure reliability, DNS
active_probing	Verifiability	Active probing endpoints
agent_policy	Verifiability	Agent policy declarations

Pillars

Pillar	Weight	Question
Discovery	20%	Can an agent find you?
Understandability	25%	Can an agent understand you?
Executability	30%	Can an agent act on your API?
Verifiability	25%	Can an agent verify what it observed?

Scoring

The scanner uses a 4-pillar scoring model (v2):

• Each category receives a score (0–100) based on assertion statuses (VERIFIED=1.0, INFERRED=0.7, CONFLICT=0.0, GAP=0.0, NOT_APPLICABLE=0.0).
• Category scores are grouped into pillars by CATEGORY_TO_PILLAR mapping.
• Each pillar score is the weighted average of its category scores.
• The overall score is the weighted average of pillar scores (weights: Discovery 20%, Understandability 25%, Executability 30%, Verifiability 25%).
• Floor caps apply: high-severity GAPs in discovery/documentation cap the score at 40; critical-severity GAPs cap at 30.
• A letter grade (A–F) is assigned based on the final score.

Rule Descriptions

Every rule has a detailed description with rule_id, category, icon, title, short_description, user_value, wrong_example, right_example, effort_hint, and estimated_cost. Access via:

import { RULE_DESCRIPTIONS, PILLAR_DESCRIPTIONS, CATEGORY_DESCRIPTIONS } from "@agentbadge/scanner";

Resource Fetchers

48 resource fetchers scan for:

robots.txt, sitemap.xml, agent-guide.json, OpenAPI spec, llms.txt, ai.txt, agents.txt, .well-known/ai-plugin.json, WebMCP descriptor, JSON-LD, OpenGraph, semantic HTML, pricing.json, auth metadata, OAuth endpoints, L402/x402 headers, DNS AID, identity proofs, agent cards, skill files, accessibility reports, content negotiation, favicons, RSS feeds, link headers, MCP server.json, content depth, operational discovery, and more.

Output Formats

• pretty — Human-readable terminal output with category grouping (default)
• table — Compact table format
• json — Machine-readable JSON to stdout
• all — All formats combined
• PDF — Premium PDF report (requires Chrome/Chromium)

Configuration

Option	CLI Flag	Description
No cache	--no-cache	Force refetch all resources
Format	--format <pretty|table|all|json>	Output format
Output path	--output <path>	Custom report file path
Skip signing	--skip-sign	Skip Ed25519 signing (dev mode)
Telemetry	--telemetry	Enable anonymous usage telemetry
Lighthouse	--lighthouse	Run Lighthouse audit (requires Chrome)
PDF	--pdf	Generate PDF report (requires Chrome)
Chrome path	--chrome-path <path>	Path to Chrome/Chromium
Resources	--resources <list>	Comma-separated resource filter

Feedback & Contact

Have questions, suggestions, or found a bug? We'd love to hear from you.

• Contact page: agentbadge.xyz/contact
• Email: [e-mail]
• Discord: Join us via the contact page
• Telegram: Reach out via the contact page

License

MIT