About the Instance Directory

This is a directory application intended to collect a list of federated instances of a PrivateBin, written in Rust 🦀.

Removing an instance

Instances will be removed, if they are no longer reachable from this service for more then 24 hours, checked every 15 minutes. If you run a PrivateBin instance and would like not to have it published on this site, you can disable it in one of multiple ways.

robots.txt

By default the robots.txt file of a PrivateBin instance disallows all search engine spiders. You can add an explicit rule to tell this service not to list your site:

User-agent: PrivateBinDirectoryBot
Disallow: /
			

Webserver configuration

If you don't want to rely on this service following your sites robots.txt, you can configure your webserver to block any access that matches this services user agent, which starts with the string PrivateBinDirectoryBot. Here below are examples of configuration snippets to do just that:

Apache
RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} PrivateBinDirectoryBot [NC]
RewriteRule . - [R=403,L]
			
Caddy
@privatebinbot header User-Agent PrivateBinDirectoryBot*
respond @privatebinbot 403
			
Nginx
if ($http_user_agent ~ PrivateBinDirectoryBot ) {
	return 403;
}
			
How to validate your webserver configuration

The complete user agent string currently looks like this:

PrivateBinDirectoryBot/0.9.2 (+https://privatebin.info/directory/about)
			

You can validate your webserver configuration using the following curl command, expecting to get an HTTP 403 status code, if you block the bot:

$ curl --head --header "User-Agent: PrivateBinDirectoryBot/0.9.2 (+https://privatebin.info/directory/about)" https://paste.example.com
HTTP/2 403
[...]
			

How the instances get tested

The columns of the lists are based on the following checks:

Version
PrivateBin and ZeroBin instances advertise their version as part of their main JavaScript file name.
HTTPS
A simple check if the instance URL is responding, when accessed over HTTPS.
HTTPS enforced
The instance URL is accessed over HTTP and a 30x redirection status code is received with an HTTP Location header, that points to a matching HTTPS URL or there is no HTTP access offered on port 80.
recommended CSP
If the instance responds with the currently recommend HTTP Content-Security-Policy (CSP) header. This policy disables browser functions that PrivateBin doesn't use and can, among other things, mitigate execution of scripts that bypass other security mechanisms while viewing a paste that contains such. We currently recommed the following policy: default-src 'none'; base-uri 'self'; form-action 'none'; manifest-src 'self'; connect-src * blob:; script-src 'self' 'unsafe-eval'; style-src 'self'; font-src 'self'; frame-ancestors 'none'; img-src 'self' data: blob:; media-src blob:; object-src blob:; sandbox allow-same-origin allow-scripts allow-forms allow-popups allow-modals allow-downloads
Observatory Rating
The score of an instance as per the Mozilla 🐲 Observatory.
File upload
If the instance has the fileupload option enabled, you can upload attachments along side your texts.
Uptime
The instances are checked for availability every 15 minutes, using an HTTP(S) HEAD request to reduce transmitted data. Only the last 100 results (25h) are kept and the percentage is calculated based on this. Basically this percentage is an indication if an instance expirienced any prolonged downtime during the last day.
Country
The IP assigned to the domain of the instance URL is checked against a GeoIP database. The precision of these databases is limited, but can serve as an indication in which country the instance is hosted. This may serve to select an instance that is close by or avoid instances located in undesirable jurisdictions.

When do the instances get updated

The uptime checks via HTTP(S) HEAD request are performed every 15 minutes. Once a day all the other properties get re-evaluated and the list updated.

Using the instance list programmtically

The instance list can be retrieved as a JSON encoded data structure by calling the /api endpoint with the HTTP header Accept: application/json set. The list order is randomized every time to spread the load to the instances.

$ curl --header "Accept: application/json" https://privatebin.info/directory/api
			

Additionally, the following optional GET parameters can be sent, to adjust the output:

top
Number between 1 - 100, defaults to 10. How many instances to return from the top of the list.
attachments
Boolean (true or false), unset by default. Only return instances that offer attachment upload in their web UI - third party clients can always upload attachments.
country
ISO 3166-1 alpha-2 country code, unset by default. Only return instances of that country. Note the limitations of this type of lookup, as explained above.
csp_header
Boolean (true or false), unset by default. Only return instances that set the currently recommend HTTP Content-Security-Policy (CSP) header (see above).
https
Boolean (true or false), unset by default. Only return instances that offer HTTPS.
https_redirect
Boolean (true or false), unset by default. Only return instances that enforce HTTPS, either by having HTTP disabled or redirected to HTTPS.
version
Version prefix, for example "1" or "1.3" or "1.3.5". Only return instances that start with that version string.
min_uptime
Number between 1 - 100, unset by default. Only return instances that have an uptime of that percentage or higher.
min_rating
Ratings as per Academic grading in the USA (A+, A, A−, B+, B, B−, C+, C, C−, D+, D, D−, F & - (unrated)), unset by default. Only return instances that have that rating or higher.

For example, to retrieve the top 3 instances, randomized:

$ curl --header "Accept: application/json" https://privatebin.info/directory/api?top=3
			
Fork me on GitHub