show access-lists reports which rule matched (#1267) #1268

Merged
jaylouisw merged 1 commit from fix/acl-match-counters into main 2026-11-09 20:24:19 +00:00
Owner

show access-lists reports which rule matched

Fixes #1267.

Extended IP access list 101
  1 deny icmp any any (5 matches)
  2 permit ip any any
    applied IN on Gi0

The gap

show access-lists listed rules and said nothing about them. show interfaces said
5 drops (ACL 101 denied (in) x5) — so the console could tell you an ACL was denying and never which line
was doing it, which is the whole reason the table is opened. And the drop summary cannot answer the follow-up
because it names the list, not the rule.

The information was already there: aclLib.evaluate() returns matchedIndex, and the implicit deny is
flagged, and the only consumer threw both away.

Now

  • Simulator._countAclHit() tallies every evaluation inside _aclCheck() — the funnel both directions
    pass through — so a permit is counted as well as a deny, and a call site added later is counted by
    construction. Same discipline _emit() uses for drops (#1257);
  • show access-lists prints (N matches) per rule, singular/plural, and nothing at all for a rule that
    has not matched — (0 matches) on every line of a twenty-line list is noise, and absence says the same
    thing;
  • the implicit deny is reported once it has fired, separately: it is a real rule, and it is what drops the
    traffic that matched nothing;
  • counters are keyed by the rule's own text, not its index — an index key credited a brand-new rule with
    the previous rule's traffic after a list was rewritten. That was found by the test written for it, and
    fixed rather than asserted around;
  • no access-list <id> deletes the counters with the list;
  • the table distinguishes "no simulation run" from "no packet has been tested against this list" from "zero
    matches" — the same three-way distinction show interfaces makes (#1252).

Evidence

test/show-access-lists.test.js — 23 checks:

  • no simulator → counters: not measured (no simulation run); simulator but no traffic → counters: no packet has been tested against this list; neither invents zero counts;
  • five denied pings → the deny rule shows 5 matches, the permit rule shows no count, and
    show interfaces reports the same five over the same list — the two tables read together must agree;
  • two more pings → 7, i.e. counters accumulate across runs like real ones;
  • a permitted flow counts the permit rule and leaves the deny rule uncounted;
  • (1 match) singular;
  • an ACL whose only rule does not match → (implicit deny all: 2 matches), while the non-matching rule stays
    uncounted;
  • the outbound direction is counted as well;
  • an ACL bound to nothing says so, with no invented binding;
  • a rewritten list does not re-attribute the old rule's traffic to the new rule at index 0.

Reverting engine/simulator.js fails 6; engine/cli.js fails 9.

docs/CLI.md gains "Reading show access-lists" and the command in the table.

Suite: 147 suites, 6,240 assertions, 0 failed.

`show access-lists` reports which rule matched Fixes #1267. ``` Extended IP access list 101 1 deny icmp any any (5 matches) 2 permit ip any any applied IN on Gi0 ``` ## The gap `show access-lists` listed rules and said nothing about them. `show interfaces` said `5 drops (ACL 101 denied (in) x5)` — so the console could tell you an ACL was denying and never **which line** was doing it, which is the whole reason the table is opened. And the drop summary cannot answer the follow-up because it names the list, not the rule. The information was already there: `aclLib.evaluate()` returns `matchedIndex`, and the implicit deny is flagged, and the only consumer threw both away. ## Now * `Simulator._countAclHit()` tallies **every** evaluation inside `_aclCheck()` — the funnel both directions pass through — so a permit is counted as well as a deny, and a call site added later is counted by construction. Same discipline `_emit()` uses for drops (#1257); * `show access-lists` prints `(N matches)` per rule, singular/plural, and **nothing at all** for a rule that has not matched — `(0 matches)` on every line of a twenty-line list is noise, and absence says the same thing; * the implicit deny is reported once it has fired, separately: it is a real rule, and it is what drops the traffic that matched nothing; * counters are keyed by **the rule's own text**, not its index — an index key credited a brand-new rule with the previous rule's traffic after a list was rewritten. That was found by the test written for it, and fixed rather than asserted around; * `no access-list <id>` deletes the counters with the list; * the table distinguishes "no simulation run" from "no packet has been tested against this list" from "zero matches" — the same three-way distinction `show interfaces` makes (#1252). ## Evidence `test/show-access-lists.test.js` — 23 checks: * no simulator → `counters: not measured (no simulation run)`; simulator but no traffic → `counters: no packet has been tested against this list`; neither invents zero counts; * five denied pings → the deny rule shows **5 matches**, the permit rule shows **no count**, and `show interfaces` reports the *same five* over the same list — the two tables read together must agree; * two more pings → 7, i.e. counters accumulate across runs like real ones; * a permitted flow counts the permit rule and leaves the deny rule uncounted; * `(1 match)` singular; * an ACL whose only rule does not match → `(implicit deny all: 2 matches)`, while the non-matching rule stays uncounted; * the outbound direction is counted as well; * an ACL bound to nothing says so, with no invented binding; * a rewritten list does not re-attribute the old rule's traffic to the new rule at index 0. Reverting `engine/simulator.js` fails 6; `engine/cli.js` fails 9. `docs/CLI.md` gains "Reading `show access-lists`" and the command in the table. Suite: 147 suites, 6,240 assertions, 0 failed.
show access-lists reports which rule matched (#1267)
All checks were successful
CI / Classify the change (pull_request) Successful in 10s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 14s
CI / Test (Node 18) (pull_request) Successful in 1m56s
CI / Test (Node 20) (pull_request) Successful in 1m54s
CI / Server smoke test (pull_request) Successful in 37s
CI / Docker build (pull_request) Successful in 39s
CI / Test (Node 22) (pull_request) Successful in 1m54s
0ab15f01f5
The table listed rules and said nothing about them, while `show interfaces` said
`5 drops (ACL 101 denied (in) x5)` - so the console could tell you an ACL was denying and never which line.
The information was already there: `aclLib.evaluate()` returns `matchedIndex` and whether the implicit deny
matched, and the index was discarded by the one consumer.

Now:
* `Simulator._countAclHit()` tallies every evaluation inside `_aclCheck()` - the funnel both directions pass
  through - so a permit is counted as well as a deny and a call site added later is counted by construction,
  the same discipline `_emit()` uses for drops;
* `show access-lists` prints `(N matches)` per rule, singular/plural, and **nothing at all** for a rule that
  has not matched: "(0 matches)" on every line of a twenty-line list is noise, and absence says the same
  thing;
* the implicit deny is reported separately once it has fired - it is a real rule, and it is what drops the
  traffic that matched nothing;
* counters are keyed by the rule's own text rather than its index, because an index key credited a
  brand-new rule with the previous rule's traffic after a list was rewritten (found by the test for it);
  `no access-list <id>` deletes the counters with the list;
* the table distinguishes "not measured (no simulation run)" from "no packet has been tested against this
  list" from "zero matches" - the same three-way distinction `show interfaces` makes (#1252).

test/show-access-lists.test.js (23 checks): no-sim and no-traffic states; a denied flow naming the deny rule
with the right count, accumulating across runs, while the permit line stays uncounted; a permitted flow
counting the permit rule; `(1 match)` singular; the implicit deny reported with its own count and not folded
into a rule that did not match; the outbound direction counted; an ACL bound to nothing saying so with no
invented binding; and a rewritten list not re-attributing old traffic to a new rule. The load-bearing one:
`show interfaces` and `show access-lists` report the same five packets.

Reverting engine/simulator.js fails 6, engine/cli.js fails 9.

Suite: 147 suites, 6,240 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 20:24:16 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1268
No description provided.