Feature/ipcc prefix filter

[ppjablonski]

Summary

Adds support for configurable IP CC prefix exclusion groups on a per-intercept basis.

Collectors can now define named groups of IPv4/IPv6 prefixes. Individual IP intercepts select which groups to apply via cc_exclude_groups.

When an intercepted packet's source or destination IP matches a prefix in an assigned group, CC generation is suppressed for that specific intercept. IRI generation remains unaffected.

Configuration

Example collector configuration:

ipcc-exclude-prefix-groups:
  - name: oper-iptv
    prefixes:
      - 192.0.2.0/24

  - name: netflix-cache
    prefixes:
      - 198.18.10.0/24

  - name: iperf-public
    prefixes:
      - 198.20.10.0/24
      - 198.24.10.0/24
      - 198.26.10.0/24

Example intercept property:

cc_exclude_groups:
  - oper-iptv
  - netflix-cache

Key constraints:

• Max 64 groups supported globally (represented internally as a 64-bit mask).
• Overlapping prefixes across different groups are rejected during validation to ensure deterministic Trie lookups.

REST API

Exposed via cc_exclude_groups in the provisioner API.

Partial PUT behavior:

• Omitted field -> keep existing groups.
• Empty array ([]) -> clear all exclusions.
• Non-empty array -> overwrite group list.

Invalid, duplicate, or oversized group lists fail atomically — no partial updates are applied to the active intercept.

Packet Processing

Prefix filtering is backed by immutable IPv4 and IPv6 Patricia tries.

To keep overhead minimal, source and destination IP lookups are performed once per packet during standard IP CC processing. The resulting group mask is then checked against the policy of each matching intercept.

This flow is shared across standard IP CC and vendor decapsulation paths:

• JMirror
• ALU shim
• Cisco mirror

Malformed packets that fail IPv4/IPv6 parsing fall back to fail-open behavior and proceed down the standard CC path.

Suppressed records are dropped early — before export job allocation, packet copying, ZMQ pub, or sequence tracking.

Persistence & Runtime Updates

• Group definitions are stored in the provisioner YAML config and restored on startup
• Mask updates dynamically propagate to active dynamic sessions (v4/v6), static IP sessions, and vendor mirror intercepts without requiring a collector restart.

Testing

Verified in lab / local testbed:

• Core provisioner flows (POST, GET, partial PUT, persistence across restarts).
• Validation logic (duplicate group rejection, failed PUT transaction safety).
• Dynamic enable/disable on live sessions (no restart needed).
• IPv4 dynamic IP CC filtering.
• Intercept isolation (verified per-LIID filtering with two overlapping intercepts for the same target).
• Output capture validation (pcapdisk, agency delivery, JMirror).
• Performance benchmarking on JMirror (no measurable throughput regression observed with single-prefix filtering active).

Implemented and build-verified (pending traffic testing in live environment):

• IPv6 prefix matching.
• Static IP intercept ranges.
• ALU shim and Cisco mirror decapsulation paths.

Note: Code analyzed and prepared with assistance from GPT-5.6. Reviewed and tested manually.