Xarf 1.1.0

XARF v4 C# Parser

A C# library for parsing, validating, and generating XARF v4 (eXtended Abuse Reporting Format) reports.

🚀 Status

The XarfApi surface implements the XARF v4.2.0 specification with schema-driven parsing, validation, generation, and v3 backward compatibility, at behavioural parity with the official JavaScript and Go libraries.

Versioning

• Library Version: 1.1.0 (this C# implementation)
• XARF Spec Version: 4.2.0 (the specification it implements)

The library version follows independent semantic versioning, separate from the XARF specification version it supports.

Supported .NET versions

The library targets netstandard2.1 and net8.0, and the test suite runs against it on .NET 8, 9, and 10 across Linux, macOS, and Windows in CI.

Newer runtimes (.NET 9/10) consume the net8.0 assets — no per-version build is required.

Supported Categories

• ✅ messaging - Email spam, phishing, social engineering
• ✅ connection - DDoS, port scans, login attacks, brute force
• ✅ content - Phishing sites, malware distribution, defacement, fraud
• ✅ infrastructure - Compromised systems, botnets
• ✅ copyright - DMCA, P2P, cyberlockers
• ✅ vulnerability - CVE reports, misconfigurations
• ✅ reputation - Threat intelligence, blocklists

📦 Installation

# Install from NuGet
dotnet add package Xarf

# Or using Package Manager
Install-Package Xarf

✨ JavaScript-parity API (XarfApi, v4.2.0)

The static XarfApi class mirrors the official JavaScript library (@xarf/xarf): schema-driven validation against the embedded v4.2.0 schemas, v3 auto-conversion, and result objects that carry errors/warnings instead of throwing on validation failures.

using Xarf;
using System.Text;
using System.Text.Json.Nodes;

// Parse returns a result; only malformed JSON / MaxInputBytes overflow throws.
// v3 reports are auto-detected and converted (deprecation warning in Warnings).
ParseResult result = XarfApi.Parse(json, new ParseOptions { ShowMissingOptional = true });
if (result.Errors.Count == 0)
{
    JsonObject report = result.Report; // the validated report object
}
// result.Warnings  -> unknown fields, v3 deprecation
// result.Info       -> missing optional/recommended fields (ShowMissingOptional)
// ParseOptions.Strict reports warnings and x-recommended fields as errors.

// CreateReport auto-fills xarf_version, report_id, and timestamp.
CreateReportResult created = XarfApi.CreateReport(input);

// CreateEvidence base64-encodes the payload and prefixes the hash with the algorithm.
Evidence ev = XarfApi.CreateEvidence(
    "message/rfc822", Encoding.UTF8.GetBytes(rawEmail),
    new EvidenceOptions { Description = "Original spam email", HashAlgorithm = "sha256" });
// ev.Payload (base64), ev.Hash ("sha256:<hex>"), ev.Size

Version constants: XarfApi.SpecVersion ("4.2.0"), XarfApi.BundledSpecVersion ("v4.2.0"), XarfApi.Version. The pre-existing typed Parser/Generator/Validator classes remain for backward compatibility; XarfApi is the recommended v4.2.0 surface.

🔧 Quick Start (legacy typed API)

Parsing XARF Reports

using Xarf;
using Xarf.Models;

// Initialize parser
var parser = new Parser();

// Parse a XARF report from JSON string
var reportJson = @"{
  ""xarf_version"": ""4.0.0"",
  ""report_id"": ""550e8400-e29b-41d4-a716-446655440000"",
  ""category"": ""content"",
  ""type"": ""phishing"",
  ""timestamp"": ""2024-01-15T14:30:00Z"",
  ""source_identifier"": ""203.0.113.45"",
  ""reporter"": {
    ""org"": ""Security Team"",
    ""contact"": ""abuse@example.com"",
    ""type"": ""automated""
  },
  ""evidence_source"": ""automated_scan"",
  ""url"": ""https://evil-site.example.com/phishing""
}";

var report = parser.Parse(reportJson);

// Access report data
Console.WriteLine($"Category: {report.Category}");
Console.WriteLine($"Type: {report.Type}");
Console.WriteLine($"Source: {report.SourceIdentifier}");

if (report is ContentReport contentReport)
{
    Console.WriteLine($"URL: {contentReport.Url}");
}

// Validate report structure
if (parser.Validate(reportJson))
{
    Console.WriteLine("✅ Report is valid");
}
else
{
    Console.WriteLine("❌ Validation errors:");
    foreach (var error in parser.GetErrors())
    {
        Console.WriteLine($"  - {error}");
    }
}

Generating XARF Reports

using Xarf;
using Xarf.Models;

// Initialize generator
var generator = new Generator();

// Generate a phishing report
var report = generator.CreateContentReport(
    reportType: "phishing_site",
    sourceIdentifier: "203.0.113.45",
    url: "https://evil-phishing.example.com/login",
    reporterContact: "abuse@security-lab.example",
    reporterOrg: "Security Research Lab",
    description: "Phishing site targeting banking customers"
);

// Add evidence
var evidence = new List<Evidence>
{
    generator.AddEvidence(
        contentType: "image/png",
        description: "Screenshot of phishing page",
        payload: "iVBORw0KGgoAAAANSUhEUg..." // base64 encoded
    )
};
report.Evidence = evidence;

// Serialize to JSON
var json = generator.ToJson(report);
Console.WriteLine(json);

📋 Features

Current (v1.1.0)

• ✅ Schema-driven validation against the embedded XARF v4.2.0 schemas, with strict mode, unknown-field warnings, and missing-optional info
• ✅ Parsing: result-object XarfApi.Parse (errors/warnings/info, no throw on validation failure), plus the legacy typed parser
• ✅ Generation: CreateReport (auto-filled metadata) and CreateEvidence (base64 payload, algorithm-prefixed hash, size)
• ✅ XARF v3 backward compatibility: automatic detection and conversion
• ✅ Category Support: all 7 XARF categories (messaging, connection, content, infrastructure, copyright, vulnerability, reputation)
• ✅ Runtimes: .NET 8, 9, 10 (verified in CI) plus netstandard2.1 consumers

Planned

• 🔮 CLI tools for validation and generation
• 🔮 ASP.NET Core middleware
• 🔮 Report signing and encryption
• 🔮 Multi-format export (XML, CSV)

📊 Supported Categories & Types

messaging

• spam - Email spam reports
• phishing - Phishing emails
• social_engineering - Social engineering attempts

connection

• ddos - Distributed denial of service attacks
• port_scan - Port scanning attempts
• login_attack - Brute force/credential attacks
• ip_spoofing - IP address spoofing

content

• phishing_site - Phishing websites
• malware_distribution - Malware hosting sites
• defacement - Website defacements
• spamvertised - Spam-advertised content
• web_hack - Web application attacks

🧪 Examples

Parse Email Spam Report

using Xarf;

var spamReport = @"{
    ""xarf_version"": ""4.0.0"",
    ""report_id"": ""a1b2c3d4-e5f6-7890-abcd-ef1234567890"",
    ""timestamp"": ""2024-01-15T10:30:00Z"",
    ""reporter"": {
        ""org"": ""Spam Detection Service"",
        ""contact"": ""noreply@spamdetect.example"",
        ""type"": ""automated""
    },
    ""source_identifier"": ""192.0.2.100"",
    ""category"": ""messaging"",
    ""type"": ""spam"",
    ""evidence_source"": ""spamtrap"",
    ""protocol"": ""smtp"",
    ""smtp_from"": ""spammer@badexample.com"",
    ""subject"": ""Get Rich Quick Scheme!""
}";

var parser = new Parser();
var report = parser.Parse(spamReport);

if (report is MessagingReport messaging)
{
    Console.WriteLine($"Detected {messaging.Type} from {messaging.SmtpFrom}");
}

Generate DDoS Report

using Xarf;

var generator = new Generator();

var ddosReport = generator.CreateConnectionReport(
    reportType: "ddos",
    sourceIdentifier: "203.0.113.50",
    destinationIp: "198.51.100.10",
    protocol: "tcp",
    reporterContact: "noc@example.com",
    reporterOrg: "Network Operations Center",
    destinationPort: 80,
    attackType: "syn_flood",
    description: "Volumetric SYN flood attack against web services"
);

ddosReport.DurationMinutes = 45;
ddosReport.PacketCount = 1500000;

Console.WriteLine($"Attack lasted {ddosReport.DurationMinutes} minutes");
Console.WriteLine($"Total packets: {ddosReport.PacketCount}");

Using OnBehalfOf for Infrastructure Providers

using Xarf;
using Xarf.Models;

var generator = new Generator();

// Infrastructure provider (Abusix) sending report for client (Swisscom)
var onBehalfOf = new Reporter
{
    Organization = "Swisscom",
    Contact = "abuse@swisscom.ch",
    Type = "manual"
};

var report = generator.GenerateReport(
    category: "messaging",
    reportType: "spam",
    sourceIdentifier: "192.0.2.150",
    reporterContact: "reports@abusix.com",
    reporterOrg: "Abusix",
    onBehalfOf: onBehalfOf,
    description: "Spam detected by Swisscom's infrastructure"
);

// The report clearly shows Abusix is reporting on behalf of Swisscom
Console.WriteLine($"Reporter: {report.Reporter.Organization}");
Console.WriteLine($"On behalf of: {report.Reporter.OnBehalfOf.Organization}");

🔍 Validation

The parser performs multiple validation levels:

1. JSON Structure - Structure and required fields
2. Data Types - Field type validation
3. Business Rules - Category-specific requirements
4. Evidence - Content type, size, and hash validation

using Xarf;
using Xarf.Exceptions;

// Non-strict mode: collect errors without raising exception
var parser = new Parser(strict: false);
var isValid = parser.Validate(reportJson);

if (!isValid)
{
    var errors = parser.GetErrors();
    foreach (var error in errors)
    {
        Console.WriteLine($"Error: {error}");
    }
}

// Strict mode: raise exception on first error
var strictParser = new Parser(strict: true);
try
{
    var report = strictParser.Parse(reportJson);
}
catch (XARFValidationException ex)
{
    Console.WriteLine($"Validation failed: {ex.Message}");
    foreach (var error in ex.Errors)
    {
        Console.WriteLine($"  - {error}");
    }
}

🔒 Security Best Practices

1. Always Validate Input

using Xarf;
using Xarf.Exceptions;

var parser = new Parser(strict: true);

void ProcessExternalReport(string reportJson)
{
    try
    {
        if (!parser.Validate(reportJson))
        {
            throw new ArgumentException($"Invalid report: {string.Join(", ", parser.GetErrors())}");
        }

        var report = parser.Parse(reportJson);
        // Process validated report
    }
    catch (XARFValidationException ex)
    {
        // Log validation errors
        Console.WriteLine($"Invalid XARF report received: {string.Join(", ", ex.Errors)}");
        throw;
    }
}

2. Limit Evidence Size

const long MaxEvidenceSize = 5 * 1024 * 1024;  // 5MB per evidence item
const long MaxTotalSize = 15 * 1024 * 1024;    // 15MB total

void ValidateEvidenceSize(XARFReport report)
{
    if (report.Evidence == null) return;

    long totalSize = 0;
    foreach (var evidenceItem in report.Evidence)
    {
        var itemSize = evidenceItem.Size ?? 0;

        if (itemSize > MaxEvidenceSize)
        {
            throw new ArgumentException($"Evidence item too large: {itemSize} bytes");
        }

        totalSize += itemSize;
    }

    if (totalSize > MaxTotalSize)
    {
        throw new ArgumentException($"Total evidence too large: {totalSize} bytes");
    }
}

3. Verify Evidence Hashes

using System.Security.Cryptography;
using System.Text;

bool VerifyEvidenceHash(Evidence evidence)
{
    if (string.IsNullOrEmpty(evidence.Hash))
    {
        return true; // Hash is optional
    }

    // Parse hash format: "algorithm:hexvalue"
    var parts = evidence.Hash.Split(':');
    if (parts.Length != 2) return false;

    var algorithm = parts[0];
    var expectedHash = parts[1];

    // Compute hash
    byte[] hashBytes = algorithm switch
    {
        "sha256" => SHA256.HashData(Encoding.UTF8.GetBytes(evidence.Payload)),
        "sha512" => SHA512.HashData(Encoding.UTF8.GetBytes(evidence.Payload)),
        "md5" => MD5.HashData(Encoding.UTF8.GetBytes(evidence.Payload)),
        _ => throw new ArgumentException($"Unsupported hash algorithm: {algorithm}")
    };

    var computedHash = BitConverter.ToString(hashBytes).Replace("-", "").ToLowerInvariant();
    return computedHash == expectedHash;
}

🧬 Development

# Clone repository
git clone https://github.com/xarf/xarf-csharp.git
cd xarf-csharp

# Restore dependencies
dotnet restore

# Build
dotnet build

# Run tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Format code
dotnet format

📚 Documentation

• XARF v4 Specification - Complete technical reference
• CHANGELOG - Version history and breaking changes
• Sample Reports - Real-world examples by category
• Common Fields - Field reference
• Best Practices - Implementation guidelines

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Bug Reports: Use GitHub Issues
• Feature Requests: Discuss in GitHub Discussions
• Pull Requests: Follow our coding standards
• Testing: Add tests for new features

📄 License

MIT License - See LICENSE for details.

🔗 Related Projects

• xarf-spec - XARF v4 specification and JSON schemas
• xarf-javascript - JavaScript/TypeScript implementation
• xarf-go - Go implementation
• xarf-python - Python implementation
• xarf.org - Official XARF website and documentation

📈 Versioning

This project follows independent semantic versioning, separate from the XARF specification version:

Library Versioning (this implementation)

• Current: 1.1.0
• The library version evolves independently of the XARF specification version.

XARF Specification Support

• Current: XARF v4.2.0 (check XarfApi.SpecVersion; embedded schema version via XarfApi.BundledSpecVersion)
• This library maintains compatibility with XARF spec updates through minor version increments.

💬 Support

• Documentation: https://xarf.org
• GitHub Issues: https://github.com/xarf/xarf-csharp/issues
• Discussions: https://github.com/xarf/xarf-spec/discussions
• Email: contact@xarf.org

Note: This library implements the official XARF v4 specification. Always refer to the specification for authoritative technical details.