@hoanghainh/komagu 2.3.0 → 2.5.0

package/assess/lsa/scripts/map_routes.py

@@ -19,8 +19,11 @@ from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from lsa_common import (KIT_VERSION, compile_id_patterns, is_id_name, iter_source_files,  # noqa: E402
-                        line_of, load_config, read_text, write_json)
+from java_routes import (build_class_index, collect_spring_beans, entry_method_line, java_declared,  # noqa: E402
+                         struts2_action_extension,
+                         struts_modules, xml_declared)
+from lsa_common import (JAVA_WEB_ROOT, KIT_VERSION, call_args, compile_id_patterns, is_id_name,  # noqa: E402
+                        iter_source_files, line_of, load_config, read_text, split_top, write_json)
 from nextjs_routes import middleware_note, nextjs_declared  # noqa: E402
 from privilege import annotate_privilege  # noqa: E402
 
@@ -250,8 +253,6 @@ def segments(text: str, decl_rx: re.Pattern) -> List[Tuple[re.Match, int, int]]:
 # Declared-route extractors
 # --------------------------------------------------------------------------------------
 PHP_METHOD = re.compile(r"^[ \t]*(?:(public|protected|private)\s+)?(?:static\s+)?function\s+&?(\w+)\s*\(", re.M)
-JAVA_METHOD_ANN = re.compile(r"@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|Path)\b\s*(\(([^)]*)\))?")
-JAVA_HTTP_ANN = re.compile(r"@(GET|POST|PUT|DELETE|PATCH)\b")
 CS_ACTION = re.compile(r"^[ \t]*public\s+(?!record\b|class\b)(?:virtual\s+|async\s+|override\s+|static\s+)*[A-Za-z0-9_<>., \[\]?]+\s+(\w+)\s*\(([^)]*)\)", re.M)
 VB_ACTION = re.compile(r"^[ \t]*Public\s+(?:Overridable\s+|Async\s+)*Function\s+(\w+)\s*\(([^)]*)\)\s+As\s+[\w.(<>) ]+", re.M | re.I)
 WEBMETHOD = re.compile(r"(\[WebMethod[^\]]*\]|<WebMethod[^>]*>|\[OperationContract[^\]]*\]|<OperationContract[^>]*>)[\s\S]{0,300}?"
@@ -305,107 +306,6 @@ def php_declared(c: Collector, rel: str, text: str, stacks: set) -> bool:
     return found
 
 
-def java_declared(c: Collector, rel: str, text: str) -> bool:
-    found = False
-    cls_prefix = ""
-    cm = re.search(r"@(RequestMapping|Path)\s*\(\s*(?:value\s*=\s*)?\"([^\"]*)\"[^)]*\)\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+)?(?:abstract\s+)?class", text)
-    if cm:
-        cls_prefix = cm.group(2)
-    is_servlet = re.search(r"extends\s+HttpServlet", text)
-    if is_servlet:
-        ws = re.search(r"@WebServlet\s*\(\s*(?:urlPatterns\s*=\s*|value\s*=\s*)?\{?\s*\"([^\"]+)\"", text)
-        for m in re.finditer(r"(?:public|protected)\s+void\s+(doGet|doPost|doPut|doDelete|service)\s*\(", text):
-            start = m.start()
-            nxt = re.search(r"\n\s*(?:public|protected|private)\s+[\w<>\[\]]+\s+\w+\s*\(", text[m.end():])
-            body = text[start: m.end() + (nxt.start() if nxt else len(text))]
-            line = line_of(text, start)
-            verb = {"doGet": "GET", "doPost": "POST", "doPut": "PUT", "doDelete": "DELETE"}.get(m.group(1), "ANY")
-            c.add(stack="java-servlet", kind="declared_route", method=[verb],
-                  path=ws.group(1) if ws else "<see web.xml servlet-mapping>",
-                  handler={"file": rel, "line": line, "symbol": m.group(1)},
-                  id_params=c.inputs("java", body, line), guard_hints=c.guards(body, line),
-                  data_hints=c.data_ops(body, line), notes="" if ws else "resolve path from web.xml")
-            found = True
-        return found
-    anns = list(JAVA_METHOD_ANN.finditer(text))
-    for m in anns:
-        if cm and m.start() == cm.start():
-            continue
-        after = text[m.end(): m.end() + 600]
-        # skip class-level annotation
-        if re.match(r"\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+)?(?:abstract\s+)?class\b", after):
-            continue
-        sig = re.search(r"(?:(?:public|protected)\s+[\w<>\[\],.? ]+|fun|(?:override|suspend)\s+fun)\s+(\w+)\s*\(", after)
-        if not sig:
-            continue
-        before = text[:m.start()]
-        cls_m = list(re.finditer(r"@(?:RequestMapping|Path)\s*\(\s*(?:value\s*=\s*|path\s*=\s*)?\"([^\"]*)\"[^)]*\)[\s\S]{0,300}?(?:class\b)", before))
-        method_cls_prefix = cls_m[-1].group(1) if cls_m else cls_prefix
-        args = m.group(3) or ""
-        pv = re.search(r"(?:value\s*=\s*|path\s*=\s*)?\{?\s*\"([^\"]*)\"", args)
-        sub = pv.group(1) if pv else ""
-        verbs = re.findall(r"RequestMethod\.(\w+)", args)
-        ann = m.group(1)
-        if ann.endswith("Mapping") and ann != "RequestMapping":
-            verbs = [ann[:-7].upper()]
-        if ann == "Path":
-            hv = JAVA_HTTP_ANN.search(text[max(0, m.start() - 200): m.end() + 200])
-            verbs = [hv.group(1)] if hv else ["ANY"]
-        path = "/" + "/".join(p.strip("/") for p in (method_cls_prefix, sub) if p.strip("/"))
-        nxt = re.search(r"\n\s*@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|Path)\b(?!Variable|Param)", text[m.end():])
-        body = text[m.start(): m.end() + (nxt.start() if nxt else len(text))]
-        line = line_of(text, m.start())
-        c.add(stack="java-spring-mvc" if ann != "Path" else "java-jaxrs", kind="declared_route", method=verbs or ["ANY"],
-              path=path, handler={"file": rel, "line": line, "symbol": sig.group(1)},
-              id_params=c.path_params(path) + c.inputs("java", body, line),
-              guard_hints=c.guards(text[:m.start()][-1500:], 1)[:2] + c.guards(body, line),
-              data_hints=c.data_ops(body, line), notes="")
-        found = True
-    # Struts 1 / 2 Action classes without annotations are mapped from XML (see xml_declared)
-    return found
-
-
-def xml_declared(c: Collector, rel: str, text: str, class_index: Dict[str, str]) -> bool:
-    found = False
-    if rel.endswith("web.xml"):
-        servlets = dict(re.findall(r"<servlet>\s*<servlet-name>\s*([^<]+?)\s*</servlet-name>[\s\S]*?<servlet-class>\s*([^<]+?)\s*</servlet-class>", text))
-        for m in re.finditer(r"<servlet-mapping>\s*<servlet-name>\s*([^<]+?)\s*</servlet-name>\s*<url-pattern>\s*([^<]+?)\s*</url-pattern>", text):
-            name, pattern = m.group(1), m.group(2)
-            cls = servlets.get(name, "")
-            hfile = class_index.get(cls.split(".")[-1], rel)
-            c.add(stack="java-servlet", kind="declared_route", method=["ANY"], path=pattern,
-                  handler={"file": hfile, "line": 1, "symbol": cls or name}, id_params=[], guard_hints=[],
-                  data_hints=[], notes=f"mapped in {rel}:{line_of(text, m.start())}")
-            found = True
-    if "struts-config" in rel:
-        for m in re.finditer(r"<action\b([^>]*)>", text):
-            attrs = dict(re.findall(r"(\w+)\s*=\s*\"([^\"]*)\"", m.group(1)))
-            if "path" not in attrs:
-                continue
-            cls = attrs.get("type", "")
-            hfile = class_index.get(cls.split(".")[-1], rel)
-            note = f"declared in {rel}:{line_of(text, m.start())}"
-            if attrs.get("parameter"):
-                note += f"; DispatchAction parameter '{attrs['parameter']}' -> one endpoint per method"
-            c.add(stack="java-struts1", kind="declared_route", method=["ANY"], path=attrs["path"] + ".do",
-                  handler={"file": hfile, "line": 1, "symbol": cls}, id_params=[], guard_hints=[], data_hints=[], notes=note)
-            found = True
-    if rel.endswith("struts.xml"):
-        for pm in re.finditer(r"<package\b([^>]*)>([\s\S]*?)</package>", text):
-            pattrs = dict(re.findall(r"(\w+)\s*=\s*\"([^\"]*)\"", pm.group(1)))
-            ns = pattrs.get("namespace", "/").rstrip("/")
-            for am in re.finditer(r"<action\b([^>]*)>", pm.group(2)):
-                attrs = dict(re.findall(r"(\w+)\s*=\s*\"([^\"]*)\"", am.group(1)))
-                cls = attrs.get("class", "")
-                hfile = class_index.get(cls.split(".")[-1], rel)
-                c.add(stack="java-struts2", kind="declared_route", method=["ANY"], path=f"{ns}/{attrs.get('name', '?')}.action",
-                      handler={"file": hfile, "line": 1, "symbol": f"{cls}#{attrs.get('method', 'execute')}"},
-                      id_params=[], guard_hints=[], data_hints=[],
-                      notes=f"declared in {rel}:{line_of(text, pm.start() + am.start())}; action setters are inputs")
-                found = True
-    return found
-
-
 def dotnet_declared(c: Collector, rel: str, text: str) -> bool:
     found = False
     cm = re.search(r"(?:\[ApiController\][\s\S]{0,100}?)?class\s+(\w+?)Controller\s*(?::\s*(\w+))?|Class\s+(\w+?)Controller[\s\S]{0,80}?Inherits\s+(\w+)", text, re.I)
@@ -560,48 +460,6 @@ GO_FRAMEWORKS = [("go-gin", "github.com/gin-gonic/gin"), ("go-echo", "github.com
 GO_PATTERN = re.compile(r"^(?:([A-Z]+)\s+)?(/\S*)$")
 
 
-def call_args(text: str, open_idx: int, limit: int = 4000) -> Tuple[str, int]:
-    """Return (argument text, index after the closing paren) for the call whose '(' is at open_idx."""
-    depth, i, end = 0, open_idx, min(len(text), open_idx + limit)
-    while i < end:
-        ch = text[i]
-        if ch in "\"`":
-            close = text.find(ch, i + 1)
-            while ch == '"' and close != -1 and text[close - 1] == "\\":
-                close = text.find(ch, close + 1)
-            i = close if close != -1 else end
-        elif ch in "([{":
-            depth += 1
-        elif ch in ")]}":
-            depth -= 1
-            if depth == 0:
-                return text[open_idx + 1:i], i + 1
-        i += 1
-    return text[open_idx + 1:end], end
-
-
-def split_top(args: str) -> List[str]:
-    """Split call arguments on top-level commas."""
-    parts, depth, cur, quote = [], 0, [], None
-    for ch in args:
-        if quote:
-            quote = None if ch == quote else quote
-        elif ch in "\"`":
-            quote = ch
-        elif ch in "([{":
-            depth += 1
-        elif ch in ")]}":
-            depth -= 1
-        elif ch == "," and depth == 0:
-            parts.append("".join(cur).strip())
-            cur = []
-            continue
-        cur.append(ch)
-    if "".join(cur).strip():
-        parts.append("".join(cur).strip())
-    return parts
-
-
 def guards_before(c: Collector, text: str, start: int, end: int, span: int = 500) -> List[Dict]:
     ws = max(0, start - span)
     return c.guards(text[ws:end], line_of(text, ws))
@@ -712,6 +570,9 @@ def file_endpoint(c: Collector, rel: str, text: str, lang: str, ext: str, target
         wr = wr.strip("/") + "/"
         if rel.startswith(wr):
             path = "/" + rel[len(wr):]
+    root = JAVA_WEB_ROOT.search(rel) if lang == "java" and path == "/" + rel else None
+    if root:
+        path = "/" + rel[root.end():]
     stack = {"php": "php", "java": "java-jsp", "dotnet": "dotnet-webforms" if ext in (".aspx",) else "dotnet-handlers",
              "asp": "classic-asp", "perl": "perl-cgi", "cfml": "coldfusion"}.get(lang, lang)
     if ext in (".asmx", ".svc"):
@@ -775,7 +636,11 @@ def _scan_route_file_batch(args: Tuple[List[Tuple[str, str]], Dict, set, str]) -
             declared = go_declared(c, rel, t)
         if declared or ext not in FILE_ENDPOINT_EXTS:
             continue
-        if INCLUDE_DIR_RE.search(rel.rsplit("/", 1)[0] + "/" if "/" in rel else ""):
+        if ext == ".jsp":
+            # Tomcat serves any JSP outside WEB-INF, whatever its directory is called; those inside are only forwarded to
+            if "/WEB-INF/" in "/" + rel:
+                continue
+        elif INCLUDE_DIR_RE.search(rel.rsplit("/", 1)[0] + "/" if "/" in rel else ""):
             continue
         if framework_php and lang == "php" and re.search(r"(^|/)(application|system|app|vendor|routes|resources|storage|bootstrap)/", rel):
             continue
@@ -791,15 +656,22 @@ def map_routes(target: Path, config: Dict, stack_ids: Optional[set] = None, work
     files = list(iter_source_files(target, config))
     stack_ids = stack_ids or set()
     framework_php = bool(stack_ids & {"php-codeigniter", "php-cakephp", "php-laravel", "php-zend1"})
-    class_index = {p.stem: rel for p, rel in files if p.suffix == ".java"}
+    class_index = build_class_index(rel for _, rel in files)
     texts: Dict[str, str] = {}
 
-    # 1. XML pre-pass (web.xml / struts.xml declarative mappings)
-    for p, rel in files:
-        if p.suffix.lower() == ".xml":
-            t = read_text(p, enc)
-            if "<servlet" in t or "<action" in t:
-                xml_declared(c, rel, t, class_index)
+    # 1. XML pre-pass (web.xml / Struts / Spring declarative mappings)
+    xml_texts = {rel: read_text(p, enc) for p, rel in files if p.suffix.lower() == ".xml"}
+    modules: Dict[str, str] = {}
+    beans: Dict[str, str] = {}
+    for rel, t in xml_texts.items():
+        if rel.endswith("web.xml"):
+            modules.update(struts_modules(rel, t))
+        if "<bean" in t:
+            beans.update(collect_spring_beans(t))
+    extension = struts2_action_extension(target, config, xml_texts.values(), enc)
+    for rel, t in xml_texts.items():
+        if "<servlet" in t or "<action" in t or "UrlHandlerMapping" in t:
+            xml_declared(c, rel, t, class_index, modules, beans, extension)
 
     xml_items = list(c.items)
 
@@ -865,20 +737,24 @@ def map_routes(target: Path, config: Dict, stack_ids: Optional[set] = None, work
     # post-pass 1: routes declared in XML -> enrich from the handler class file
     for it in c.items:
         hf = it["handler"]["file"]
+        if it["kind"] == "declared_route" and it["handler"]["line"] == 1 and hf in texts and hf.endswith(".java"):
+            it["handler"]["line"] = entry_method_line(texts[hf], it["handler"].get("symbol")) or 1
         if it["kind"] == "declared_route" and not it["id_params"] and hf in texts and hf.endswith(".java"):
             t = texts[hf]
             it["id_params"] = c.inputs("java", t)
             it["guard_hints"] = it["guard_hints"] or c.guards(t)
             it["data_hints"] = it["data_hints"] or c.data_ops(t)
     # post-pass 2: servlet classes without @WebServlet -> take the path from web.xml
-    xml_paths = {it["handler"]["file"]: it["path"] for it in c.items
-                 if it["stack"] == "java-servlet" and it["notes"].startswith("mapped in ")}
+    xml_paths: Dict[str, List[str]] = {}
+    for it in c.items:
+        if it["stack"] == "java-servlet" and it["notes"].startswith("mapped in "):
+            xml_paths.setdefault(it["handler"]["file"], []).append(it["path"])
     keep = []
     for it in c.items:
         if it["path"] == "<see web.xml servlet-mapping>" and it["handler"]["file"] in xml_paths:
-            it["path"] = xml_paths[it["handler"]["file"]]
-            it["notes"] = "path from web.xml"
-        keep.append(it)
+            keep.extend(dict(it, path=mapped, notes="path from web.xml") for mapped in xml_paths[it["handler"]["file"]])
+        else:
+            keep.append(it)
     mapped_with_methods = {it["handler"]["file"] for it in keep if it["notes"] == "path from web.xml"}
     keep = [it for it in keep if not (it["notes"].startswith("mapped in ") and it["handler"]["file"] in mapped_with_methods)]
     for n, it in enumerate(keep, 1):

package/assess/lsa/scripts/merge_findings.py

@@ -403,6 +403,8 @@ def main() -> int:
                                     "injection_candidates_without_verdict", "bfla_routes_without_verdict",
                                     "mass_candidates_without_verdict", "validation_errors",
                                     "new_issues_from_verifier"))
+    for error in cov.get("validation_errors") or []:
+        print(f"validation error (finding not merged): {error}", file=sys.stderr)
     print(json.dumps({"summary": summary, "coverage_gaps": gaps}, indent=2))
     return 1 if gaps else 0
 

package/assess/lsa/scripts/redaction.py

@@ -0,0 +1,118 @@
+"""Secret redaction for code excerpts: Tier 1 snippets and every excerpt the headless agents send to a model (#350).
+
+Pattern-based, so it cannot catch every secret: the pilot runbook also leaves key and environment config files
+out of the source copy. Standard-library only (Python 3.8+ compatible).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+MASK = "[REDACTED]"
+# Longer lines (minified bundles, generated data) are dropped whole: they are not useful to an auditor and
+# keep the regexes below from running on megabyte-long input
+MAX_LINE_CHARS = 4000
+
+# A secret-like key name; the lookahead keeps passwordPolicy, tokenizer and Passenger out
+_KW = r"(?:password|passwd|passphrase|pwd|pw|pass|secret|credential|api[_-]?key|token)(?![a-z])"
+_NAME_TAGS = r"(?:param-name|name|key)"
+_VALUE_TAGS = r"(?:param-value|value)"
+
+
+def _rx(pattern: str, flags: int = re.IGNORECASE) -> re.Pattern[str]:
+    return re.compile(pattern, flags)
+
+
+# (pattern, replacement); applied in order to each line
+_RULES: Tuple[Tuple[re.Pattern[str], str], ...] = (
+    # -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- on one line
+    (_rx(r"(-----BEGIN [A-Z ]*PRIVATE KEY-----).*?(-----END [A-Z ]*PRIVATE KEY-----)", 0), r"\1" + MASK + r"\2"),
+    # "password": "x", 'password' => 'x', pw = "x", keystorePass="x", setProperty("mail.smtp.password", "x")
+    (_rx(r"(?<![\w.\-])((['\"]?)[\w.\-]*?" + _KW + r"\2\s*(?:=>|->|[=:,])\s*)(['\"])[^'\"]+\3"), r"\1\3" + MASK + r"\3"),
+    # conn.setPassword("x"), setKeystorePass("x")
+    (_rx(r"(\bset\w*?" + _KW + r"\s*\(\s*)(['\"])[^'\"]*\2"), r"\1\2" + MASK + r"\2"),
+    # DriverManager.getConnection(url, "sa", "x")
+    (_rx(r"(\bgetConnection\s*\([^,()]*,[^,()]*,\s*)(['\"])[^'\"]*\2"), r"\1\2" + MASK + r"\2"),
+    # new PasswordAuthentication("u", "x".toCharArray())
+    (_rx(r"(\bPasswordAuthentication\s*\([^,()]*,\s*)(['\"])[^'\"]*\2"), r"\1\2" + MASK + r"\2"),
+    # <property name="jdbc.password" value="x"/>
+    (_rx(r"(\bname\s*=\s*['\"][^'\"]*?" + _KW + r"[^'\"]*['\"][^>]*?\bvalue\s*=\s*)(['\"])[^'\"]*\2"),
+     r"\1\2" + MASK + r"\2"),
+    # <param-name>password</param-name><param-value>x</param-value>
+    (_rx(r"(<" + _NAME_TAGS + r">[^<]*?" + _KW + r"[^<]*</" + _NAME_TAGS + r">\s*<" + _VALUE_TAGS + r">)[^<]+"),
+     r"\1" + MASK),
+    # <password>x</password>
+    (_rx(r"(<([\w.\-:]*?" + _KW + r")\s*>)[^<]+(?=</\2\s*>)"), r"\1" + MASK),
+    # jdbc:sqlserver://h;password=x  ?pwd=x&  password={a;b}
+    (_rx(r"([;?&](?:password|passwd|pwd)=)(?:\{[^}]*\}|[^;\"'&\s]+)"), r"\1" + MASK),
+    # scheme://user:pass@host
+    (_rx(r"(?<![a-z0-9+.\-])([a-z][a-z0-9+.\-]*://[^/\s:@\"']+:)[^@\s\"'/]+@"), r"\1" + MASK + "@"),
+    # jdbc:oracle:thin:user/pass@host
+    (_rx(r"(\bjdbc:oracle:\w+:[^/\s:@\"']+/)[^@\s\"']+@"), r"\1" + MASK + "@"),
+    # Authorization: Basic xxx / Bearer xxx
+    (_rx(r"(\b(?:Basic|Bearer)\s+)[A-Za-z0-9._~+/=\-]{8,}"), r"\1" + MASK),
+    # Well-known token formats (case-sensitive)
+    (_rx(r"\b(?:AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{30,}|github_pat_\w{20,}|sk-[A-Za-z0-9_\-]{20,}"
+         r"|AIza[0-9A-Za-z_\-]{35})\b", 0), MASK),
+    # Unquoted config values (.properties, YAML, .env) on their own line; ${PLACEHOLDER} and code are kept
+    (_rx(r"^(\s*[\w.\-]*?" + _KW + r"[\w.\-]*\s*[=:]\s*)(?![\"'$=\s])[^\s\"'(){}<>,;]+\s*(?:(?:#|//).*)?$"), r"\1" + MASK),
+    # Dotted config keys inside comments or strings: <%-- db.password=x --%>
+    (_rx(r"(?<![\w.\-])([\w\-]+\.[\w.\-]*?" + _KW + r"[\w\-]*\s*=\s*)(?![\"'$=\s])[^\s\"'(){}<>,;]+(?=\s|$|[\"'])"),
+     r"\1" + MASK),
+)
+
+_PRIVATE_KEY_BEGIN = _rx(r"-----BEGIN [A-Z ]*PRIVATE KEY-----", 0)
+_PRIVATE_KEY_END = _rx(r"-----END [A-Z ]*PRIVATE KEY-----", 0)
+# A secret name whose value follows on a later line: <property name="password"\n value="x"/>, web.xml params
+_PENDING_NAME = _rx(r"\bname\s*=\s*['\"][^'\"]*?" + _KW + r"[^'\"]*['\"]|<" + _NAME_TAGS + r">[^<]*?" + _KW)
+_PENDING_VALUE: Tuple[Tuple[re.Pattern[str], str], ...] = (
+    (_rx(r"(\bvalue\s*=\s*)(['\"])[^'\"]*\2"), r"\1\2" + MASK + r"\2"),
+    (_rx(r"(<" + _VALUE_TAGS + r">)[^<]+"), r"\1" + MASK),
+)
+_PENDING_LINES = 2
+
+
+def _too_long(s: str) -> Optional[str]:
+    return f"[line of {len(s)} characters omitted]" if len(s) > MAX_LINE_CHARS else None
+
+
+def redact(s: str) -> str:
+    """Mask secrets in one line of code or config."""
+    omitted = _too_long(s)
+    if omitted:
+        return omitted
+    for pattern, repl in _RULES:
+        s = pattern.sub(repl, s)
+    return s
+
+
+def _redact_pending(line: str) -> Tuple[str, bool]:
+    for pattern, repl in _PENDING_VALUE:
+        masked, n = pattern.subn(repl, line)
+        if n:
+            return masked, True
+    return line, False
+
+
+def redact_lines(lines: List[str]) -> List[str]:
+    """Redact each line, blank out private key bodies and mask values split from their names.
+
+    The line count stays the same, so line numbers in excerpts remain valid.
+    """
+    out: List[str] = []
+    in_key, pending = False, 0
+    for line in lines:
+        if in_key:
+            in_key = not _PRIVATE_KEY_END.search(line)
+            out.append(MASK if in_key else line)
+            continue
+        masked = redact(line)
+        if pending:
+            masked, done = _redact_pending(masked)
+            pending = 0 if done else pending - 1
+        if _PENDING_NAME.search(line) and MASK not in masked:
+            pending = _PENDING_LINES
+        in_key = bool(_PRIVATE_KEY_BEGIN.search(line)) and not _PRIVATE_KEY_END.search(line)
+        out.append(masked)
+    return out