@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):

1. 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).
2. Category scores are grouped into pillars by CATEGORY_TO_PILLAR mapping.
3. Each pillar score is the weighted average of its category scores.
4. The overall score is the weighted average of pillar scores (weights: Discovery 20%, Understandability 25%, Executability 30%, Verifiability 25%).
5. Floor caps apply: high-severity GAPs in discovery/documentation cap the score at 40; critical-severity GAPs cap at 30.
6. 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: [email protected]
• Discord: Join us via the contact page
• Telegram: Reach out via the contact page

License

MIT