DOCSEARCHbyAlgolia
Submit Docs

XARF (eXtended Abuse Reporting Format)

repository·master·Indexed 41 days ago

https://github.com/abusix/xarf

A machine-readable format for reporting abuse. This documentation covers the legacy v3 schema, including bundling options (xarf_bundled.schema.json and xarf_deref.schema.json), SMTP transmission via multipart/report, and validation using ajv-cli. Note that XARF v3 is deprecated; new integrations should use XARF v4.

Tokens
1.8K
Snippets
3
Records
5
Agent score
50%

What's inside XARF

  1. Understand XARF v3 Schema Bundling Options

    master

    When using the legacy XARF v3 schema, you can choose between two types of bundled schema files depending on your tool's capabilities:

    • xarf_bundled.schema.json: A minimized file that includes all versions using internal references. This is best for most use cases if your JSON schema tool can handle complex, multi-hop internal references.
    • xarf_deref.schema.json: A larger file where all schema definitions are included without any references (completely dereferenced). Use this if your code generation or validation tool is not sophisticated enough to resolve internal references.

  2. Send XARF reports via SMTP

    master

    XARF extends the RFC5965 (ARF) format for email feedback reports. To send a XARF report via email, the message must follow a specific MIME structure:

    1. Outer Content-Type: multipart/report; report-type=feedback-report.
    2. MIME Part 1 (Human-readable): A text/plain part describing the condition that caused the report.
    3. MIME Part 2 (Machine-readable ARF): A message/feedback-report part. To signal an XARF report, the Feedback-Type field must be set to xarf (this is an unofficial extension to the standard values abuse, fraud, virus, other, or not-spam). This part must include Feedback-Type, User-Agent, and Version.
    4. MIME Part 3 (XARF Data): An application/json part containing the actual XARF report, typically sent as a base64 encoded attachment with the filename xarf.json.
    Content-Type: multipart/report; report-type=feedback-report;
    boundary="--_NmP-f348b15e0b4a4931-Part_1"
From: Abusix <noreply@abusix.org>
To: Max Musterman <max@abusix.com>
Subject: XARF test
Message-ID: <9a271f0f-8929-421b-5bfa-80e50dabf32d@abusix.org>
Date: Tue, 21 Apr 2020 10:25:47 +0000
MIME-Version: 1.0

----_NmP-f348b15e0b4a4931-Part_1
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

This is the human readable description
----_NmP-f348b15e0b4a4931-Part_1
Content-Type: message/feedback-report
Content-Disposition: inline

Feedback-Type: xarf
User-Agent: Abusix/1.0
Version: 1
----_NmP-f348b15e0b4a4931-Part_1
Content-Type: application/json; name=xarf.json
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=xarf.json

ewogICJWZXJzaW9uIjogIjEiLAogICJSZXBvcnRlckluZm8iOiB7CiAgICAiUmVwb3J0ZXJPcmciOiAiRXhhbXBsZU9yZyIsCiAgICAiUmVwb3J0ZXJPcmdEb21haW4iOiAiZXhhbXBsZS5jb20iLAogICAgIlJlcG9ydGVyT3JnRW1haWwiOiAicmVwb3J0c0BleGFtcGxlLmNvbSIsCiAgICAiUmVwb3J0ZXJDb250YWN0RW1haWwiOiAiY29udGFjdEBleGFtcGxlLmNvbSIsCiAgICAiUmVwb3J0ZXJDb250YW5hbWUiOiAiMr4gRXhhbXBsZSIsCiAgICAiUmVwb3J0ZXJDb250YWN0UGhvbmUiOiAiKyAwMSAwMDAgMTIzNDU2NyIKICB9LAogICJEaXNjbG9zdXJlIjogdHJ1ZSwKICAiUmVwb3J0IjogewogICAgIlJlcG9ydENsYXNzIjogIkFjdGl2aXR5IiwKICAgICJSZXBvcnRUeXBlIjogIlNwYW0iLAogICAgIlJlcG9ydFN1YlR5cGUiOiAiVHJhcCIsCiAgICAiRGF0ZSI6ICIyMDE4LTAyLTA1VDE0OjE3OjEwWiIsCiAgICAiU291cmNlSXAiOiAiMTkyLjAuMi41NSIsCiAgICAiU291cmNlUG9ydCI6IDU0MzIxLAogICAgIkRlc3RpbmF0aW9uSXAiOiAiMTk4LjUxLjEwMC4zMyIsCiAgICAiRGVzdGluYXRpb25Qb3J0IjogMjUsCiAgICAiU210cE1haWxGcm9tQWRkcmVzcyI6ICJzcGFtQGV4YW1wbGUuY29tIiwKICAgICJTbXRwUmNwdFRvQWRkcmVzcyI6ICJ2aWN0aW1AZXhhbXBsZS5jb20iLAogICAgIlNhbXBsZXMiOiBbCiAgICAgIHsKICAgICAgICAiQ29udGVudFR5cGUiOiAibWVzc2FnZS9yZmM4MjIiLAogICAgICAgICJCYXNlNjRFbmNvZGVkIjogdHJ1ZSwKICAgICAgICAiRGVzY3JpcHRpb24iOiAiVGhlIHNwYW0gbWFpbCIsCiAgICAgICAgIlBheWxvYWQiOiAiYldGcGJBPT0iCiAgICAgIH0KICAgIF0KICB9Cn0=
----_NmP-f348b15e0b4a4931-Part_1--

  3. Validate XARF v3 JSON-schema samples with ajv-cli

    master

    You can validate XARF v3 JSON samples against the schema using ajv-cli.

    For ajv-cli >= 4.0.0:

    npm install -g ajv-cli ajv-formats
ajv -c ajv-formats -s xarf.schema.json -d "samples/positive/**/*.json" -r "schemas/**/*.schema.json"

    For ajv-cli < 4.0.0:

    npm install -g ajv-cli@3.3.0
ajv -s xarf.schema.json -d "samples/positive/**/*.json" -r "schemas/**/*.schema.json"

  4. Generate bundled XARF v3 schemas

    master

    To create a single-file version of the XARF schema, use the provided bundling script. This is useful for distributing the schema as a single asset.

    1. Clone the repository.
    2. Install dependencies.
    3. Run the bundle command.

    This will generate two files:

    • xarf_bundled.schema.json: Minimized using internal references.
    • xarf_deref.schema.json: Completely dereferenced (larger, but more compatible with all tools).
    git clone https://github.com/abusix/xarf.git
cd xarf
npm install
npm run bundle-xarf

  5. Migrate from XARF v3 to XARF v4

    master

    The repository abusix/abusix/xarf is deprecated and hosts only the legacy XARF v3 schema. For all new integrations, you should use XARF v4.

    If you are currently using v3, existing assets like xarf_bundled.schema.json and the legacy $id URL will continue to resolve, but no new updates will be provided for v3. To migrate, follow the v3 → v4 migration guide located in the xarf-spec repository.