ascanrulesAlpha: Add example alerts to example rules

- CHANGELOG > Added change note.
- Scan Rules > Added example alert handling, updated to conform to the
common active scan rule tests.
- Scan Rule Unit Tests > Added to assert the example alert and
references, as well as common tests.

Signed-off-by: kingthorin <[email protected]>

Author: kingthorin

addOns/ascanrulesAlpha/CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Changed
 - Update minimum ZAP version to 2.15.0.
 - Maintenance changes.
+- The Example scan rules now include example alerts in order to be more representative of what's expected (Issue 6119).
 
 ### Fixed
 - Alert text for various rules has been updated to more consistently use periods and spaces in a uniform manner.

addOns/ascanrulesAlpha/src/main/java/org/zaproxy/zap/extension/ascanrulesAlpha/ExampleFileActiveScanRule.java

@@ -43,7 +43,8 @@
  *
  * @author psiinon
  */
-public class ExampleFileActiveScanRule extends AbstractAppParamPlugin {
+public class ExampleFileActiveScanRule extends AbstractAppParamPlugin
+        implements CommonActiveScanRuleInfo {
 
     /** Prefix for internationalized messages used by this rule */
     private static final String MESSAGE_PREFIX = "ascanalpha.examplefile.";
@@ -155,14 +156,7 @@ public void scan(HttpMessage msg, String param, String value) {
                 String evidence;
                 if ((evidence = doesResponseContainString(msg.getResponseBody(), attack)) != null) {
                     // Raise an alert
-                    newAlert()
-                            .setConfidence(Alert.CONFIDENCE_MEDIUM)
-                            .setParam(param)
-                            .setAttack(attack)
-                            .setOtherInfo(getOtherInfo())
-                            .setEvidence(evidence)
-                            .setMessage(testMsg)
-                            .raise();
+                    createAlert(param, attack, evidence).setMessage(testMsg).raise();
                     return;
                 }
             }
@@ -194,6 +188,15 @@ private String doesResponseContainString(HttpBody body, String str) {
         return null;
     }
 
+    private AlertBuilder createAlert(String param, String attack, String evidence) {
+        return newAlert()
+                .setConfidence(Alert.CONFIDENCE_MEDIUM)
+                .setParam(param)
+                .setAttack(attack)
+                .setOtherInfo(getOtherInfo())
+                .setEvidence(evidence);
+    }
+
     private static List<String> loadFile(String file) {
         /*
          * ZAP will have already extracted the file from the add-on and put it underneath the 'ZAP home' directory
@@ -244,4 +247,9 @@ public int getWascId() {
         // The WASC ID
         return 0;
     }
+
+    @Override
+    public List<Alert> getExampleAlerts() {
+        return List.of(createAlert("foo", "<SCRIPT>a=/XSS/", "<SCRIPT>a=/XSS/").build());
+    }
 }

addOns/ascanrulesAlpha/src/main/java/org/zaproxy/zap/extension/ascanrulesAlpha/ExampleSimpleActiveScanRule.java

@@ -20,6 +20,7 @@
 package org.zaproxy.zap.extension.ascanrulesAlpha;
 
 import java.io.IOException;
+import java.util.List;
 import java.util.Random;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
@@ -39,7 +40,8 @@
  *
  * @author psiinon
  */
-public class ExampleSimpleActiveScanRule extends AbstractAppParamPlugin {
+public class ExampleSimpleActiveScanRule extends AbstractAppParamPlugin
+        implements CommonActiveScanRuleInfo {
 
     // wasc_10 is Denial of Service - well, its just an example ;)
     private static final Vulnerability VULN = Vulnerabilities.getDefault().get("wasc_10");
@@ -59,8 +61,7 @@ public int getId() {
 
     @Override
     public String getName() {
-        // Strip off the "Example Active Scan Rule: " part if implementing a real one ;)
-        return "Example Active Scan Rule: " + VULN.getName();
+        return Constant.messages.getString("ascanalpha.examplesimple.name");
     }
 
     @Override
@@ -118,12 +119,7 @@ public void scan(HttpMessage msg, String param, String value) {
             // For this example we're just going to raise the alert at random!
 
             if (rnd.nextInt(10) == 0) {
-                newAlert()
-                        .setConfidence(Alert.CONFIDENCE_MEDIUM)
-                        .setParam(param)
-                        .setAttack(value)
-                        .setMessage(testMsg)
-                        .raise();
+                createAlert(param, attack).setMessage(testMsg).raise();
                 return;
             }
 
@@ -132,6 +128,10 @@ public void scan(HttpMessage msg, String param, String value) {
         }
     }
 
+    private AlertBuilder createAlert(String param, String attack) {
+        return newAlert().setConfidence(Alert.CONFIDENCE_MEDIUM).setParam(param).setAttack(attack);
+    }
+
     @Override
     public int getRisk() {
         return Alert.RISK_HIGH;
@@ -148,4 +148,9 @@ public int getWascId() {
         // The WASC ID
         return 0;
     }
+
+    @Override
+    public List<Alert> getExampleAlerts() {
+        return List.of(createAlert("foo", "attack").build());
+    }
 }

addOns/ascanrulesAlpha/src/main/javahelp/org/zaproxy/zap/extension/ascanrulesAlpha/resources/help/contents/ascanalpha.html

@@ -9,14 +9,14 @@
 <H1>Active Scan Rules - Alpha</H1>
 The following alpha status active scan rules are included in this add-on:
 
-<H2>An example active scan rule which loads data from a file</H2>
+<H2 id="id-60101">An example active scan rule which loads data from a file</H2>
 This implements an example active scan rule that loads strings from a file that the user can edit.<br>
 For more details see: 
 <a href="https://www.zaproxy.org/blog/2014-04-30-hacking-zap-4-active-scan-rules/">Hacking ZAP Part 4: Active Scan Rules</a>.
 <p>
 Latest code: <a href="https://github.com/zaproxy/zap-extensions/blob/main/addOns/ascanrulesAlpha/src/main/java/org/zaproxy/zap/extension/ascanrulesAlpha/ExampleFileActiveScanRule.java">ExampleFileActiveScanRule.java</a>
 
-<H2>Example Active Scan Rule: Denial of Service</H2>
+<H2 id="id-60100">Example Active Scan Rule: Denial of Service</H2>
 This implements a very simple example active scan rule.<br>
 For more details see: 
 <a href="https://www.zaproxy.org/blog/2014-04-30-hacking-zap-4-active-scan-rules/">Hacking ZAP Part 4: Active Scan Rules</a>.

addOns/ascanrulesAlpha/src/main/resources/org/zaproxy/zap/extension/ascanrulesAlpha/resources/Messages.properties

@@ -6,6 +6,8 @@ ascanalpha.examplefile.other = This is for information that doesnt fit in any of
 ascanalpha.examplefile.refs = https://www.zaproxy.org/blog/2014-04-30-hacking-zap-4-active-scan-rules/
 ascanalpha.examplefile.soln = A general description of how to solve the problem.
 
+ascanalpha.examplesimple.name = "Example Active Scan Rule: Denial of Service"
+
 #ascanalpha.ldapinjection.alert.attack=[{0}] field [{1}] set to [{2}]
 ascanalpha.ldapinjection.alert.attack = parameter [{0}] set to [{1}]
 #ascanalpha.ldapinjection.alert.extrainfo=[{0}] field [{1}] on [{2}] [{3}] may be vulnerable to LDAP injection, using an attack with LDAP meta-characters [{4}], yielding known [{5}] error message [{6}], which was not present in the original response.

addOns/ascanrulesAlpha/src/test/java/org/zaproxy/zap/extension/ascanrulesAlpha/ExampleFileActiveScanRuleUnitTest.java

@@ -0,0 +1,63 @@
+/*
+ * Zed Attack Proxy (ZAP) and its related class files.
+ *
+ * ZAP is an HTTP/HTTPS proxy for assessing web application security.
+ *
+ * Copyright 2024 The ZAP Development Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.zaproxy.zap.extension.ascanrulesAlpha;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.endsWith;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.is;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.parosproxy.paros.core.scanner.Alert;
+
+public class ExampleFileActiveScanRuleUnitTest
+        extends ActiveScannerTest<ExampleFileActiveScanRule> {
+
+    @Override
+    protected ExampleFileActiveScanRule createScanner() {
+        return new ExampleFileActiveScanRule();
+    }
+
+    @Test
+    void shouldHaveExpectedExample() {
+        // Given / When
+        List<Alert> alerts = rule.getExampleAlerts();
+        // Then
+        assertThat(alerts, hasSize(1));
+        Alert alert = alerts.get(0);
+        assertThat(alert.getParam(), is(equalTo("foo")));
+    }
+
+    @Test
+    void shouldHaveHelpLink() {
+        // Given / When
+        String helplink = rule.getHelpLink();
+        // Then
+        assertThat(helplink, endsWith("60101"));
+    }
+
+    @Test
+    @Override
+    public void shouldHaveValidReferences() {
+        super.shouldHaveValidReferences();
+    }
+}

addOns/ascanrulesAlpha/src/test/java/org/zaproxy/zap/extension/ascanrulesAlpha/ExampleSimpleActiveScanRuleUnitTest.java

@@ -0,0 +1,63 @@
+/*
+ * Zed Attack Proxy (ZAP) and its related class files.
+ *
+ * ZAP is an HTTP/HTTPS proxy for assessing web application security.
+ *
+ * Copyright 2024 The ZAP Development Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.zaproxy.zap.extension.ascanrulesAlpha;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.endsWith;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.is;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.parosproxy.paros.core.scanner.Alert;
+
+public class ExampleSimpleActiveScanRuleUnitTest
+        extends ActiveScannerTest<ExampleSimpleActiveScanRule> {
+
+    @Override
+    protected ExampleSimpleActiveScanRule createScanner() {
+        return new ExampleSimpleActiveScanRule();
+    }
+
+    @Test
+    void shouldHaveExpectedExample() {
+        // Given / When
+        List<Alert> alerts = rule.getExampleAlerts();
+        // Then
+        assertThat(alerts, hasSize(1));
+        Alert alert = alerts.get(0);
+        assertThat(alert.getParam(), is(equalTo("foo")));
+    }
+
+    @Test
+    void shouldHaveHelpLink() {
+        // Given / When
+        String helplink = rule.getHelpLink();
+        // Then
+        assertThat(helplink, endsWith("60100"));
+    }
+
+    @Test
+    @Override
+    public void shouldHaveValidReferences() {
+        super.shouldHaveValidReferences();
+    }
+}