rkn-block-checker Monitoring Guide

TL;DR

TL;DR: rkn-block-checker is a Python CLI for diagnosing Russian internet blocking patterns using DNS, TCP, TLS, HTTP, whitelist controls, blacklist targets, JSON output, and confidence-labeled verdicts.

Source and Accuracy Notes

This guide uses official project material from MayersScott/rkn-block-checker, including quick start, usage examples, install options, JSON schema, custom target list formats, verdict logic, caveats, privacy notes, and threat model. Commands below are preserved from project docs.

The tool performs network diagnostics from machine where it runs. Results describe that vantage point: ISP, DNS resolver, routing, TLS behavior, and target availability at that moment. They are evidence, not legal determination.

What Is rkn-block-checker?

rkn-block-checker is a command-line diagnostic tool for checking whether current network environment appears affected by Russian internet blocking. It compares whitelist targets that should work against blacklist targets that may be restricted. It examines DNS behavior, TCP reachability, TLS handshake failures, HTTP stub pages, status codes, and timing signals. Output includes verdicts and confidence labels.

The project is useful because censorship failures rarely look identical. DNS may fail locally while public DoH resolves. TCP may connect but TLS may reset after ClientHello, suggesting SNI-based filtering. HTTP may return ISP stub pages. Some targets may fail because site is down, rate-limited, geo-blocked, or blocking probes. rkn-block-checker tries to separate these signals rather than returning only “up/down.”

It also supports JSON output, custom target lists, cron-style snapshots, and jq pipelines. That makes it practical for repeat measurement, not only one-time debugging.

Repo-Specific Setup Workflow

Step 1: Install and run quick start

pip install rkn-block-checker
rkn-check

This performs default checks and prints human-readable summary with whitelist and blacklist sections.

Step 2: Diagnose current connection

rkn-check

Use this first when someone asks, “Is my connection blocked or is site down?” It gives control targets and restricted targets in one run.

Step 3: Check specific URLs

rkn-check --url https://example.com
rkn-check --url example.com --url google.com    # repeat for several

This is useful when default lists do not include your target. Repeat --url for several URLs when comparing sites.

Step 4: Pipe JSON into jq

# names of every blocked site
rkn-check --json | jq -r '.blacklist[] | select(.verdict != "OK") | .name'

# count by block type
rkn-check --json | jq '.blacklist | group_by(.verdict)
                       | map({verdict: .[0].verdict, count: length})'

# only DPI-style blocks (TCP fine, TLS dies)
rkn-check --json | jq '.blacklist[] | select(.verdict == "TLS_BLOCK" and .tcp_ok)'

JSON mode is best for dashboards, archives, or comparisons over time.

Step 5: Use custom target lists

rkn-check --black-file my-list.txt
rkn-check --white-file my-control.json --black-file my-targets.json

Supported custom JSON shape:

{
  "google":   "https://google.com",
  "github":   "https://github.com",
  "rutracker": "https://rutracker.org"
}

Supported text shape:

# bare URL - name auto-derived from the hostname
https://example.com

# name<whitespace>URL
github https://github.com

# name=URL
custom=https://example.org

# blank lines and #-comments are skipped

Step 6: Install from source only if developing

git clone https://github.com/MayersScott/rkn-block-checker.git
cd rkn-block-checker
pip install -e .

For development extras:

pip install -e ".[dev]"

Deeper Analysis

rkn-block-checker’s design is stronger than simple website pinging because it uses multiple layers. DNS, TCP, TLS, and HTTP each fail differently. A DNS mismatch between system resolver and DoH can indicate DNS poisoning or resolver filtering. TCP failure can mean routing, firewall, or server availability issue. TLS reset after ClientHello can align with SNI-based DPI. HTTP stub-page markers indicate interception or provider block pages.

Whitelist controls are essential. Without known-good targets, you cannot distinguish broad connectivity failure from censorship-like failure. If both whitelist and blacklist fail, problem may be general network outage, captive portal, DNS breakage, or local firewall. If whitelist works and blacklist shows consistent filtered patterns, confidence improves.

The tool’s confidence language matters. It uses “likely” and verdict categories because remote diagnostics are probabilistic. Site owners change infrastructure. CDNs route differently. TLS stacks behave differently. ISPs can inject errors. A single run is snapshot evidence; repeated JSON snapshots from same vantage point make stronger story.

For analysts, --json --no-self-info is useful when storing data over time while reducing location/IP exposure.

rkn-check --json --no-self-info > "snapshots/$(date -I).json"

For developers, custom lists let you measure your own service availability from affected networks. Put your site in blacklist-like target list and keep neutral control sites in whitelist file.

Limitations remain. Tool cannot prove regulatory cause. It cannot see packets outside local machine. It may misclassify server-side blocks as network blocks. It may produce noisy results when targets rate-limit, block probes, use regional CDNs, or temporarily fail.

Practical Evaluation Checklist

• Run default rkn-check before custom targets.
• Verify whitelist health before interpreting blacklist failures.
• Use --json for repeatable analysis and diffing.
• Use --no-self-info when storing or sharing snapshots.
• Add stable control targets in custom whitelist files.
• Repeat tests from multiple networks before drawing broad conclusions.
• Treat TLS DPI verdicts as evidence pattern, not final proof.

Security Notes

Network censorship diagnostics can expose sensitive context: IP address, ISP, approximate location, target sites, and timing. Do not publish raw JSON with self_info unless intended. When investigating politically sensitive targets, consider personal risk and local law.

The tool sends network requests to tested URLs and DNS providers. Custom target lists reveal interests to local network observers. Run from environment where such probing is acceptable. Avoid scanning large lists aggressively; respect target services and local network policies.

FAQ

Q: What Python version is needed? A: Project badge indicates Python 3.10+.

Q: Does it prove a site is blocked by RKN? A: No. It reports technical signals and confidence. Legal or regulatory attribution needs more evidence.

Q: What does TLS_BLOCK mean? A: It indicates TCP succeeded but TLS failed in a pattern consistent with TLS/SNI filtering.

Q: Can I test my own URLs? A: Yes, use repeated --url flags or custom black/white target files.

Q: How do I store results safely? A: Use JSON output and consider --no-self-info to omit IP/location metadata from snapshots.

Related reading: GitHub Trending tools, Developer tools, bumblebee setup guide open source go ai tool, and openmonoagent ai setup guide open source c ai tool.

Conclusion

rkn-block-checker is a focused, practical CLI for censorship-style network diagnostics. Install with pip, run default checks, inspect whitelist controls, then use custom targets and JSON output for deeper analysis. Its best use is careful evidence gathering from specific vantage points, with privacy and uncertainty kept visible.