net.i2p.router.sybil

## Class Analysis

- java.lang.Object
- - net.i2p.router.JobImpl
  - - net.i2p.router.sybil.Analysis

- All Implemented Interfaces:
    Runnable, ClientApp, RouterApp, Job

      public class Analysis
      extends JobImpl
      implements RouterApp, Runnable

  Sybil attack analysis implementation.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `APP_NAME` The name we register with the ClientAppManager.
    `static boolean` | `DEFAULT_BLOCK`
    `static double` | `DEFAULT_BLOCK_THRESHOLD`
    `static long` | `DEFAULT_BLOCK_TIME`
    `static long` | `DEFAULT_FREQUENCY`
    `static long` | `DEFAULT_REMOVE_TIME`
    `static int` | `MAX`
    `static float` | `MIN_BLOCK_POINTS`
    `static double` | `MIN_CLOSE`
    `static int` | `PAIRMAX`
    `static String` | `PROP_BLOCK`
    `static String` | `PROP_BLOCKTIME`
    `static String` | `PROP_FREQUENCY`
    `static String` | `PROP_NONFF`
    `static String` | `PROP_REMOVETIME`
    `static String` | `PROP_THRESHOLD`
    `static long` | `SHORT_REMOVE_TIME`

    - ### Fields inherited from class net.i2p.router.JobImpl

      `_id`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addProfilePoints(List<RouterInfo> ris, Map<Hash,Points> points)` Analyzes router profiles and adds Sybil points for banlisted, newly observed, or poorly performing routers.
    `void` | `addVersionPoints(List<RouterInfo> ris, Map<Hash,Points> points)` Analyzes router versions and adds Sybil points for old, unreachable, or non-floodfill routers.
    `Map<Hash,Points>` | `backgroundAnalysis(boolean includeAll)` Analyze threats.
    `Map<Integer,List<RouterInfo>>` | `calculateIPGroups16(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their /16 subnet to identify routers in the same /16 network.
    `Map<Integer,List<RouterInfo>>` | `calculateIPGroups24(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their /24 subnet to identify routers in the same /24 network.
    `Map<Integer,List<RouterInfo>>` | `calculateIPGroups32(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their IP address to identify routers sharing the same IP.
    `Map<Long,List<RouterInfo>>` | `calculateIPGroups48(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their IPv6 /48 subnet to identify routers in the same /48 network.
    `Map<Long,List<RouterInfo>>` | `calculateIPGroups64(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their IPv6 /64 subnet to identify routers in the same /64 network.
    `Map<String,List<RouterInfo>>` | `calculateIPGroupsFamily(List<RouterInfo> ris, Map<Hash,Points> points)` Categorize routers by their router family to identify routers in the same family.
    `void` | `calculateIPGroupsUs(List<RouterInfo> ris, Map<Hash,Points> points, List<RouterInfo> ri32, List<RouterInfo> ri24, List<RouterInfo> ri16, List<RouterInfo> ri64, List<RouterInfo> ri48)` Categorize routers by their proximity to our IP address, grouping them by /32, /24, /16 for IPv4 and /64, /48 for IPv6.
    `double` | `calculatePairDistance(List<RouterInfo> ris, Map<Hash,Points> points, List<Pair> pairs)` Calculate average pairwise distance between floodfills and identifies routers that are unusually close to each other.
    `void` | `calculateRouterInfo(Hash us, String usName, List<RouterInfo> ris, Map<Hash,Points> points)`
    `List<RouterInfo>` | `getAllRouters(Hash us)` Returns all routers in the network DB, excluding our own router.
    `double` | `getAvgMinDist(List<RouterInfo> ris)` Calculates the average minimum distance from 200 random routing keys to the closest router in the provided list.
    `String` | `getDisplayName()` Gets the display name for this application.
    `List<RouterInfo>` | `getFloodfills(Hash us)` Returns all floodfill routers, excluding our own router.
    `static Analysis` | `getInstance(RouterContext ctx)` Gets the singleton Analysis instance, creating it if necessary.
    `String` | `getName()` Gets the application name.
    `PersistSybil` | `getPersister()` Gets the persistence handler for storing and retrieving Sybil analysis data.
    `ClientAppState` | `getState()` Gets the current state of this application.
    `void` | `run()` Executes the background Sybil analysis, stores results, and removes old data.
    `void` | `runJob()` Actually perform the task.
    `void` | `schedule()` Schedules the next Sybil analysis run based on configured frequency, router uptime, and previous run time.
    `void` | `shutdown(String[] args)` Stops the Sybil analysis service and changes state to STOPPED.
    `void` | `startup()` Initializes and starts the Sybil analysis service.

    - ### Methods inherited from class net.i2p.router.JobImpl

      `dropped, getContext, getJobId, getMadeReadyOn, getTiming, madeReady, requeue, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### APP_NAME

          public static final String APP_NAME

      The name we register with the ClientAppManager.
      See Also:
        Constant Field Values

    - #### DEFAULT_BLOCK

          public static final boolean DEFAULT_BLOCK

      See Also:
        Constant Field Values

    - #### DEFAULT_BLOCK_THRESHOLD

          public static final double DEFAULT_BLOCK_THRESHOLD

      See Also:
        Constant Field Values

    - #### DEFAULT_BLOCK_TIME

          public static final long DEFAULT_BLOCK_TIME

      See Also:
        Constant Field Values

    - #### DEFAULT_FREQUENCY

          public static final long DEFAULT_FREQUENCY

      See Also:
        Constant Field Values

    - #### DEFAULT_REMOVE_TIME

          public static final long DEFAULT_REMOVE_TIME

      See Also:
        Constant Field Values

    - #### MAX

          public static final int MAX

      See Also:
        Constant Field Values

    - #### MIN_BLOCK_POINTS

          public static final float MIN_BLOCK_POINTS

      See Also:
        Constant Field Values

    - #### MIN_CLOSE

          public static final double MIN_CLOSE

      See Also:
        Constant Field Values

    - #### PAIRMAX

          public static final int PAIRMAX

      See Also:
        Constant Field Values

    - #### PROP_BLOCK

          public static final String PROP_BLOCK

      See Also:
        Constant Field Values

    - #### PROP_BLOCKTIME

          public static final String PROP_BLOCKTIME

      See Also:
        Constant Field Values

    - #### PROP_FREQUENCY

          public static final String PROP_FREQUENCY

      See Also:
        Constant Field Values

    - #### PROP_NONFF

          public static final String PROP_NONFF

      See Also:
        Constant Field Values

    - #### PROP_REMOVETIME

          public static final String PROP_REMOVETIME

      See Also:
        Constant Field Values

    - #### PROP_THRESHOLD

          public static final String PROP_THRESHOLD

      See Also:
        Constant Field Values

    - #### SHORT_REMOVE_TIME

          public static final long SHORT_REMOVE_TIME

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### addProfilePoints

          public void addProfilePoints(List<RouterInfo> ris,
                                       Map<Hash,Points> points)

      Analyzes router profiles and adds Sybil points for banlisted, newly observed, or poorly performing routers.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points

    - #### addVersionPoints

          public void addVersionPoints(List<RouterInfo> ris,
                                       Map<Hash,Points> points)

      Analyzes router versions and adds Sybil points for old, unreachable, or non-floodfill routers.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points

    - #### backgroundAnalysis

          public Map<Hash,Points> backgroundAnalysis(boolean includeAll)

      Analyze threats. No output. Return separate maps for each cause instead?
      Parameters:
        `includeAll` - false for floodfills only
      Returns:
        map of router hash to Points containing sybil analysis results

    - #### calculateIPGroups16

          public Map<Integer,List<RouterInfo>> calculateIPGroups16(List<RouterInfo> ris,
                                                                   Map<Hash,Points> points)

      Categorize routers by their /16 subnet to identify routers in the same /16 network.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of /16 network (as Integer) to list of routers in that network

    - #### calculateIPGroups24

          public Map<Integer,List<RouterInfo>> calculateIPGroups24(List<RouterInfo> ris,
                                                                   Map<Hash,Points> points)

      Categorize routers by their /24 subnet to identify routers in the same /24 network.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of /24 network (as Integer) to list of routers in that network

    - #### calculateIPGroups32

          public Map<Integer,List<RouterInfo>> calculateIPGroups32(List<RouterInfo> ris,
                                                                   Map<Hash,Points> points)

      Categorize routers by their IP address to identify routers sharing the same IP.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of IP address (as Integer) to list of routers with that IP

    - #### calculateIPGroups48

          public Map<Long,List<RouterInfo>> calculateIPGroups48(List<RouterInfo> ris,
                                                                Map<Hash,Points> points)

      Categorize routers by their IPv6 /48 subnet to identify routers in the same /48 network.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of IPv6 /48 network (as Long) to list of routers in that network

    - #### calculateIPGroups64

          public Map<Long,List<RouterInfo>> calculateIPGroups64(List<RouterInfo> ris,
                                                                Map<Hash,Points> points)

      Categorize routers by their IPv6 /64 subnet to identify routers in the same /64 network.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of IPv6 /64 network (as Long) to list of routers in that network

    - #### calculateIPGroupsFamily

          public Map<String,List<RouterInfo>> calculateIPGroupsFamily(List<RouterInfo> ris,
                                                                      Map<Hash,Points> points)

      Categorize routers by their router family to identify routers in the same family. Routers in verified families receive fewer points.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
      Returns:
        map of family name to list of routers in that family

    - #### calculateIPGroupsUs

          public void calculateIPGroupsUs(List<RouterInfo> ris,
                                          Map<Hash,Points> points,
                                          List<RouterInfo> ri32,
                                          List<RouterInfo> ri24,
                                          List<RouterInfo> ri16,
                                          List<RouterInfo> ri64,
                                          List<RouterInfo> ri48)

      Categorize routers by their proximity to our IP address, grouping them by /32, /24, /16 for IPv4 and /64, /48 for IPv6.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
        `ri32` - out parameter for routers with same IP as us
        `ri24` - out parameter for routers in same /24 as us
        `ri16` - out parameter for routers in same /16 as us
        `ri64` - out parameter for routers in same IPv6 /64 as us
        `ri48` - out parameter for routers in same IPv6 /48 as us

    - #### calculatePairDistance

          public double calculatePairDistance(List<RouterInfo> ris,
                                              Map<Hash,Points> points,
                                              List<Pair> pairs)

      Calculate average pairwise distance between floodfills and identifies routers that are unusually close to each other.
      Parameters:
        `ris` - the list of router infos to analyze
        `points` - map to accumulate sybil points
        `pairs` - out parameter, sorted list of close router pairs
      Returns:
        average distance

    - #### calculateRouterInfo

          public void calculateRouterInfo(Hash us,
                                          String usName,
                                          List<RouterInfo> ris,
                                          Map<Hash,Points> points)

      Parameters:
        `usName` - HTML escaped
        `ris` - will be re-sorted in place

    - #### getAllRouters

          public List<RouterInfo> getAllRouters(Hash us)

      Returns all routers in the network DB, excluding our own router.
      Parameters:
        `us` - our router hash to exclude from the results
      Returns:
        list of all RouterInfo objects

    - #### getAvgMinDist

          public double getAvgMinDist(List<RouterInfo> ris)

      Calculates the average minimum distance from 200 random routing keys to the closest router in the provided list.
      Parameters:
        `ris` - the list of router infos to analyze
      Returns:
        the average minimum distance in logarithmic scale (base 2)

    - #### getDisplayName

          public String getDisplayName()

      Gets the display name for this application.
      Specified by:
        `getDisplayName` in interface `ClientApp`
      Returns:
        "Sybil Analyzer"

    - #### getFloodfills

          public List<RouterInfo> getFloodfills(Hash us)

      Returns all floodfill routers, excluding our own router.
      Parameters:
        `us` - our router hash to exclude from the results
      Returns:
        list of floodfill RouterInfo objects

    - #### getInstance

          public static Analysis getInstance(RouterContext ctx)

      Gets the singleton Analysis instance, creating it if necessary.
      Parameters:
        `ctx` - the router context
      Returns:
        non-null, creates new if not already registered

    - #### getName

          public String getName()

      Gets the application name.
      Specified by:
        `getName` in interface `ClientApp`
      Specified by:
        `getName` in interface `Job`
      Returns:
        the constant APP_NAME

    - #### getPersister

          public PersistSybil getPersister()

      Gets the persistence handler for storing and retrieving Sybil analysis data.
      Returns:
        the PersistSybil instance used by this analysis

    - #### getState

          public ClientAppState getState()

      Gets the current state of this application.
      Specified by:
        `getState` in interface `ClientApp`
      Returns:
        the current ClientAppState

    - #### run

          public void run()

      Executes the background Sybil analysis, stores results, and removes old data.
      Specified by:
        `run` in interface `Runnable`

    - #### runJob

          public void runJob()

      Description copied from interface: `Job`
      Actually perform the task. This call blocks until the Job is complete.
      Specified by:
        `runJob` in interface `Job`

    - #### schedule

          public void schedule()

      Schedules the next Sybil analysis run based on configured frequency, router uptime, and previous run time.

    - #### shutdown

          public void shutdown(String[] args)

      Stops the Sybil analysis service and changes state to STOPPED.
      Specified by:
        `shutdown` in interface `ClientApp`
      Parameters:
        `args` - ignored (required by interface)

    - #### startup

          public void startup()

      Initializes and starts the Sybil analysis service. Registers with the ClientAppManager, loads persisted blocklist data, and schedules the first analysis run.
      Specified by:
        `startup` in interface `ClientApp`