Instance Directory - About the Instance Directory

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.13.0 (+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.13.0 (+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 recommend 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 experienced 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 programmatically

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.5" or "1.5.1". 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

Forwarding to a single, random instance

A single random instance can be retrieved as a Location HTTP header by calling the /forward-me endpoint. Only instances that enforce HTTPS, use the currently recommend HTTP Content-Security-Policy (CSP) header (see above), have a 100% uptime, a rating above or at A− and are of the latest version get returned.

$ curl -v https://privatebin.info/directory/forward-me

Due to using standard HTTP headers, this will also work when accessed in browsers, hence the limited options. When you click on the following link, it will open a new random instance every time: visit a random PrivateBin instance.

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

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.
version: Version prefix, for example "1" or "1.5" or "1.5.1". Only return instances that start with that version string.

For example, to retrieve an instance with attachments enabled:

$ curl -v https://privatebin.info/directory/forward-me?attachments=true