Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

pscan: move core help and add API help page #5943

Merged
merged 1 commit into from
Nov 25, 2024
Merged

pscan: move core help and add API help page #5943

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion addOns/pscan/src/main/java/org/zaproxy/addon/pscan/internal/ui/OptionsPassiveScan.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ public void saveParam(Object obj) throws Exception {

@Override
public String getHelpIndex() {
return "ui.dialogs.options.pscan";
return "addon.pscan.options.tags";
}

private static class ScannersMultipleOptionsPanel
Expand Down
2 changes: 1 addition & 1 deletion ...s/pscan/src/main/java/org/zaproxy/addon/pscan/internal/ui/PassiveScannerOptionsPanel.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,6 @@ public void saveParam(Object obj) throws Exception {

@Override
public String getHelpIndex() {
return "ui.dialogs.options.pscan.main";
return "addon.pscan.options.scanner";
}
}
2 changes: 1 addition & 1 deletion addOns/pscan/src/main/java/org/zaproxy/addon/pscan/internal/ui/PolicyPassiveScanPanel.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,6 @@ public void setPassiveScanTableModel(PolicyPassiveScanTableModel categoryTableMo

@Override
public String getHelpIndex() {
return "ui.dialogs.options.pscanrules";
return "addon.pscan.options.rules";
}
}
5 changes: 5 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/common/map.jhm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,12 @@
<map version="1.0">
<mapID target="addon.pscan.icon" url="images/pscan.png" />
<mapID target="addon.pscan" url="../help/contents/pscan.html" />
<mapID target="addon.pscan.api" url="../help/contents/api.html" />
<mapID target="addon.pscan.automation" url="../help/contents/automation.html" />
<mapID target="addon.pscan.automation.pscanconf" url="../help/contents/job-pscanconf.html" />
<mapID target="addon.pscan.automation.pscanwait" url="../help/contents/job-pscanwait.html" />
<mapID target="addon.pscan.options" url="../help/contents/options/options.html" />
<mapID target="addon.pscan.options.rules" url="../help/contents/options/rules.html" />
<mapID target="addon.pscan.options.scanner" url="../help/contents/options/scanner.html" />
<mapID target="addon.pscan.options.tags" url="../help/contents/options/tags.html" />
</map>
86 changes: 86 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/api.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<TITLE>Passive Scanner API</TITLE>
</HEAD>
<BODY>
<H1>Passive Scanner API</H1>
The following operations are added to the API:

<h3>Actions</h3>
<ul>
<li>
clearQueue: Clears the passive scan queue.
</li>
<li>
disableAllScanners: Disables all passive scan rules.
</li>
<li>
disableAllTags: Disables all passive scan tags.
</li>
<li>
disableScanners (ids*): Disables passive scan rules.
<ul>
<li>ids: A comma separated list of scan rule IDs.</li>
</ul>
</li>
<li>
enableAllScanners: Enables all passive scan rules.
</li>
<li>
enableAllTags: Enables all passive scan tags.
</li>
<li>
enableScanners (ids*): Enables passive scan rules.
<ul>
<li>ids: A comma separated list of scan rule IDs.</li>
</ul>
</li>
<li>
setEnabled (enabled*): Sets whether or not the passive scanning is enabled (Note: the enabled state is not persisted).
<ul>
<li>enabled: The enabled state, true or false.</li>
</ul>
</li>
<li>
setMaxAlertsPerRule (maxAlerts*): Sets the maximum number of alerts a passive scan rule can raise.
<ul>
<li>maxAlerts: The maximum number of alerts.</li>
</ul>
</li>
<li>
setScanOnlyInScope (onlyInScope*): Sets whether or not the passive scan should be performed only on messages that are in scope.
<ul>
<li>onlyInScope: The scan state, true or false.</li>
</ul>
</li>
<li>
setScannerAlertThreshold (id* alertThreshold*): Sets the alert threshold of a passive scan rule.
<ul>
<li>id: The ID of the scan rule.</li>
<li>alertThreshold: The alert threshold: OFF, DEFAULT, LOW, MEDIUM and HIGH</li>
</ul>
</li>
</ul>

<h3>Views</h3>
<ul>
<li>currentTasks: Shows information about the passive scan tasks currently being run (if any).</li>
<li>maxAlertsPerRule: Gets the maximum number of alerts a passive scan rule should raise.</li>
<li>recordsToScan: The number of records the passive scanner still has to scan.</li>
<li>scanOnlyInScope: Tells whether or not the passive scan should be performed only on messages that are in scope.</li>
<li>scanners: Lists all passive scan rules with their ID, name, enabled state, and alert threshold.</li>
</ul>

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="pscan.html">Passive Scanner</a></td>
<td>the introduction to Passive Scanner add-on</td>
</tr>
</table>

</BODY>
</HTML>
39 changes: 39 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/options/options.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<TITLE>Options</TITLE>
</HEAD>
<BODY>
<H1>Options</H1>

The Passive Scanner add-on provides the following options screens:
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="scanner.html">Passive Scanner</a></td>
<td>Allows to configure the passive scanner.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="rules.html">Passive Scan Rules</a></td>
<td>Allows to configure the passive scan rules.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="tags.html">Passive Scan Tags</a></td>
<td>Allows to configure the tags that are added by the passive scanner.</td>
</tr>
</table>

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="../pscan.html">Passive Scanner</a></td>
<td>the introduction to Passive Scanner add-on</td>
</tr>
</table>

</BODY>
</HTML>
32 changes: 32 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/options/rules.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<TITLE>
Passive Scan Rules
</TITLE>
</HEAD>
<BODY>
<H1>Passive Scan Rules</H1>
<p>
This screen allows you to configure the passive scan rules.<br>
</p>
<H3>Threshold</H3>
This controls how likely ZAP is to report potential vulnerabilities.<br>
<ul>
<li>If you select Off then the scan rule won't run.</li>
<li>If you select Low then more potential issues will be raised which may increase the number of false positives.</li>
<li>If you select High then fewer potential issues will be raised which may mean that some real issues are missed (false negatives).</li>
</ul>

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="../pscan.html">Passive Scanner</a></td>
<td>the introduction to Passive Scanner add-on</td>
</tr>
</table>

</BODY>
</HTML>
73 changes: 73 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/options/scanner.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<TITLE>Passive Scanner</TITLE>
</HEAD>
<BODY>
<H1>Passive Scanner</H1>
<p>
This screen allows you to configure the passive scanner.

<h2>Configuration Options</h2>
<table border="2">
<tr>
<th>Field</th>
<th>Details</th>
<th>Default</th>
<th>Config File</th>
</tr>
<tr>
<td>Only scan messages in scope</td>
<td>Sets whether or not the passive scan should be performed only on messages that
are in scope.
</td>
<td align="center">Deselected</td>
<td>Key: <code>pscans.scanOnlyInScope</code><br>Values: <code>true</code> or <code>false</code></td>
</tr>
<tr>
<td>Include traffic from the Fuzzer when passive scanning</td>
<td>Sets whether or not the passive scanning should be performed on messages generated by the Fuzzer.</td>
<td align="center">Deselected</td>
<td>Key: <code>pscans.scanFuzzerMessages</code><br>Values: <code>true</code> or <code>false</code></td>
</tr>
<tr>
<td>Max alerts any rule can raise</td>
<td>Sets the maximum number of alerts a passive scan rule should raise. This may be slightly exceeded due to threading.
This setting is typically only useful for automated scanning. Scan rules that exceed this value will be disabled
and will need to be manually enabled if a new session is started.
</td>
<td align="center">0 (unset)</td>
<td>Key: <code>pscans.maxAlertsPerRule</code><br>Values: <code>0</code>: unset or the maximum number of alerts</td>
</tr>
<tr>
<td>Max body size in bytes to scan</td>
<td>Sets the maximum size request or response body size in bytes that the passive scanner will scan.
This can be used if passive scan rules take too long scanning very large requests or responses.
If set the number of ignored requests and responses are recorded in the stats using the keys
<code>stats.pscan.reqBodyTooBig</code> and <code>stats.pscan.respBodyTooBig</code> respectively.
<td align="center">0 (unset)</td>
<td>Key: <code>pscans.maxBodySizeInBytes</code><br>Values: <code>0</code>: unset or the maximum body size in bytes</td>
</td>
</tr>
<tr>
<td>Clear Queue</td>
<td>Empties the passive scan queue without passively scanning the messages.
Currently running rules will run to completion but new rules will only be run when new messages are added to the queue.
<td></td>
<td></td>
</td>
</tr>
</table>

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="../pscan.html">Passive Scanner</a></td>
<td>the introduction to Passive Scanner add-on</td>
</tr>
</table>

</BODY>
</HTML>
48 changes: 48 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/options/tags.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<TITLE>
Passive Scan Tags
</TITLE>
</HEAD>
<BODY>
<H1>Passive Scan Tags</H1>
<p>
This screen allows you to configure the tags that are added by the passive scanner.
</p>
You can add, modify and remove the tags via the appropriate buttons.

<H2>Tag Interpolation</H2>
In order to allow some flexibility in Tag creation and content it is possible for the user to specify a regular expression with capturing groups
which will be used to replace the group identifiers (ex: $1) in the resulting tag.
<p>
For example, a tag could be defined as follows:
<table border=1>
<tr>
<th>Field</th><th>Value</th><th>Note</th>
</tr>
<tr>
<td>Name:</td><td>Test</td><td>&nbsp;</td>
</tr>
<tr>
<td>Tag:</td><td>$1-SOMETAG</td><td>&nbsp;</td>
</tr>
<tr>
<td>Response Body Regex:</td><td>(\d{3})</td><td>Find strings of 3 numbers, using a capturing group (round brackets).</td>
</tr>
</table>
<b>Result:</b> When 3 digit strings are passively identified in response body content (the regex matches) the messages will be
tagged such as "123-SOMETAG", "345-SOMETAG", etc.

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="../pscan.html">Passive Scanner</a></td>
<td>the introduction to Passive Scanner add-on</td>
</tr>
</table>

</BODY>
</HTML>
44 changes: 44 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/contents/pscan.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,49 @@ <H1>Passive Scanner Add-on</H1>
This add-on supports the <a href="automation.html">Automation Framework</a>.
</p>

<H2>Passive Scan</H1>
<p>
ZAP by default passively scans all messages (e.g. HTTP, WebSocket) sent to the web application being tested.<br>
Passive scanning does not change the messages in any way and is therefore safe to use.<br>
Scanning is performed in the background to ensure that it does not slow down the exploration of an application.
</p>
<p>
The (main) behaviour of the passive scanner can be configured using the <a href="options/scanner.html">Options Passive Scanner Screen</a>.
</p>
<p>
Passive scanning can also be used for automatically adding <a href="https://www.zaproxy.org/docs/desktop/start/features/tags/">tags</a>
and raising <a href="https://www.zaproxy.org/docs/desktop/start/features/alerts/">alerts</a> for potential issues.<br>
A set of rules for automatic tagging are provided by default. These can be changed, deleted or
added to via the <a href="options/tags.html">Options Passive Scan Tags screen</a>.
</p>

<p>
The alerts raised by passive scan rules can be configured using the <a href="options/scanrules.html">Options Passive Scan Rules screen</a>.
</p>

<H2>Official Videos</H2>
<table>
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="https://play.sonatype.com/watch/vDWpoYjHi7fSLYFDQPWgMF">ZAP In Ten: Passive Scanning</a> (10:27)</td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="https://play.vidyard.com/HfENJ3GJB3zbD6sMscDrjD">ZAP In Ten: Passive Scan Scripts</a> (11:53)</td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="https://www.youtube.com/watch?v=Rx42kyrB0nk">Deep Dive: Passive Scanning</a> (27:35)</td></tr>
</table>

<H2>See also</H2>
<table>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="api.html">Passive Scanner API</a></td>
<td>for more details about the Passive Scanner API</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><a href="options/options.html">Options</a></td>
<td>for the provided options screens</td>
</tr>
</table>

</BODY>
</HTML>
2 changes: 2 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/index.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@

<index version="2.0">
<indexitem text="Passive Scanner" target="addon.pscan" />
<indexitem text="Passive Scanner API" target="addon.pscan.api" />
<indexitem text="Passive Scanner Automation" target="addon.pscan.automation"/>
<indexitem text="Passive Scanner Automation - passiveScan-config job" target="addon.pscan.automation.pscanconf" />
<indexitem text="Passive Scanner Automation - passiveScan-wait job" target="addon.pscan.automation.pscanwait" />
<indexitem text="Passive Scanner Options" target="addon.pscan.options" />
</index>
6 changes: 6 additions & 0 deletions addOns/pscan/src/main/javahelp/org/zaproxy/addon/pscan/help/toc.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,16 @@
<tocitem text="ZAP User Guide" tocid="toplevelitem">
<tocitem text="Add Ons" tocid="addons">
<tocitem text="Passive Scanner" image="addon.pscan.icon" target="addon.pscan">
<tocitem text="API" target="addon.pscan.api" />
<tocitem text="Automation Framework" target="addon.pscan.automation">
<tocitem text="Job: passiveScanConfig" target="addon.pscan.automation.pscanconf" />
<tocitem text="Job: passiveScanWait" target="addon.pscan.automation.pscanwait" />
</tocitem>
<tocitem text="Options" target="addon.pscan.options">
<tocitem text="Passive Scanner" target="addon.pscan.options.scanner" />
<tocitem text="Passive Scan Rules" target="addon.pscan.options.rules" />
<tocitem text="Passive Scan Tags" target="addon.pscan.options.tags" />
</tocitem>
</tocitem>
</tocitem>
</tocitem>
Expand Down