Skip to content

CatalogLock

Choose a tag to compare

View all tags
@BryanFiFife BryanFiFife released this 27 Aug 00:24
v0.1.0
de13eb6

🔒 CatalogLock v0.1.0

First public release

Version Tests Node Runtime deps License ARD SARIF

ARD / ai-catalog security · recursive resolution · SSRF resistance · trust graph · deterministic lockfile · blast-radius diff · SARIF · GitHub Action

CatalogLock is a pre-connect security gate for Agentic Resource Discovery (ARD) catalogs. It resolves remote catalog graphs under strict network controls, validates publisher and trust authority, freezes reviewed state into a deterministic lockfile, and makes later drift explicit before an agent connects to newly discovered capabilities.

retrieval ≠ trust and discovery ≠ authorization

✨ Highlights

  • Canonical ARD discovery via /.well-known/ai-catalog.json
  • Compatibility probe for early /.well-known/ard.json deployments
  • Recursive catalog resolution with explicit depth/catalog limits
  • SSRF resistance across IPv4/IPv6, private, loopback, link-local, CGNAT, reserved and documentation ranges
  • DNS validation plus pinned socket lookup to reduce rebinding risk
  • Redirect-by-redirect URL/DNS/IP revalidation
  • Publisher/source authority validation for urn:air: identifiers
  • HTTPS, SPIFFE and did:web trust-identity alignment checks
  • Host-level trust identity validation
  • Cross-catalog identifier collision detection
  • Deterministic SHA-256 lockfiles with policy and graph fingerprints
  • Full-entry semantic hashing
  • Policy, root, catalog, resource and authority drift detection
  • Blast-radius reporting with severity classification
  • JSON, self-contained HTML and SARIF 2.1.0 output
  • Ready-to-use GitHub Action
  • Zero runtime npm dependencies

🛡️ Security posture

CatalogLock treats catalog metadata as untrusted input.

It does not silently promote strings such as SOC2-Type2, HIPAA or GDPR into verified compliance claims. It records signature presence but does not claim cryptographic verification where verification has not actually occurred. Passing CatalogLock is not equivalent to authorizing the discovered MCP server, A2A agent or API.

The resolver is fail-closed around unsafe network destinations and enforces bounded graph traversal.

🧪 Verification

The release candidate passed 44/44 regression tests before publication, including coverage for:

  • IPv4/IPv6 private-address rejection
  • canonical ARD discovery behavior
  • schema and URL/data validation
  • publisher/source mismatches
  • host trust identity mismatches
  • cross-catalog identifier collisions
  • deterministic lockfile generation
  • authority drift
  • policy drift
  • catalog body drift
  • semantic entry drift

The source release was also compiled against genuine Node 24 type definitions, and the packaged CLI/action wrappers were smoke-tested.

🚀 Quick start

npm ci
npm run build

node dist/cli.cjs scan example.com
node dist/cli.cjs lock example.com --output cataloglock.lock.json

Then compare reviewed state later:

node dist/cli.cjs lock example.com --output cataloglock.next.json
node dist/cli.cjs diff cataloglock.lock.json cataloglock.next.json

⚙️ GitHub Action

Use the published semver release tag:

name: Catalog security
on: [push, pull_request]

jobs:
  cataloglock:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: BryanFiFife/CatalogLock@v0.1.0
        with:
          target: example.com
          fail-on: error
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: cataloglock.sarif

📦 Release artifacts

Attach these three files to the GitHub Release:

  • CatalogLock-v0.1.0.zip
  • cataloglock-0.1.0.tgz
  • CatalogLock-v0.1.0.sha256

SHA-256

893f24ceaa03b740a510bd2a2fcc8a354fb065ed525ca798ca9a5cfc8a2081c0  CatalogLock-v0.1.0.zip
4fa5a74afcc4fd16fef2af01e9b710327746fc5664e9a809829d9ccf5d7afc20  cataloglock-0.1.0.tgz

📌 Release target

Published tag: v0.1.0

Recommended target commit:

de13eb613044b2589880f2d579cc9818ffe00bc4

This commit contains the verified v0.1.0 implementation plus the final README/CI metadata fixes. No application-source changes were made after the 44/44 test gate.

🗺️ Next

Planned work includes cryptographic verification for supported JWS/DID Web trust manifests, richer redirect-chain telemetry, public-suffix-aware authority policy, signed lockfiles/transparency anchoring, fleet-scale registry ingestion and enterprise policy packs.

The open agentic web needs a lockfile.

⭐ If CatalogLock is useful to you, star the repository and help make agent discovery reviewable infrastructure instead of blind runtime trust.

Assets 5
Loading