Fides Module

.gitignore

@@ -172,3 +172,8 @@ output/
 config-live-macos-*
 dataset-private/*
 appendonly.aof
+/slipsOut/flows.sqlite
+/slipsOut/metadata/info.txt
+/slipsOut/metadata/slips.yaml
+/slipsOut/metadata/whitelist.conf
+/p2p_db.sqlite

docs/fides_module.md

@@ -0,0 +1,50 @@
+# Fides module
+
+Traditional network defense systems depend on centralized threat intelligence, which has limitations like single points of failure, inflexibility, and reliance on trust in centralized authorities. Peer-to-peer networks offer an alternative for sharing threat intelligence but face challenges in verifying the trustworthiness of participants, including potential malicious actors.
+
+The Fides Module, based on [research](https://github.com/stratosphereips/fides/tree/bfac47728172d3a4bbb27a5bb53ceef424e45e4f) by Lukáš Forst, addresses these challenges by providing a trust model for peer-to-peer networks. It evaluates peer behavior, considers membership in trusted organizations, and assesses incoming threat data to determine reliability. Fides aggregates and weights data to enhance intrusion prevention systems, even in adversarial scenarios. Experiments show that Fides can maintain accurate threat intelligence even when 75% of the network is controlled by malicious actors, assuming the remaining 25% are trusted.
+## How to use
+### **Communication**
+The module uses Slips' Redis to receive and send messages related to trust and P2P connection and data evaluation.
+
+**Used Channels**
+
+| **Slips Channel Name** | **Purpose**                                                             |
+|-----------------|-------------------------------------------------------------------------|
+| `slips2fides`   | Provides communication channel from Slips to Fides                      |
+| `fides2slips`   | Enables the Fides Module to answer requests from slips2fides            |
+| `network2fides` | Facilitates communication from network (P2P) module to the Fides Module |
+| `fides2network` | Lets the Fides Module request network opinions form network modules     |
+
+For more details, the code [here](https://github.com/stratosphereips/fides/tree/bfac47728172d3a4bbb27a5bb53ceef424e45e4f/fides/messaging) may be read.
+
+
+### **Messages**
+
+| **Message type (data['type'])** | **Channel**     | **Call/Handle**                                                                                                       | **Description**                                                                                       |
+|:-------------------------------:|-----------------|-----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+|             `alert`             | `slips2fides`   | FidesModule as self.__alerts.dispatch_alert(target=data['target'], confidence=data['confidence'],score=data['score']) | Triggers sending an alert to the network, about given target, which SLips believes to be compromised. |
+|     `intelligence_request`      | `slips2fides`   | FidesModule as self.__intelligence.request_data(target=data['target'])                                                | Triggers request of trust intelligence on given target.                                               |
+|          `tl2nl_alert`          | `fides2network` | call dispatch_alert() of AlertProtocol class instance                                                                 | Broadcasts alert through the network about the target.                                                |
+|  `tl2nl_intelligence_response`  | `fides2network` | NetworkBridge.send_intelligence_response(...)                                                                         | Shares Intelligence with peer that requested it.                                                      |
+|  `tl2nl_intelligence_request`   | `fides2network` | NetworkBridge.send_intelligence_request(...)                                                                          | Requests network intelligence from the network regarding this target.                                 |
+| `tl2nl_recommendation_response` | `fides2network` | NetworkBridge.send_recommendation_response(...)                                                                       | Responds to given request_id to recipient with recommendation on target.                              |
+| `tl2nl_recommendation_request`  | `fides2network` | NetworkBridge.send_recommendation_request(...)                                                                        | Request recommendation from recipients on given peer.                                                 |
+|    `tl2nl_peers_reliability`    | `fides2network` | NetworkBridge.send_peers_reliability(...)                                                                             | Sends peer reliability, this message is only for network layer and is not dispatched to the network.  |
+
+
+Implementations of Fides_Module-network-communication can be found in modules/fidesModule/messaging/network_bridge.py.
+
+### Configuration
+Evaluation model, evaluation thrash-holds and other configuration is located in fides.conf.yml 
+
+**Possible threat intelligence evaluation models**
+
+| **Model Name**         | **Description**                                                  |
+|:-----------------------|--------------------------------------------------------------|
+| `average`              | Average Confidence Trust Intelligence Aggregation            |
+| `weightedAverage`      | Weighted Average Confidence Trust Intelligence Aggregation   |
+| `stdevFromScore`       | Standard Deviation From Score Trust Intelligence Aggregation |
+
+## Implementation notes and credit
+The mathematical models for trust evaluation were written by Lukáš Forst as part of his theses and can be accessed [here](https://github.com/LukasForst/fides/commits?author=LukasForst).

modules/fidesModule/__init__.py

@@ -0,0 +1 @@
+# This module contains code that is necessary for Slips to use the Fides trust model

modules/fidesModule/config/fides.conf.yml

@@ -0,0 +1,150 @@
+# This is main configuration file for the trust model
+# NOTE: if you update this file' structure, you need to update fides.model.configuration.py parsing as well
+
+# Settings related to running inside slips
+slips:
+
+# settings related to network protocol
+network:
+
+# Values that define this instance of Fides
+my:
+  id: myId
+  organisations: [ ]
+
+# Confidentiality related settings
+confidentiality:
+  # possible levels of data that are labeled by Slips
+  # the value defines how secret the data are where 0 (can be shared
+  # with anybody) and 1 (can not be shared at all)
+  #
+  # the checks are: if(entity.confidentiality_level >= data.confidentiality_level) allowData()
+  # see https://www.cisa.gov/tlp
+  levels:
+    # share all data
+    - name: WHITE # name of the level, used mainly for debugging purposes
+      value: 0    # value that is used during computation
+    - name: GREEN
+      value: 0.2
+    - name: AMBER
+      value: 0.5
+    - name: RED
+      value: 0.7
+    # do not share anything ever
+    - name: PRIVATE
+      value: 1.1 # never meets condition peer.privacyLevel >= data.level as peer.privacyLevel <0, 1>
+
+  # if some data are not labeled, what value should we use
+  defaultLevel: 0
+
+  # rules that apply when the model is filtering data for peers
+  thresholds:
+    - level: 0.2          # for this level (and all levels > this) require
+      requiredTrust: 0.2  # this trust
+    - level: 0.5
+      requiredTrust: 0.5
+    - level: 0.7
+      requiredTrust: 0.8
+    - level: 1
+      requiredTrust: 1
+
+# Trust model related settings
+trust:
+  # service trust evaluation
+  service:
+    # initial reputation that is assigned for every peer when there's new encounter
+    initialReputation: 0.5
+
+    # maximal size of Service History, sh_max
+    historyMaxSize: 100
+
+  # settings for recommendations
+  recommendations:
+    # if the recommendation protocol should be executed
+    enabled: True
+    # when selecting recommenders, use only the ones that are currently connected
+    useOnlyConnected: False
+    # if true, protocol will only ask pre-trusted peers / organisations for recommendations
+    useOnlyPreconfigured: False
+    # require minimal number of trusted connected peers before running recommendations
+    # valid only if trust.recommendations.useOnlyPreconfigured == False
+    requiredTrustedPeersCount: 1
+    # minimal trust for trusted peer
+    # valid only if trust.recommendations.useOnlyPreconfigured == False
+    trustedPeerThreshold: 0.8
+    # maximal count of peers that are asked to give recommendations on a peer, η_max
+    peersMaxCount: 100
+    # maximal size of Recommendation History, rh_max
+    historyMaxSize: 100
+
+  # alert protocol
+  alert:
+    # how much should we trust an alert that was sent by peer we don't know anything about
+    defaultTrust: 0.5
+
+  # trust these organisations with given trust by default
+  organisations:
+    - id: org1                  # public key of the organisation
+      name: Organisation \#1    # name
+      trust: 0.1                # how much should the model trust peers from this org
+      enforceTrust: True        # whether to allow (if false) changing trust during runtime (when we received more data from org)
+      confidentialityLevel: 0.7 # what level of data should be shared with peers from this org, see privacy.levels
+
+    - id: org2
+      name: Organisation \#2
+      trust: 0.9
+      enforceTrust: False
+      confidentialityLevel: 0.9
+
+  # trust these peers with given trust by default
+  # see doc for trust.organisations
+  peers:
+    - id: peer1
+      name: Peer \#1
+      trust: 0.1
+      enforceTrust: True
+      confidentialityLevel: 0.7
+
+    - id: peer2
+      name: Peer \#2
+      trust: 0.9
+      enforceTrust: False
+      confidentialityLevel: 0.9
+
+  # how many minutes is network opinion considered valid
+  networkOpinionCacheValidSeconds: 3600
+
+  # which strategy should be used to evaluate interaction when peer provided threat intelligence on a target
+  # see fides.evaluation.ti_evaluation.py for options
+  # options: ['even', 'distance', 'localDistance', 'threshold', 'maxConfidence', 'weighedDistance']
+  interactionEvaluationStrategies:
+    used: 'threshold'
+    # these are configuration for the strategies, content will be passed as a **kwargs to the instance
+    # even strategy uses the same satisfaction value for every interaction
+    even:
+      # value used as a default satisfaction for all peers
+      satisfaction: 1
+    # distance measures distance between aggregated network intelligence and each intelligence from the peers
+    distance:
+    # localDistance measures distance between each peer's intelligence to local threat intelligence by Slips
+    localDistance:
+    # weighedDistance combines distance and localDistance with given weight
+    weighedDistance:
+      # weight of the local TI to TI aggregated from the network
+      localWeight: 0.4
+    # maxConfidence uses combination of distance, localDistance and even - utilizes their confidence to
+    # make decisions with the highest possible confidence
+    maxConfidence:
+    # threshold employs 'lower' value strategy when the confidence of the aggregated TI is lower than 'threshold',
+    # otherwise it uses 'higher' - 'even' and 'distance' strategies work best with this
+    threshold:
+      # minimal confidence level
+      threshold: 0.7
+      # this strategy is used when the aggregated confidence is lower than the threshold
+      lower: 'even'
+      # and this one when it is higher
+      higher: 'distance'
+
+  # Threat Intelligence aggregation strategy
+  # valid values - ['average', 'weightedAverage', 'stdevFromScore']
+  tiAggregationStrategy: 'average'

modules/fidesModule/evaluation/README.md

@@ -0,0 +1 @@
+All algorithms in this package are based on SORT - see paper.

modules/fidesModule/evaluation/discount_factor.py

@@ -0,0 +1,9 @@
+def compute_discount_factor() -> float:
+    """
+    Computes discount factor used for `competence + (discount) * integrity` to lower
+    the expectations of current peer for future interaction.
+
+    :return: discount factor for integrity
+    """
+    # arbitrary value -1/2 explained in the paper
+    return -0.5

modules/fidesModule/evaluation/recommendation/new_history.py

@@ -0,0 +1,78 @@
+from ...model.configuration import TrustModelConfiguration
+from ...model.peer_trust_data import PeerTrustData
+from ...model.recommendation import Recommendation
+from ...model.recommendation_history import RecommendationHistoryRecord, RecommendationHistory
+from ...utils.time import now
+
+
+def create_recommendation_history_for_peer(
+        configuration: TrustModelConfiguration,
+        peer: PeerTrustData,
+        recommendation: Recommendation,
+        history_factor: float,
+        er_ij: float,
+        ecb_ij: float,
+        eib_ij: float
+) -> RecommendationHistory:
+    """
+    Creates new recommendation_history for given peer and its recommendations.
+
+    :param configuration: configuration for current trust model
+    :param peer: peer "k" which provided recommendation r
+    :param recommendation: recommendation provided by peer k
+    :param history_factor: int(mean(size of history) / maximal history size)
+    :param er_ij: estimation about reputation
+    :param ecb_ij: estimation about competence belief
+    :param eib_ij: estimation about integrity belief
+    :return:
+    """
+    rs_ik = __compute_recommendation_satisfaction_parameter(recommendation, er_ij, ecb_ij, eib_ij)
+    rw_ik = __compute_weight_of_recommendation(configuration, recommendation, history_factor)
+
+    updated_history = peer.recommendation_history + [RecommendationHistoryRecord(satisfaction=rs_ik,
+                                                                                 weight=rw_ik,
+                                                                                 timestamp=now())]
+    # fix history len if we reached max size
+    if len(updated_history) > configuration.recommendations.history_max_size:
+        last_idx = len(updated_history)
+        updated_history = updated_history[last_idx - configuration.recommendations.history_max_size: last_idx]
+
+    return updated_history
+
+
+def __compute_recommendation_satisfaction_parameter(
+        recommendation: Recommendation,
+        er_ij: float,
+        ecb_ij: float,
+        eib_ij: float
+) -> float:
+    """
+    Computes satisfaction parameter - how much was peer satisfied with provided data.
+
+    :param recommendation: recommendation from the peer
+    :param er_ij: estimation about reputation
+    :param ecb_ij: estimation about competence belief
+    :param eib_ij: estimation about integrity belief
+    :return: recommendation satisfaction rs_ik
+    """
+    r_diff = (1 - abs(recommendation.recommendation - er_ij) / er_ij) if er_ij > 0 else 0
+    cb_diff = (1 - abs(recommendation.competence_belief - ecb_ij) / ecb_ij) if ecb_ij > 0 else 0
+    ib_diff = (1 - abs(recommendation.integrity_belief - eib_ij) / eib_ij) if eib_ij > 0 else 0
+    return (r_diff + cb_diff + ib_diff) / 3
+
+
+def __compute_weight_of_recommendation(
+        configuration: TrustModelConfiguration,
+        recommendation: Recommendation,
+        history_factor: float
+) -> float:
+    """
+    Computes weight of recommendation - in model's notation rw^z_ik.
+    :param configuration: current trust model config
+    :param recommendation: recommendation from the peer
+    :param history_factor: int(mean(size of history) / maximal history size)
+    :return: recommendation weight rw^z_ik
+    """
+    service_history = recommendation.service_history_size / configuration.service_history_max_size
+    used_peers = recommendation.initial_reputation_provided_by_count / configuration.recommendations.peers_max_count
+    return history_factor * service_history + (1 - history_factor) * used_peers