RTBL guide for developers

This page provides all the information you need to add RTBL support to your XMPP software - whether that’s a server, bot or other utility. Further down it also details the protocol used to forward spam reports to us, so we can update and improve our RTBLs.

If you have any questions about implementing the RTBL protocol, feel free to ask them in the jdev developer chatroom.

Consuming the RTBLs

The protocol is very simple. RTBLs are simply normal XEP-0060 pubsub nodes. The contents of the node may vary between lists.

MUC bans

These nodes are suitable for restricting access to public channels, for example, banning or restricting voice for matching JIDs.

Nodes

This format is used by the following nodes:

• muc_bans_sha256

Format

• Item IDs are either a JID or a hash of a JID (e.g. our muc_bans_sha256 node uses SHA256 hashes of JIDs).
  • Implementations should check both the bare JID (e.g. user@example.com) and the domain (e.g. example.com) against the list, to support domain-wide blocks of rogue servers.
  • JIDs should always be normalized before comparison or hashing.
• Item payloads are a XEP-0377 <report> element, describing the reason for the listing.

For example, the JID ‘sales@stolen-cardz.example’ could be presented as:

<item id='7583a9b348a498d329089a20d51b4fa0da65da0cab52bf300e0d775750311fc9'>
    <report xmlns="urn:xmpp:reporting:1" reason="urn:xmpp:reporting:spam">
        <text>Spamming channels with advertisements for criminal activity</text>
    </report>
</item>

Spam sources

These nodes are used to share information about reported spam sources - servers, IP addresses and individual JIDs.

Nodes

This format is used by the following nodes:

• spam_source_domains

Format

• Item IDs are the normalized domain name of the reported server
• Item payloads are a XEP-0377 <report> element, describing the reason for the listing.
• In addition, the <report/> element may contain a custom child element describing additional metadata (described below).

Additional metadata

Custom metadata for each item is provided in a <meta/> element in the https://xmppbl.org/meta/v1 (this will be a child of the <report/> element).

<meta xmlns="https://xmppbl.org/meta/v1">
    <recommendations>
        <block-strangers/>
    </recommendations>
</meta>

The <recommendations/> element contains suggested actions to take when receiving traffic from the listed source.

A combination of the following recommendations may be present:

• <block-strangers/>
• <allow-trusted/>

If <block-strangers/> is present, we recommend that you block all attempts to initiate chats (messages, subscription requests) from unfamiliar JIDs (e.g. those which are not on the recipient’s roster).

If <allow-trusted/> is present, we recommend allowing traffic which contains a XEP-0489: Reporting Account Affiliations tag with an affiliation of “admin” or “member”, or a trust score greater or equal to the value provided in the ‘min’ attribute (which defaults to ‘0.5’ if not present). This tag will only be present for domains which have XEP-0489 support.

Forwarding spam reports

This section describes the protocol used to submit spam reports to the xmppbl.org service.

Protocol syntax

XEP-0377 assumes the report is embedded within another protocol such as XEP-0191: Blocking, and doesn’t specify a format for communicating “standalone” reports.

This section describes the format that is expected by xmppbl.org.

Each report is transmitted inside a <message> stanza. The <report> element is a payload of the message, and contains <jid/> element (borrowed from XEP-0268: Incident Handling):

<message from="prosody.example" to="destination.example" id="e14f56ce-e079-11ee-861e-ab97f9e476c8">
    <report xmlns="urn:xmpp:reporting:1" reason="urn:xmpp:reporting:spam">
        <jid xmlns="urn:xmpp:jid:0">spammer@bad.example</jid>
        <text>
          Never came trouble to my house like this.
        </text>
    </report>
</message>

The outer message MUST include an ‘id’ attribute unique to this report. If further communication about this issue occurs (e.g. via IODEF), that id serves as the report/incident ID. If the same report is sent to multiple recipients, the same ‘id’ attribute SHOULD be used.

If the original report indicated a specific message (as described in XEP-0377) then this can also be included, wrapped in a XEP-0297: Stanza Forwarding <forwarded/> element. The <forwarded/> element should be a direct child of the top-level <message/> stanza, i.e. a sibling of <report/>. xmppbl.org does not currently support multiple attached messages in a single report, additional forwarded payloads will be ignored..

<message from="prosody.example" to="destination.example" id="e14f56ce-e079-11ee-861e-ab97f9e476c8">
  <report reason="urn:xmpp:reporting:spam" xmlns="urn:xmpp:reporting:1">
    <jid xmlns="urn:xmpp:jid:0">spammer@bad.example</jid>
    <text>Never came trouble to my house like this.</text>
  </report>
  <forwarded xmlns="urn:xmpp:forward:0">
    <message from="spammer@bad.example" to="victim@prosody.example" type="chat" xmlns="jabber:client">
      <body>Spam, Spam, Spam, Spam, Spam, Spam, baked beans, Spam, Spam and Spam!</body>
    </message>
  </forwarded>
</message>

Reporting to origin servers

This section describes the logic used by Prosody’s mod_report_forward when a user reports a JID or message.

1. Look up the XEP-0157: Contact Addresses for XMPP Services for the sending domain
2. If ‘report-addresses’ is present in the response:
3. Find the first ‘xmpp:’ URI that does not have a query part (e.g. entries with ‘?join’ are ignored)
4. If report-addresses is not found, repeat step 2 with ‘abuse-addresses’ instead.

If no suitable addresses are found, the report can be sent to the bare JID of the server as a last resort.

Send the report in the syntax described in the previous section, except also add a <body/> element with a human-readable description of the report. This allows them to read the report in an IM client, even if they do not have automation to process the machine-readable payloads of incoming reports.