fix(cisco-switch): map real message addresses and stop MAC rule circuit breakers

[kryonsx]

Summary

Real Cisco switch logs show that the MAC spoofing rule keeps disabling itself in production. The filter never writes the MAC address that the rule's history search needs. This draft maps the addresses that real switch messages carry. It also keeps MAC flap notifications out of the spoofing rule, guards the ARP rule's history search, and fixes a raw CEL condition that errors on every non-switch line.

Predecessor: #2599 (closed, historical context only).

Evidence (read-only, described without identifying data)

• Two instances send real Cisco IOS/IOS XE switch syslog:
  • about 226,000 records from 5 switches, and about 2,600 from one switch;
  • 79% are %SW_MATM-4-MACFLAP_NOTIF;
  • the rest are LINK/LINEPROTO, SISF, DHCPD, SSH, SYS, PKI, IP and wireless-controller messages.
• A third instance sends about 2.36M non-switch lines (Firepower Threat Defense events and Firepower Management Center system lines) to this data type.
• The deployed filter and rules (v11.2.13) match this repository.
• Production alert indices contain 12 Circuit Breaker: MAC Address Spoofing Detection alerts (2026-08-19 to 09-21) and no real MAC spoofing alert.
  • The error: expression value cannot be nil after placeholder resolution.
  • The events that triggered it: MAC flap notifications.
• Cisco's documentation site refused automated access (HTTP 403). Changes rest on real records, the filter, EventProcessor (commit 497bf53; the latest 8a3ade7 differs only in SDK versions and the CEL plugin's OpenSearch settings) and go-sdk behavior (unchanged for these points in v1.1.36).

Filter (filters/cisco/cs_switch.yml, 3.0.2 → 3.1.0)

• Condition fix: where: log.severity=="4" → equals("log.severity", "4"). The raw form fails to compile on events without a log object ("undeclared reference to 'log'"). It stored that error on about 1.12M non-switch records. Severity results are unchanged.
• MAC flap notifications: write origin.mac, log.vlan, log.firstPort and log.secondPort. Interface names stay under log.* because origin.port is numeric. The names do not claim which port is the previous one.
• Other address mappings, taken from the fixed text shapes seen in real records:
  • SISF excessive ARP activity: client MAC → origin.mac;
  • SSH session close and unexpected message: client address → origin.ip;
  • DHCP ping conflict: pinged address → target.ip;
  • logging-host start/fail: target.ip and a numeric target.port.
• Outcome values and severity words are unchanged; a separate outcome review owns them.

Rules

• mac_address_spoofing.yml:
  • requires origin.mac;
  • excludes flap notifications and corrects its description;
  • reads log.msg, which the filter writes, instead of log.message, which nothing writes;
  • uses deduplicateBy: [adversary.mac].
• arp_poisoning_detection.yml: requires origin.ip before its history search and reads log.msg.
• vlan_hopping_attempts.yml is unchanged; see the deferred items.

Why flaps are excluded (owner decision the reviewer can revisit)

Nothing establishes that a flap means an address was copied. In the real data, flaps look like network paths:

• one address alternates between the same two ports about every 15 seconds for 31 days;
• on the other instance, five port pairs carry 93% of flaps with 73–116 different addresses each.

Estimated 30-day alert volumes from real timestamps (not observed alerts):

Option	Instance A	Instance B
Flaps in, deduplicated, 3 in 10 min	5 (from ~175,000 firings)	115–119
Flaps in, deduplicated, 10 in 10 min	5	9
Flap storms only (50–100 in 10 min)	2–5	0
Flaps excluded (this draft)	0	0

Validation

Re-checked on 2026-09-24 on the latest versions: official v11 d2479c1a (merged into this branch, no conflicts; plugins/alerts now pins go-sdk v1.1.36) and EventProcessor main 8a3ade7 (playground and every plugin on go-sdk v1.1.36).

• SDK change: go-sdk v1.1.35+ keeps underscores in field names the parser plugins write, and v1.1.36 makes regexMatch match strings only. Neither changes this draft: none of the 25 names the filter writes contains an underscore (SW_MATM and similar are values, not names), and every regexMatch/contains call reads a text field. No file needed a change.
• Isolated EventProcessor playground (latest, real parser):
  • 398 inputs: 327 real, kept private, and 71 fabricated. Both runs are identical, event by event, to the results recorded on the older build.
  • The unchanged filter reproduces all stored records.
  • The changed filter gives 0 errors (from 25), unchanged severity and only intended new fields.
  • All real flap, SISF, SSH, DHCP and logging-host records get their fields, and no fabricated near-miss gets one.
  • The 2,795 distinct real texts and 28 fabricated lines give the same output as on the older build, line for line.
  • Committed plugins/alerts/testdata/cisco-switch/replay.py: 44 events, 0 errors, every field as in expected.json, 6 VLAN alerts, no circuit breaker, no history search.
• go-sdk v1.1.36 replay: the changed MAC and ARP rules match 0 of 229,017 real records, with no unresolved placeholder. The original MAC rule matches all 182,326 flap records and, with the deployed filter, cannot resolve origin.mac; with this filter's new mapping it would instead run a history search on every flap, which is why flaps are excluded. 15/15 synthetic checks pass.
• Playground rule run with fabricated lines (latest):
  • Changed rules: 0 MAC, 0 ARP and 0 circuit-breaker alerts, and VLAN alerts only on the six VLAN/DTP lines (14/14 checks).
  • Original rules: they reproduce the circuit breaker.
• Go tests: the full plugins/alerts suite passes on go-sdk v1.1.36: 51 pass, 11 skip (other technologies' private-evidence tests, same as the base), 0 fail. The eight new Cisco Switch tests all fail against the original files.

Deferred

These need Cisco's documentation or an owner decision:

• whether flaps should alert at all (as a separate network-health rule);
• which flap port is the previous one;
• address mappings for SW_DAI, IP DUPADDR and SOURCEGUARD;
• the VLAN rule's text branches, which have no threshold or guard;
• new rules for excessive ARP activity, logging-host failures, DHCP conflicts and PKI failures;
• access-list fields and device time conversion;
• severity words and outcome values.

For the owner, not a filter change

On one instance, Firepower and Firepower Management Center devices send their logs to the Cisco Switch input. Those events never reach the Firepower filter or rules. The fix is to point those devices at the Firepower input.

Limits

• The playground (EventProcessor 8a3ade7) and this module both use go-sdk v1.1.36; neither is claimed to match a customer deployment.
• History searches, deduplication, indexing and notifications were not tested against OpenSearch.
• Alert volumes are estimates from real timestamps.

See filters/audits/cisco-switch.md.

🤖 Generated with Claude Code