Skip to main content

pyxarf - easy x-arf report generation

Project description

PyPi Version PyPi License PyPi Versions PyPi Wheel

pyxarf - easy x-arf report generation

Introduction

pyxarf is a Python library for handling X-ARF Network Abuse Reporting.

  • pyxarf: A module for creating, validating and serializing X-ARF objects.
  • xarfmail: A module for sending X-ARF reports by E-Mail, with automatic Abuse Contact lookup provided by the free querycontacts library.
  • xarfutil: A command line client for reporting in X-ARF directly from the Shell.

For more information on the reporting format X-ARF, check out it's offical website.

Getting Started

Installation

pip install pyxarf

Calling the Script

Report-Generation

In this first example, all required parameters for generating a X-ARF report are specified directly at command line. Using the --output-yaml parameter, the validated report data is printed to stdout in YAML format.

$ xarfutil.py --evidence 'sample evidence data' --greeting 'greeting text here' \
    --schema-url 'http://xarf.org/schema/abuse_login-attack_0.1.2.json' \
    --schema-cache '/tmp/' --reported-from 'xarf-reports@example.com' \
    --category 'abuse' --report-type 'login-attack' --report-id '1234567' \
    --date 'Feb  3 2014 02:13:35 +0100' --source '83.169.54.26' \
    --source-type 'ip-address' --attachment 'text/plain' --service 'ssh' \
    --port 22 --output-yaml

evidence: sample evidence data
machine_readable:
    Attachment: text/plain
    Category: abuse
    Date: Feb  3 2014 02:13:35 +0100
    Port: 22
    Report-ID: '1234567'
    Report-Type: login-attack
    Reported-From: xarf-reports@example.com
    Schema-URL: http://xarf.org/schema/abuse_login-attack_0.1.2.json
    Service: ssh
    Source: 83.169.54.26
    Source-Type: ip-address
    User-Agent: pyxarf 0.0.1

Sending Reports

You can send reports using the script by adding specific parameters.

$ xarfutil.py --evidence 'sample evidence data' \
--greeting 'greeting text here' \
--schema-url 'http://xarf.org/schema/abuse_login-attack_0.1.2.json' \
--schema-cache '/tmp/' --reported-from 'xarf@example.org' \
--category 'abuse' --report-type 'login-attack' --report-id '1234567' \
--date 'Feb  3 2014 02:13:35 +0100' --source '83.169.54.26' \
--source-type 'ip-address' --attachment 'text/plain' --service 'ssh' \
--port 22 --mail-server-host mx.example.org --mail-server-port 25 \
--mail-from 'xarf@example.org' --mail-subject 'x-arf sample report' \
--mail-to 'abuse@example.com' --send-email

Report sent.

You can also lookup the abuse contact for a given IP by adding the parameter --lookup-contact.

Using the API

from __future__ import print_function

from pyxarf import Xarf

xarf = Xarf(
    evidence='sample evidence data',
    greeting='greeting text here',
    schema_url='http://www.xarf.org/schema/abuse_login-attack_0.1.2.json',
    schema_cache='/tmp/',
    reported_from='xarf-reports@example.com',
    category='abuse',
    report_type='login-attack',
    report_id='1234567',
    date='Feb  3 2014 02:13:35 +0100',
    source='83.169.54.26',
    source_type='ip-address',
    attachment='text/plain',
    service='ssh',
    port=22,
)

print(xarf.to_json()) # return json
print()
print(xarf.to_yaml()) # return yaml
print()
print(xarf.get_report_obj()) # return python object (dict)

Output:

$ python sample.py
{"machine_readable": {"Reported-From": "xarf-reports@example.com", "Report-ID": "1234567", "Category": "abuse", "Report-Type": "login-attack", "Service": "ssh", "Port": 22, "Date": "Feb  3 2014 02:13:35 +0100", "Source": "83.169.54.26", "Source-Type": "ip-address", "Attachment": "text/plain", "Schema-URL": "http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json", "User-Agent": "pyxarf 0.0.5"}, "evidence": "sample evidence data"}

evidence: sample evidence data
machine_readable:
  Attachment: text/plain
  Category: abuse
  Date: Feb  3 2014 02:13:35 +0100
  Port: 22
  Report-ID: '1234567'
  Report-Type: login-attack
  Reported-From: xarf-reports@example.com
  Schema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json
  Service: ssh
  Source: 83.169.54.26
  Source-Type: ip-address
  User-Agent: pyxarf 0.0.5


{'machine_readable': {'Reported-From': 'xarf-reports@example.com', 'Report-ID': '1234567', 'Category': 'abuse', 'Report-Type': 'login-attack', 'Service': 'ssh', 'Port': 22, 'Date': 'Feb  3 2014 02:13:35 +0100', 'Source': '83.169.54.26', 'Source-Type': 'ip-address', 'Attachment': 'text/plain', 'Schema-URL': 'http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json', 'User-Agent': 'pyxarf 0.0.5'}, 'evidence': 'sample evidence data'}

Detecting Errors

The following example contains a error on line 17, as the specified JSON schema definies port to be a integer.

from __future__ import print_function

from pyxarf import Xarf

xarf = Xarf(
    evidence='sample evidence data',
    greeting='greeting text here',
    schema_url='http://www.xarf.org/schema/abuse_login-attack_0.1.2.json',
    schema_cache='/tmp/',
    reported_from='xarf-reports@example.com',
    category='abuse',
    report_type='login-attack',
    report_id='1234567',
    date='Feb  3 2014 02:13:35 +0100',
    source='83.169.54.26',
    source_type='ip-address',
    attachment='text/plain',
    service='ssh',
    port='22',
)

print(xarf.to_json())

Output:

$ python sample.py
Traceback (most recent call last):
  File "sample.py", line 22, in <module>
    print(xarf.to_json())
  File "/home/user/dev/python-xarf/pyxarf/xarf.py", line 362, in to_json
    return json_dumps(self.get_report_obj(part))
  File "/home/user/dev/python-xarf/pyxarf/xarf.py", line 395, in get_report_obj
    'machine_readable': self._get_validated_machine_readable(),
  File "/home/user/dev/python-xarf/pyxarf/xarf.py", line 338, in _get_validated_machine_readable
    self.machine_readable
  File "/home/user/dev/python-xarf/pyxarf/xarf.py", line 290, in _validate_schema
    ', '.join(errors)
pyxarf.exceptions.ValidationError: Port '22' is not of type 'integer'

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyxarf, version 0.1.0
Filename, size & hash File type Python version Upload date
pyxarf-0.1.0-py2.py3-none-any.whl (13.5 kB) View hashes Wheel py2.py3
pyxarf-0.1.0.tar.gz (14.1 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page