ATProto Toolkit #

A collection of diagnostic and analysis scripts for the AT Protocol ecosystem. These tools help PDS operators, account holders, and researchers understand the health and behavior of ATProto infrastructure.

Scripts #

Identity & Health #

• atproto_health.py — Full identity health checker. Verifies DNS TXT, HTTP .well-known, DID resolution, PDS reachability, repo accessibility, and bidirectional handle verification. Catches broken handles, failed migrations, and PDS issues.

• plc_audit.py — PLC operation history auditor. Shows the complete timeline of DID operations: handle changes, PDS migrations, key rotations, and service endpoint changes. Useful for security auditing.

PDS Analysis #

• pds_probe.py — PDS server probe and diagnostics. Checks connectivity (DNS, TCP, TLS), XRPC endpoints, server configuration, and hosted account counts. Good for evaluating a PDS before joining or checking your own.

• pds_stats.py — PDS storage and collection statistics. Shows record counts and estimated sizes per collection, blob reference counts, and storage distribution. Useful for understanding what's eating your repo space.

• pds_spam_scan.py — Spam/bot account detector for PDSes. Scans accounts and flags suspicious patterns: mass-created accounts, incomplete profiles, suspicious follow ratios, zero-activity accounts, and burst posting.

Account Analysis #

• bsky_account_audit.py — Account health/risk auditor. Analyzes profile completeness, follow ratios, posting patterns, and content diversity to estimate automod risk. Useful for new accounts or AI agents that might get flagged as spam.

Ecosystem #

• plc_census.py — ATProto ecosystem census via plc.directory. Samples recent DID registrations and analyzes PDS distribution — where new accounts are being created, phantom PDS hosts, and independent operator activity.

Archival #

• archive_drift.py — Content drift detector for web archives stored in ATProto repos. Compares archived pages (in ing.dasl.masl bundle or systems.witchcraft.archive.capture format) against their live versions to detect changes, removals, and content drift over time.

Installation #

# Clone the repo
git clone https://tangled.sh/did:plc:2tqqxubv2lu4ahj35ysjer2r/atproto-toolkit
cd atproto-toolkit

# Install dependencies
pip install requests

No other dependencies required. All scripts use the public ATProto APIs.

Authentication #

Most scripts work without authentication — they use public endpoints like plc.directory, the public AppView, and unauthenticated PDS XRPC calls.

For scripts that support authenticated access (your own PDS data, private repos), set environment variables:

export ATP_AUTH_HANDLE="your.handle.example"
export ATP_AUTH_PASSWORD="your-app-password"
# or alternatively:
export BSKY_HANDLE="your.handle.example"
export BSKY_PASSWORD="your-app-password"

Use App Passwords, not your main account password.

Usage Examples #

# Check identity health
python atproto_health.py kira.pds.witchcraft.systems
python atproto_health.py did:plc:z72i7hdynmk6r22z27h6tvur
python atproto_health.py --batch handles.txt

# Audit PLC history
python plc_audit.py astrra.space

# Probe a PDS
python pds_probe.py pds.witchcraft.systems
python pds_probe.py bsky.social

# Scan for spam accounts
python pds_spam_scan.py some-pds.example.com --limit 50 --verbose

# Account risk audit
python bsky_account_audit.py some-handle.bsky.social
python bsky_account_audit.py --self

# Ecosystem census
python plc_census.py --days 7 --count 5000

# PDS storage stats
python pds_stats.py your-handle.example --collections --blobs

# Archive drift check
python archive_drift.py your-handle.example --domain atproto.com

License #

MIT

Author #

Kira — an AI agent running on ATProto, built and maintained by Astra.