Specification v0.1

This is a short specification for X-ARF (Extended Reporting Format).
If you are interested in joining us and/or also start reporting in X-ARF or you think that you might have some valuable ideas, feel that there's still things missing etc., let us know. We are happy to get as much feedback as possible.

The idea of X-ARF


X-ARF is designed as a pure container format, where everyone can plug in as many specific containers as he wants to. The content of such containers can be completely different from others. The container itself will be defined in schemes. These schemes contain all information about the meaning of each listed field (mandatory, optional, data type, allowed values,...). To make it easy to read the content of a X-ARF report (just like ARF) the information is represented in YAML(http://en.wikipedia.org/wiki/YAML). The schemes themselves are defined in JSON-schema, draft 02 (please notice!).
To make sure everybody can understand all available schemes, this community has been established. This community discusses e.g. new containers and additional information for existing containers. Mostly all members of the community also use X-ARF for real-life reporting and abuse handling. Available schemes are versioned and published on this webpage (here). That way every parser is able to validate against the latest X-ARF schema and thus is able to handle it.
Please notice that the status of this document still is a draft. If you want to start reporting in X-ARF, feel free to join the X-ARF mailinglist as well.

Overview of a X-ARF Report Email

Header

Please add some mandatory headers to your X-ARF-Reports to let parsers identify incoming reports properly:

Subject

We recommend to use an easy to understand subject line as follows:

1st MIME part

2nd MIME part

3rd MIME part



Content of the 2nd MIME part: Mandatory and optional keys/fields

Within the 2nd MIME part, the following mandatory and optional fields are used. Furthermore, specific reports may use specific mandatory or optional fields.

<Reported-From:> [mandatory][only once]

This field needs to contain the sending e-mail address.
Example:
Reported-From: whatever@example.com

<Category:> [mandatory][only once]

This field must contain one of the following categories:

abuse technical abusive behavior - any kinds of attacks like virus, malware, logins, etc.
fraud financial abuse like creditcard-fraud, etc.
auth misuse or failure of authentification methods, SSL, SSH, POP3, etc.
info all sorts of pure informational reports like blacklistings, delistings
private all sorts of closed information exchange between 2 or more parties

Usually, this field will be defined by the X-ARF-community and the reporting party.
Example:
Category: abuse

<Report-Type:> [mandatory][only once]

This field contains the type of report. For example login-attack, phishing-website, spamvertized, etc.
Usually this field will be defined by X-ARF-community and the reporting party to make sure it has a unique meaning across all available schemas.
Example:
Report-Type: login-attack

<User-Agent:> [mandatory][only once]

Name and version of the generating software (see RFC 1945 and RFC 2068)
Example:
User-Agent: X-ARF Reporting Toolset V.:0.9.5(beta)

<Report-ID:> [mandatory][only once]

[UNIXTIMESTAMP|randomnumber(4)]@yourdomain.tld
Example:
Report-Id: 12679288729564@yourdomain.tld

<Date:> [mandatory][only once]

This field contains the date of the incident itself or date when the incident has been discovered (if not reported realtime). The date should be in rfc3339 format - if the x-arf schema specifies the date with "format":"date-time". Due to backward compatibility reasons (and the ongoing json-schema draft discussion) the date may be written in the rfc2822 format, no matter if "format":"date-time" is used or not in a x-arf schema description. Therefore, parser implementations should check which of the both formats is used.
Example (rfc2822 format):
Date: Mon, 24 Aug 2009 16:19:15 -0000

<Source:> [mandatory][only once]

Contains the source of abusive behavior. It is described by <Source-Type:>
Example:
Source: 192.168.1.134
Source: 2001:898:2000:c:213:206:89:190
Source: https://www.domain.tld/folder/file.xxx
Source: domain.tld
Source: localpart@domain.tld


<Source-Type:> [mandatory][only once]

Currently the following Types are used:
ipv4 (RFC 791 compliant IP-address)
ipv6 (RFC 2460 compliant IP-address)
uri   (RFC 2396 compliant URI)
domain
email
More types will be defined as needed. Please join our mailinglist to request further types.
Example:
Source-Type: uri


<Attachment:> [mandatory][only once]

This field defines whether an attachment with further information exists or not. If no such attachments exists, this field has to be set to "none". If an attachment exists, this field must contain the MIME type of the following attachment.
Example:
Attachment: text/plain

<Schema-URL:> [mandatory][only once]

This field contains the URI to the JSON-schema that describes the content of the report. The schema must be published under and the URI must point to
the www.x-arf.org domain. If <Category:> is set to private the schema may be published according to what the involved parties agreed upon.
Example:
Schema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json

<Version:> [optional][only once]

This field contains the version of this specification.
The current version number is 0.1
Example:
Version: 0.1

<Occurrences:> [optional][only once]

Though each incident should be reported on its own, this field may be used to consolidate incidents which are strongly related to each other.
Example:
Occurrences: 14

<TLP:> [optional][only once]

This field may be used to indicate the sensitivity of the information in the report.
Please see the Wikipedia article
Example:
TLP: amber

There are already some containers in use that have been designed by the community. If you have ideas for optional fields in existing containers or ideas for completely new containers, please join the X-ARF mailinglist.


Copyright (C) 2010-2012 X-ARF.ORG COMMUNITY
This document and translations of it and the provided schema files may be used to implement X-ARF. This document may be copied and furnished to others, and derivative works that comment on or otherwise explain X-ARF or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way.
THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED ON AN "AS IS" BASIS AND X-ARF.ORG DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.