Skip to content

SpiderFoot automates OSINT for threat intelligence and mapping your attack surface.

spiderfoot: events: Update docstrings and annotations (#1323)

bcolesd9d35fccdf8b
diff --git a/setup.cfg b/setup.cfg
index 3e06c196..171ad863 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,20 +1,22 @@
[flake8]
flake8-max-line-length = 120
max-complexity = 60
-select = C,E,F,W,I,B,DUO,D,R,A,S,Q0,SIM,SFS
+docstring-convention = google
+ignore-decorators = property
+select = C,E,F,W,I,B,B9,D,DAR,DUO,R,A,S,Q0,SIM,SFS
# Note: D and SIM tests should be reviewed and fixed instead of ignored
-ignore = E501 W503 B006 E800 SFS301 SF01 Q000 SIM102 SIM113 SIM115 D100 D104
+ignore = E501 W503 B006 E800 B950 SFS301 SF01 Q000 SIM102 SIM113 SIM115 D D100 D104 ANN
# Note: most of these should be fixed instead of ignored
per-file-ignores =
spiderfoot/event.py:A,D
spiderfoot/plugin.py:D,B902
- spiderfoot/db.py:D,SFS101,B902
+ spiderfoot/db.py:D,DAR,SFS101,B902
spiderfoot/helpers.py:D
spiderfoot/target.py:D
spiderfoot/logger.py:D
- sf.py:I,D,SFS201,B902
+ sf.py:I,D,DAR,SFS201,B902
sflib.py:I,D,SFS101,SIM110,SIM111,B902
- sfwebui.py:A,B902
+ sfwebui.py:A,B902,D212
sfscan.py:I,D,SIM105,B902
modules/*:D,B902
modules/sfp_binaryedge.py:D,B902,C901
@@ -24,8 +26,8 @@ per-file-ignores =
modules/sfp_ripe.py:D,SIM110,B902
modules/sfp_zetalytics.py:D,R504,B902
spiderfoot/__init__.py:I,D,F401
- sfcli.py:D,B902
- test/*:I,D,SIM117
+ sfcli.py:D,DAR,B902
+ test/*:I,D,SIM117,ANN
docs/conf.py:A,D
[darglint]
diff --git a/spiderfoot/event.py b/spiderfoot/event.py
index ba6c00b9..2072bb23 100644
--- a/spiderfoot/event.py
+++ b/spiderfoot/event.py
@@ -7,19 +7,19 @@ class SpiderFootEvent():
"""SpiderFootEvent object representing identified data and associated meta data.
Attributes:
- generated (float): timestamp of event creation time
- eventType (str): event type, e.g. URL_FORM, RAW_DATA, etc.
- confidence (int): how sure are we of this data's validity, 0-100
- visibility (int): how 'visible' was this data, 0-100
- risk (int): how much risk does this data represent, 0-100
- module (str): module from which the event originated
- data (str): event data, e.g. a URL, port number, webpage content, etc.
+ generated (float): Timestamp of event creation time
+ eventType (str): Event type, e.g. URL_FORM, RAW_DATA, etc.
+ confidence (int): How sure are we of this data's validity, 0-100
+ visibility (int): How 'visible' was this data, 0-100
+ risk (int): How much risk does this data represent, 0-100
+ module (str): Module from which the event originated
+ data (str): Event data, e.g. a URL, port number, webpage content, etc.
sourceEvent (SpiderFootEvent): SpiderFootEvent that triggered this event
- sourceEventHash (str): hash of the SpiderFootEvent event that triggered this event
- hash (str): unique SHA256 hash of the event, or "ROOT"
- moduleDataSource (str): module data source
- actualSource (str): source data of parent event
- __id: unique ID of the event, generated using eventType, generated, module, and a random integer
+ sourceEventHash (str): Hash of the SpiderFootEvent event that triggered this event
+ hash (str): Unique SHA256 hash of the event, or "ROOT"
+ moduleDataSource (str): Module data source
+ actualSource (str): Source data of parent event
+ __id (str): Unique ID of the event, generated using eventType, generated, module, and a random integer
"""
_generated = None
@@ -35,19 +35,18 @@ class SpiderFootEvent():
_actualSource = None
__id = None
- def __init__(self, eventType, data, module, sourceEvent, confidence=100, visibility=100, risk=0):
+ def __init__(self, eventType: str, data: str, module: str, sourceEvent: 'SpiderFootEvent', confidence: int = 100, visibility: int = 100, risk: int = 0) -> None:
"""Initialize SpiderFoot event object.
Args:
- eventType (str): event type, e.g. URL_FORM, RAW_DATA, etc.
- data (str): event data, e.g. a URL, port number, webpage content, etc.
- module (str): module from which the event originated
+ eventType (str): Event type, e.g. URL_FORM, RAW_DATA, etc.
+ data (str): Event data, e.g. a URL, port number, webpage content, etc.
+ module (str): Module from which the event originated
sourceEvent (SpiderFootEvent): SpiderFootEvent event that triggered this event
- confidence (int): how sure are we of this data's validity, 0-100
- visibility (int): how 'visible' was this data, 0-100
- risk (int): how much risk does this data represent, 0-100
+ confidence (int): How sure are we of this data's validity, 0-100
+ visibility (int): How 'visible' was this data, 0-100
+ risk (int): How much risk does this data represent, 0-100
"""
-
self._generated = time.time()
self.data = data
self.eventType = eventType
@@ -59,68 +58,77 @@ class SpiderFootEvent():
self.__id = f"{self.eventType}{self.generated}{self.module}{random.SystemRandom().randint(0, 99999999)}"
@property
- def generated(self):
- """
+ def generated(self) -> float:
+ """Timestamp of event creation time.
+
Returns:
float: timestamp of event creation time
"""
return self._generated
@property
- def eventType(self):
+ def eventType(self) -> str:
+ """Event type.
+
+ Returns:
+ str: event type
+ """
return self._eventType
@property
- def confidence(self):
- """
+ def confidence(self) -> int:
+ """How sure are we of this data's validity.
+
Returns:
- int: How sure are we of this data's validity (0 to 100)
+ int: confidence score (0 to 100).
"""
return self._confidence
@property
- def visibility(self):
- """
+ def visibility(self) -> int:
+ """How 'visible' was this data (0 to 100).
+
Returns:
- int: How 'visible' was this data (0 to 100)
+ int: visibility score (0 to 100).
"""
return self._visibility
@property
- def risk(self):
- """
+ def risk(self) -> int:
+ """How much risk does this data represent.
+
Returns:
- int: How much risk does this data represent (0 to 100)
+ int: risk score (0 to 100).
"""
return self._risk
@property
- def module(self):
+ def module(self) -> str:
return self._module
@property
- def data(self):
+ def data(self) -> str:
return self._data
@property
- def sourceEvent(self):
+ def sourceEvent(self) -> 'SpiderFootEvent':
return self._sourceEvent
@property
- def sourceEventHash(self):
+ def sourceEventHash(self) -> str:
return self._sourceEventHash
@property
- def actualSource(self):
+ def actualSource(self) -> str:
return self._actualSource
@property
- def moduleDataSource(self):
+ def moduleDataSource(self) -> str:
return self._moduleDataSource
@property
- def hash(self):
- """Unique hash of this event.
+ def hash(self) -> str:
+ """Unique SHA256 hash of the event, or "ROOT".
Returns:
str: unique SHA256 hash of the event, or "ROOT"
@@ -132,8 +140,9 @@ class SpiderFootEvent():
return hashlib.sha256(digestStr).hexdigest()
@eventType.setter
- def eventType(self, eventType):
- """
+ def eventType(self, eventType: str) -> None:
+ """Event type.
+
Args:
eventType (str): type of data for this event
@@ -141,7 +150,6 @@ class SpiderFootEvent():
TypeError: confidence type was invalid
ValueError: confidence value was invalid
"""
-
if not isinstance(eventType, str):
raise TypeError(f"eventType is {type(eventType)}; expected str()")
@@ -151,16 +159,16 @@ class SpiderFootEvent():
self._eventType = eventType
@confidence.setter
- def confidence(self, confidence):
- """
+ def confidence(self, confidence: int) -> None:
+ """Event confidence.
+
Args:
- confidence (int): How sure are we of this data's validitya(0 to 100)
+ confidence (int): How sure are we of this data's validity (0 to 100)
Raises:
TypeError: confidence type was invalid
ValueError: confidence value was invalid
"""
-
if not isinstance(confidence, int):
raise TypeError(f"confidence is {type(confidence)}; expected int()")
@@ -170,8 +178,9 @@ class SpiderFootEvent():
self._confidence = confidence
@visibility.setter
- def visibility(self, visibility):
- """
+ def visibility(self, visibility: int) -> None:
+ """Event visibility.
+
Args:
visibility (int): How 'visible' was this data (0 to 100)
@@ -179,7 +188,6 @@ class SpiderFootEvent():
TypeError: visibility type was invalid
ValueError: visibility value was invalid
"""
-
if not isinstance(visibility, int):
raise TypeError(f"visibility is {type(visibility)}; expected int()")
@@ -189,8 +197,9 @@ class SpiderFootEvent():
self._visibility = visibility
@risk.setter
- def risk(self, risk):
- """
+ def risk(self, risk: int) -> None:
+ """Event risk.
+
Args:
risk (int): How much risk does this data represent (0 to 100)
@@ -198,7 +207,6 @@ class SpiderFootEvent():
TypeError: risk type was invalid
ValueError: risk value was invalid
"""
-
if not isinstance(risk, int):
raise TypeError(f"risk is {type(risk)}; expected int()")
@@ -208,8 +216,9 @@ class SpiderFootEvent():
self._risk = risk
@module.setter
- def module(self, module):
- """
+ def module(self, module: str) -> None:
+ """Module which created the event.
+
Args:
module (str): module
@@ -217,7 +226,6 @@ class SpiderFootEvent():
TypeError: module type was invalid
ValueError: module value was invalid
"""
-
if not isinstance(module, str):
raise TypeError(f"module is {type(module )}; expected str()")
@@ -228,8 +236,8 @@ class SpiderFootEvent():
self._module = module
@data.setter
- def data(self, data):
- """Event data
+ def data(self, data: str) -> None:
+ """Event data.
Args:
data (str): data
@@ -238,7 +246,6 @@ class SpiderFootEvent():
TypeError: data type was invalid
ValueError: data value was invalid
"""
-
if not isinstance(data, str):
raise TypeError(f"data is {type(data)}; expected str()")
@@ -248,8 +255,8 @@ class SpiderFootEvent():
self._data = data
@sourceEvent.setter
- def sourceEvent(self, sourceEvent):
- """source event
+ def sourceEvent(self, sourceEvent: 'SpiderFootEvent') -> None:
+ """Source event which lead to this event.
Args:
sourceEvent (SpiderFootEvent): source event
@@ -257,7 +264,6 @@ class SpiderFootEvent():
Raises:
TypeError: sourceEvent type was invalid
"""
-
# "ROOT" is a special "hash" reserved for elements with no parent,
# such as targets provided via the web UI or CLI.
if self.eventType == "ROOT":
@@ -272,19 +278,19 @@ class SpiderFootEvent():
self._sourceEventHash = self.sourceEvent.hash
@actualSource.setter
- def actualSource(self, actualSource):
+ def actualSource(self, actualSource: str) -> None:
self._actualSource = actualSource
@moduleDataSource.setter
- def moduleDataSource(self, moduleDataSource):
+ def moduleDataSource(self, moduleDataSource: str) -> None:
self._moduleDataSource = moduleDataSource
- def asDict(self):
- """
+ def asDict(self) -> dict:
+ """Event object as dictionary.
+
Returns:
dict: event as dictionary
"""
-
evtDict = {
'generated': int(self.generated),
'type': self.eventType,
@@ -299,8 +305,8 @@ class SpiderFootEvent():
return evtDict
- def getHash(self):
- """Event hash
+ def getHash(self) -> str:
+ """Unique SHA256 hash of the event or "ROOT".
Note: required for SpiderFoot HX compatibility of modules.