Skip to content
47 changes: 40 additions & 7 deletions analysis/checks/risk.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,18 +55,51 @@ def _evidence(finding: Dict[str, Any]) -> str:
return str(evidence.get("detail", "")).lower()


# The marker access_control._check_dead_rules() writes after the dead line:
#
# "Unreachable line: <line> (action PERMIT|DENY). Blocked by: <lines>. ..."
#
# Our own fixed wording, not config text, and the same shape ai/explain.py
# reads. The first "(action ...)." before "Blocked by:" is ours; the line
# text before it comes from Batfish and never carries one.
_DEAD_DENY = re.compile(r"unreachable line: .+?\(action deny\)\. blocked by:")


def _rule_dead_rule_is_low(finding: Dict[str, Any]) -> Optional[str]:
"""R-1: a line that can never match cannot expose anything.
"""R-1: a dead PERMIT is low. A dead DENY keeps its check's severity.

A permit that can never match blocks traffic someone wanted: a hygiene
problem, worth reporting, not an exposure. A deny that can never match is
usually the opposite: when the line shadowing it is a permit, traffic
someone meant to block gets through, and access_control grades it high
for that reason.

NOT WHEN THE BLOCKER ALSO DENIES. Then the traffic is still blocked, by
the earlier line, and nothing is exposed. R-1 cannot tell the two apart:
the evidence names the dead line's action, not the blocker's. So it keeps
the check's severity for both, and over-rates a deny behind a deny (#447).

It used to lower both, on the grounds that the exposure "is reported
separately by R-2". That only holds when the line shadowing the deny is
a blanket permit. Measured in section 4 of the CVSS comparison in PR
#434: a deny shadowed by a SPECIFIC permit went to low, R-2 did not
fire, and the only finding about that traffic sat at the bottom.

Only a clear "(action DENY)" marker is left alone. Anything else that
says "unreachable" keeps the old answer, low.

FIRST ON PURPOSE. A dead-rule finding normally quotes the line that shadows
it, and that line is very often a blanket permit -- so if R-2 ran first it
would match the quoted BLOCKER and rate the dead rule "high". The exposure
is not lost by rating this low: the blanket permit is reported separately on
its own finding, where R-2 rates it high.
would match the quoted BLOCKER and rate a dead permit "high". For a dead
deny this rule passes, and R-2 still does not promote it, because the
blocker follows "Blocked by:" and is a citation.
"""
if "unreachable" in _evidence(finding):
return "low"
return None
detail = _evidence(finding)
if "unreachable" not in detail:
return None
if _DEAD_DENY.search(detail):
return None
return "low"


# The phrases our checks use to ATTRIBUTE a violation to the ACL line that
Expand Down
2 changes: 1 addition & 1 deletion docs/document-builds/build_group_report.py
Original file line number Diff line number Diff line change
Expand Up @@ -405,7 +405,7 @@ def code(t):
"possible traffic",
"No rows is a proof that no such flow exists. One row is a counter-example"],
["filterLineReachability", "Rules that can never match, and the earlier rule shadowing them",
"Report it as a tidiness problem and rate it low, because a dead rule cannot expose anything"],
"Rate a dead permit low, as a tidiness problem; a dead deny keeps its check's severity, because when a permit shadows it the traffic it was meant to block gets through"],
["undefinedReferences", "Things the configuration mentions but never defines",
"Report it directly. This is a silent failure risk"],
["traceroute", "The hop-by-hop path and whether the traffic arrived",
Expand Down
39 changes: 32 additions & 7 deletions docs/severity-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,21 +46,44 @@ move it down the page, which is the F-4 failure by another route.
Applied in order. The first that matches wins; anything unmatched keeps the
severity its check assigned.

### R-1 — A dead rule is low, whatever it says
### R-1 — A dead permit is low; a dead deny keeps its check's severity

**Matches:** `status="found"` and the evidence describes an unreachable /
shadowed ACL line.
shadowed ACL line that is **not** marked `(action DENY)`.
**Sets:** `low`

A line that can never match cannot expose anything. It is a hygiene problem —
A dead **permit** blocks traffic someone wanted. It is a hygiene problem —
someone believes a rule is in force when it is not — and it is worth reporting,
but it is not an exposure and should not sit above one.

A dead **deny** is usually the opposite: when the line shadowing it is a
permit, traffic someone meant to block gets through. `access_control` grades
it `high` for that reason, and R-1 leaves it alone.

**Known over-rating: a dead deny behind another deny (#447).** Then the traffic
is still blocked, by the earlier line, and nothing is exposed. R-1 cannot tell
this case apart: the evidence names the dead line's action, not the blocker's.
So it keeps the check's `high` here too, which over-rates it.

**This used to lower every dead line**, on the grounds that the exposure is
reported separately by R-2. That only holds when the line shadowing the deny is
a blanket permit. Measured in section 4 of the CVSS comparison in PR
#434: a telnet deny shadowed by a *specific* permit went to `low`, R-2 did not
fire, and the only finding about that traffic sat at the bottom of the list.
§6 item 2 below also records that R-2 has no observed effect on any fixture we
have, so R-1 should not lean on it.

**How the action is read.** The finding has no structured field for it, so R-1
reads the fixed marker `access_control` writes into `evidence.detail` —
*"Unreachable line: … (action DENY). Blocked by: …"*. That is our wording, not
config text. A dead-rule finding without a clear `(action DENY)` marker keeps
the old answer, `low`.

This rule is deliberately **first**, because a dead-rule finding usually quotes
the line that shadows it, and that line is very often a blanket permit. Without
the ordering, R-2 would match the quoted blocker and rate the dead rule `high`.
The exposure is not lost by rating it low: the blanket permit is reported
separately, on its own finding, by R-2.
the ordering, R-2 would match the quoted blocker and rate a dead permit `high`.
A dead deny passes through R-1 and is not promoted by R-2 either: its blocker
follows *"Blocked by:"*, so R-2 treats it as a citation.

### R-2 — A blanket permit is high

Expand Down Expand Up @@ -124,7 +147,9 @@ registry order, which is alphabetical by accident rather than meaningful.
- **It does not weight by device.** "This router is more important than that
one" is real, but we have no source for it that is not guesswork, and
inventing one would be exactly the unfounded claim the rest of this project
avoids. If the client tells us, it becomes data, not a rule.
avoids. If the client tells us, it becomes data, not a rule. That data is
business context (`critical` / `important` / `standard`), applied after these
rules: our equivalent of CVSS Environmental metrics.

## 6. Open, and deliberately not settled here

Expand Down
89 changes: 89 additions & 0 deletions tests/test_severity_rules.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,95 @@ def test_dead_rule_beats_the_blanket_permit_it_quotes():
assert risk.severity_for(f) == "low"


# The shape access_control._check_dead_rules() writes, copied by hand. A copy
# does not follow the real wording if it drifts: only
# test_a_dead_deny_from_the_real_check_comes_out_high, which runs the real
# producer, catches that.
def dead_line_detail(line, action, blocked_by):
return (f"Unreachable line: {line} (action {action}). "
f"Blocked by: {blocked_by}. Reason: BLOCKING_LINES")


def test_dead_deny_behind_a_specific_permit_keeps_its_checks_severity():
"""The measured case from section 4 of the CVSS comparison in PR #434.

The telnet deny never fires because the permit above it already lets the
whole LAN through to the server. So telnet from .66 gets through, which
the author meant to block. R-2 does not fire (the blocker is not a
blanket permit), so if R-1 lowers this, nothing in the list says it is
an exposure.
"""
f = a_finding("access_control", "high", dead_line_detail(
"deny tcp host 10.10.10.66 host 10.20.0.5 eq telnet", "DENY",
"permit tcp 10.10.10.0 0.0.0.255 host 10.20.0.5"))
assert risk.severity_for(f) == "high"


def test_dead_deny_behind_a_blanket_permit_keeps_its_checks_severity():
"""Still an exposure in its own right, and R-2 does not promote the quoted
blocker, so the check's own `high` is what has to survive."""
f = a_finding("access_control", "high", dead_line_detail(
"deny tcp host 10.10.10.66 host 10.20.0.5 eq telnet", "DENY",
"permit ip any any"))
assert risk.severity_for(f) == "high"


def test_dead_permit_is_still_rated_low():
"""A permit that never fires blocks wanted traffic. Hygiene, not exposure."""
f = a_finding("access_control", "medium", dead_line_detail(
"permit tcp 10.10.10.0 0.0.0.255 host 10.20.0.5 eq 443", "PERMIT",
"deny ip 10.10.10.0 0.0.0.255 any"))
assert risk.severity_for(f) == "low"


@pytest.mark.parametrize("detail", [
dead_line_detail("deny tcp any host 10.20.0.5 eq 23", "UNKNOWN", "an earlier line"),
"Unreachable line: deny tcp any host 10.20.0.5 eq 23",
])
def test_dead_line_not_clearly_a_deny_is_still_rated_low(detail):
"""Only a clear `(action DENY)` marker keeps the check's severity. Anything
else keeps R-1's old behaviour, as docs/severity-rules.md says."""
assert risk.severity_for(a_finding("access_control", "high", detail)) == "low"


def test_action_deny_not_followed_by_blocked_by_is_still_rated_low():
"""The marker is "(action DENY). Blocked by:", both halves. Our check
always writes them together, so "(action DENY)" on its own is not our
marker and gets R-1's old answer, low."""
detail = "Unreachable line: deny tcp any host 10.20.0.5 eq 23 (action DENY)"
assert risk.severity_for(a_finding("access_control", "high", detail)) == "low"


def test_a_dead_deny_from_the_real_check_comes_out_high():
"""The producer and the rule together: the finding access_control builds
for a dead deny is still `high` after refine(), and still `found`."""
import itertools

import pandas as pd

from analysis.checks import access_control

class _Session:
class q:
@staticmethod
def filterLineReachability():
frame = pd.DataFrame([{
"Sources": ["rtr-us5: lan_in"],
"Unreachable_Line": "deny tcp host 10.10.10.66 host 10.20.0.5 eq telnet",
"Unreachable_Line_Action": "DENY",
"Blocking_Lines": ["permit tcp 10.10.10.0 0.0.0.255 host 10.20.0.5"],
"Reason": "BLOCKING_LINES",
}])
return type("A", (), {"answer": lambda self: self,
"frame": lambda self: frame})()

[dead] = access_control._check_dead_rules(_Session(), itertools.count(1))
[refined] = risk.refine([dead])
assert dead["severity"] == "high", "the check's own grading changed"
assert refined["severity"] == "high"
assert refined["status"] == "found"


# --- R-2: blanket permits ---------------------------------------------------


Expand Down