ascanrules: XXE example alerts

addOns/ascanrules/CHANGELOG.md

@@ -4,7 +4,8 @@ All notable changes to this add-on will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
-
+### Changed
+- The XML External Entity Attack scan rule now include example alert functionality for documentation generation purposes (Issue 6119).
 
 ## [68] - 2024-09-24
 ### Changed

addOns/ascanrules/src/main/java/org/zaproxy/zap/extension/ascanrules/XxeScanRule.java

@@ -21,6 +21,7 @@
 
 import java.io.IOException;
 import java.text.MessageFormat;
+import java.util.List;
 import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -325,12 +326,7 @@ private void localFileInclusionAttack(HttpMessage msg) {
                 String response = msg.getResponseBody().toString();
                 Matcher matcher = LOCAL_FILE_PATTERNS[idx].matcher(response);
                 if (matcher.find()) {
-                    newAlert()
-                            .setConfidence(Alert.CONFIDENCE_MEDIUM)
-                            .setAttack(payload)
-                            .setEvidence(matcher.group())
-                            .setMessage(msg)
-                            .raise();
+                    createAlert(payload, matcher.group()).setMessage(msg).raise();
                 }
                 if (isStop()) {
                     return;
@@ -383,12 +379,7 @@ private boolean localFileReflectionTest(HttpMessage msg, String requestBody) {
             String response = msg.getResponseBody().toString();
             Matcher matcher = LOCAL_FILE_PATTERNS[idx].matcher(response);
             if (matcher.find()) {
-                newAlert()
-                        .setConfidence(Alert.CONFIDENCE_MEDIUM)
-                        .setAttack(payload)
-                        .setEvidence(matcher.group())
-                        .setMessage(msg)
-                        .raise();
+                createAlert(payload, matcher.group()).setMessage(msg).raise();
                 return true;
             }
             if (isStop()) {
@@ -405,4 +396,25 @@ static String createTagSpecificLfrPayload(String requestBody, Matcher tagMatcher
         sb.append(requestBody.substring(tagMatcher.end(1)));
         return sb.toString();
     }
+
+    private AlertBuilder createAlert(String attack, String evidence) {
+        return newAlert()
+                .setConfidence(Alert.CONFIDENCE_MEDIUM)
+                .setAttack(attack)
+                .setEvidence(evidence);
+    }
+
+    @Override
+    public List<Alert> getExampleAlerts() {
+        return List.of(
+                createAlert(
+                                "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+                                        + "<!DOCTYPE foo [\n"
+                                        + "  <!ELEMENT foo ANY >\n"
+                                        + "  <!ENTITY zapxxe SYSTEM \"file:///etc/passwd\">\n"
+                                        + "]>\n"
+                                        + "<comment><text>&zapxxe;</text></comment>",
+                                "root:*:0:0")
+                        .build());
+    }
 }

addOns/ascanrules/src/test/java/org/zaproxy/zap/extension/ascanrules/XxeScanRuleUnitTest.java

@@ -22,6 +22,7 @@
 import static fi.iki.elonen.NanoHTTPD.newFixedLengthResponse;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
 import static org.hamcrest.Matchers.is;
 
 import fi.iki.elonen.NanoHTTPD;
@@ -314,6 +315,20 @@ void shouldAlertOnlyIfCertainTagValuesArePresent()
         assertThat(alert.getConfidence(), equalTo(Alert.CONFIDENCE_MEDIUM));
     }
 
+    @Test
+    void shouldHaveExpectedExampleAlert() {
+        // Given / When
+        List<Alert> alerts = rule.getExampleAlerts();
+        // Then
+        assertThat(alerts, hasSize(1));
+    }
+
+    @Test
+    @Override
+    public void shouldHaveValidReferences() {
+        super.shouldHaveValidReferences();
+    }
+
     private static NanoServerHandler createNanoHandler(
             String path, NanoHTTPD.Response.IStatus status, String responseBody) {
         return new NanoServerHandler(path) {