n6sdk.data_spec¶

Note

For basic information how to use the classes defined in this module – please consult the Data specification class chapter of the tutorial.

n6sdk.data_spec.RESTRICTION_ENUMS = ('public', 'need-to-know', 'internal')¶: A tuple of network incident data distribution restriction qualifiers – used in the DataSpec.restriction field specification.

n6sdk.data_spec.CONFIDENCE_ENUMS = ('low', 'medium', 'high')¶: A tuple of network incident data confidence qualifiers – used in the DataSpec.confidence field specification.

n6sdk.data_spec.CATEGORY_ENUMS = ('amplifier', 'bots', 'backdoor', 'cnc', 'dns-query', 'dos-attacker', 'dos-victim', 'flow', 'flow-anomaly', 'fraud', 'leak', 'malurl', 'malware-action', 'phish', 'proxy', 'sandbox-url', 'scanning', 'server-exploit', 'spam', 'spam-url', 'tor', 'vulnerable', 'webinject', 'other')¶: A tuple of network incident category labels – used in the DataSpec.category field specification.

n6sdk.data_spec.PROTO_ENUMS = ('tcp', 'udp', 'icmp')¶: A tuple of network incident layer-#4-protocol labels – used in the DataSpec.proto field specification.

n6sdk.data_spec.ORIGIN_ENUMS = ('c2', 'dropzone', 'proxy', 'p2p-crawler', 'p2p-drone', 'sinkhole', 'sandbox', 'honeypot', 'darknet', 'av', 'ids', 'waf')¶: A tuple of network incident origin labels – used in the DataSpec.origin field specification.

n6sdk.data_spec.STATUS_ENUMS = ('active', 'delisted', 'expired', 'replaced')¶: A tuple of black list item status qualifiers – used in the DataSpec.status field specification.

class n6sdk.data_spec.Ext[source]¶

Bases: dict

An auxiliary class of a dict-like container – to be used to extend field specifications in DataSpec subclasses (for usage examples, see the descriptions of DataSpec and AllSearchableDataSpec).

copy()[source]¶

make_extended_field(field)[source]¶

nondestructive_update(other)[source]¶

class n6sdk.data_spec.BaseDataSpec(**kwargs)[source]¶

Bases: object

The base class for data specification classes.

Typically, you will not instantiate or subclass this class directly – instead, you may want to use DataSpec or, more likely, a subclass of it.

all_keys¶

Instance property: a frozenset of all keys.

(Includes all legal parameter names and result keys.)

all_param_keys¶: Instance property: a frozenset of all legal parameter names.

all_result_keys¶: Instance property: a frozenset of all legal result keys.

clean_param_dict(params, ignored_keys=(), forbidden_keys=(), extra_required_keys=(), discarded_keys=())[source]¶

clean_param_keys(params, ignored_keys=(), forbidden_keys=(), extra_required_keys=(), discarded_keys=())[source]¶

param_field_specs(which='all', multi=True, single=True)[source]¶

clean_result_dict(result, ignored_keys=(), forbidden_keys=(), extra_required_keys=(), discarded_keys=())[source]¶

clean_result_keys(result, ignored_keys=(), forbidden_keys=(), extra_required_keys=(), discarded_keys=())[source]¶

result_field_specs(which='all')[source]¶

get_adjusted_field(key, field, ext=None)[source]¶

class n6sdk.data_spec.DataSpec(**kwargs)[source]¶

Bases: n6sdk.data_spec.BaseDataSpec

The basic, ready-to-use, data specification class.

Typically, you will want to create a subclass of it (note that, by default, all fields are disabled as query parameters, so you may want to enable some of them). For example:

class MyDataSpec(DataSpec):

    # enable `source` as a query parameter
    source = Ext(in_params='optional')

    # enable the `time.min` and `time.until` query parameters
    # (leaving `time.max` still disabled)
    time = Ext(
        extra_params=Ext(
            min=Ext(in_params='optional'),
            until=Ext(in_params='optional'),
        ),
    )

    # enable `fqdn` and `fqdn.sub` as query parameters
    # and add a new query parameter: `fqdn.prefix`
    fqdn = Ext(
        in_params='optional',
        extra_params=Ext(
            sub=Ext(in_params='optional'),
            prefix=DomainNameSubstringField(in_params='optional'),
        ),
    )

    # completely disable the `modified` field
    modified = None

    # add a new field
    weekday = UnicodeEnumField(
        in_params='optional',
        in_result='optional',
        enum_values=(
            'Monday', 'Tuesday', 'Wednesday', 'Thursday',
            'Friday', 'Saturday', 'Sunday'),
        ),
    )

See also

Compare this class with AllSearchableDataSpec.

id = UnicodeLimitedField(in_result='required', max_length=64)¶

source = SourceField(in_result='required')¶

restriction = UnicodeEnumField(enum_values=('public', 'need-to-know', 'internal'), in_result='required')¶

confidence = UnicodeEnumField(enum_values=('low', 'medium', 'high'), in_result='required')¶

category = UnicodeEnumField(enum_values=('amplifier', 'bots', 'backdoor', 'cnc', 'dns-query', 'dos-attacker', 'dos-victim', 'flow', 'flow-anomaly', 'fraud', 'leak', 'malurl', 'malware-action', 'phish', 'proxy', 'sandbox-url', 'scanning', 'server-exploit', 'spam', 'spam-url', 'tor', 'vulnerable', 'webinject', 'other'), in_result='required')¶

time = DateTimeField(extra_params={'max': DateTimeField(single_param=True), 'until': DateTimeField(single_param=True), 'min': DateTimeField(single_param=True)}, in_params=None, in_result='required')¶

address = ExtendedAddressField(in_params=None, in_result='optional')¶

ip = IPv4Field(extra_params={'net': IPv4NetField()}, in_result=None)¶

ipv6 = IPv6Field(extra_params={'net': IPv6NetField()}, in_result=None)¶

asn = ASNField(in_result=None)¶

cc = CCField(in_result=None)¶

active = Field(extra_params={'max': DateTimeField(single_param=True), 'until': DateTimeField(single_param=True), 'min': DateTimeField(single_param=True)}, in_params=None, in_result=None)¶

expires = DateTimeField(in_params=None, in_result='optional')¶

replaces = UnicodeLimitedField(in_result='optional', max_length=64)¶

status = UnicodeEnumField(enum_values=('active', 'delisted', 'expired', 'replaced'), in_result='optional')¶

count = IntegerField(in_params=None, in_result='optional', max_value=32767, min_value=0)¶

until = DateTimeField(in_params=None, in_result='optional')¶

action = UnicodeLimitedField(in_result='optional', max_length=32)¶

adip = AnonymizedIPv4Field(in_result='optional')¶

dip = IPv4Field(in_result='optional')¶

dport = PortField(in_result='optional')¶

email = EmailSimplifiedField(in_result='optional')¶

fqdn = DomainNameField(extra_params={'sub': DomainNameSubstringField()}, in_result='optional')¶

iban = IBANSimplifiedField(in_result='optional')¶

injects = ListOfDictsField(in_params=None, in_result='optional')¶

md5 = MD5Field(in_result='optional')¶

modified = DateTimeField(extra_params={'max': DateTimeField(single_param=True), 'until': DateTimeField(single_param=True), 'min': DateTimeField(single_param=True)}, in_params=None, in_result='optional')¶

name = UnicodeLimitedField(in_result='optional', max_length=255)¶

origin = UnicodeEnumField(enum_values=('c2', 'dropzone', 'proxy', 'p2p-crawler', 'p2p-drone', 'sinkhole', 'sandbox', 'honeypot', 'darknet', 'av', 'ids', 'waf'), in_result='optional')¶

phone = UnicodeLimitedField(in_result='optional', max_length=20)¶

proto = UnicodeEnumField(enum_values=('tcp', 'udp', 'icmp'), in_result='optional')¶

registrar = UnicodeLimitedField(in_result='optional', max_length=100)¶

sha1 = SHA1Field(in_result='optional')¶

sport = PortField(in_result='optional')¶

target = UnicodeLimitedField(in_result='optional', max_length=100)¶

url = URLField(extra_params={'sub': URLSubstringField()}, in_result='optional')¶

url_pattern = UnicodeLimitedField(disallow_empty=True, in_result='optional', max_length=255)¶

username = UnicodeLimitedField(in_result='optional', max_length=64)¶

x509fp_sha1 = SHA1Field(in_result='optional')¶

class n6sdk.data_spec.AllSearchableDataSpec(**kwargs)[source]¶

Bases: n6sdk.data_spec.DataSpec

A DataSpec subclass with most of its fields marked as searchable.

You may want to use this class instead of DataSpec if your data backend makes it easy to search by various event attributes (all relevant ones or most of them).

Typically, you will want to create your own subclass of AllSearchableDataSpec (especially to disable some searchable parameters). For example:

class MyDataSpec(AllSearchableDataSpec):

    # disable `source` as a query parameter
    source = Ext(in_params=None)

    # disable the `time.max` query parameter
    # (leaving `time.min` and `time.until` still enabled)
    time = Ext(
        extra_params=Ext(
            max=Ext(in_params=None),
        ),
    )

    # disable the `fqdn.sub` query parameter and, at the
    # same time, add a new query parameter: `fqdn.prefix`
    fqdn = Ext(
        extra_params=Ext(
            sub=Ext(in_params=None),
            prefix=DomainNameSubstringField(in_params='optional'),
        ),
    )

    # completely disable the `modified` field (together with the
    # related "extra params": `modified.min` etc.)
    modified = None

    # add a new field
    weekday = UnicodeEnumField(
        in_params='optional',
        in_result='optional',
        enum_values=(
            'Monday', 'Tuesday', 'Wednesday', 'Thursday',
            'Friday', 'Saturday', 'Sunday'),
        ),
    )