docs: created MODULES.md to document Suriconf pipeline and configurat…

[KEIAHNY]

…ion modules

[Copilot]

Pull request overview

Documents Suriconf’s static-analysis pipeline and configuration modules.

Changes:

• Explains pipeline stages and module execution order.
• Documents CPU, memory, flow, and thread-sizing calculations.
• Adds operational thresholds and warning counters.

Suppressed comments (4)

MODULES.md:107

• The claimed minimum is not fully enforced: set_new_cpu_set only raises estimates < 3 to four, so an estimate of exactly three remains three (src/cpu_affinity.rs:453-468). Either change that condition to enforce the documented four-core minimum or describe the current three-core edge case.

> A minimum of 4 logical cores is enforced due to performance degradation observed with fewer cores during testing.

MODULES.md:136

• Hash sizes are not always derived from the observed maxima. get_set_table keeps the fixed ACTIVE_LIMIT value of 512 whenever the maximum is at most 512, and only then switches to next_power_of_two; defragmentation trackers is also set to that resulting hash size (src/memory_usage.rs:295-318,414-435), not directly to the observed counter.

The sizes of the hash tables are determined based on the maximum observed values of counters:
- **IPpair** – `ippair_active` (maximum number of active IPpair objects).
- **Host** – `host_active` (maximum number of active host objects).
- **Defragmentation** – `defrag_tracker_active` (maximum number of active defrag trackers). This counter also  sets `trackers` parameter in defragmentation section. 

MODULES.md:145

• The default path is missing here: for IPpair, Host, and Defragmentation, preallocation is 256 when the active maximum is at most 512, rather than max_active / 2. Also, max-frags is calculated from the configured defragmentation hash size, not the raw active counter (src/memory_usage.rs:381-410,414-435,117-118).

Preallocated objects depend on the maximum number of active objects:
- **IPpair / Host** – `ippair_active` / `host_active` → prealloc = max_active / 2
- **Defragmentation** – `defrag_tracker_active` → prealloc = max_active / 2
- **max-frags** – calculated as `defrag_tracker_active` × `defrag_max_fragments`

MODULES.md:95

• These equations do not describe the implemented worker estimate. The code averages packet throughput per one CPU percentage point, includes decoder.invalid, targets 50% (CPU_USAGE = 50.0), and applies the 1.5 multiplier to the estimated packet load before division (src/cpu_affinity.rs:70-75,170-206,268-319). The current 60% formula therefore gives readers a different core count.

throughput_per_core = (decoder.pkts / cpu_usage) × 0.60
required_cores = ceil((total_kernel_packets / throughput_per_core) × 1.5)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.