Start advertising our (work-in-progress) live documentation at https:…

…//google.github.io/tsunami-security-scanner/

PiperOrigin-RevId: 665195494
Change-Id: I821fd5bc6b2a7b37e943b107f053b7563f55e670

README.md

@@ -6,7 +6,7 @@ Tsunami is a general purpose network security scanner with an extensible plugin
 system for detecting high severity vulnerabilities with high confidence.
 
 To learn more about Tsunami, visit our
-[documentation](https://github.com/google/tsunami-security-scanner/blob/master/docs/index.md).
+[documentation](https://google.github.io/tsunami-security-scanner/).
 
 Tsunami relies heavily on its plugin system to provide basic scanning
 capabilities. All publicly available Tsunami plugins are hosted in a separate

docs/about/index.md

@@ -0,0 +1,29 @@
+## <a name="why_tsunami"></a>Why Tsunami?
+
+When security vulnerabilities or misconfigurations are actively exploited by
+attackers, organizations need to react quickly in order to protect potentially
+vulnerable assets. As attackers increasingly invest in automation, the time
+window to react to a newly released, high severity vulnerability is usually
+measured in hours. This poses a significant challenge for large organizations
+with thousands or even millions of internet-connected systems. In such
+hyperscale environments, security vulnerabilities must be detected and ideally
+remediated in a fully automated fashion. To do so, information security teams
+need to have the ability to implement and roll out detectors for novel security
+issues at scale in a very short amount of time. Furthermore, it is important
+that the detection quality is consistently very high. To solve these challenges,
+we created Tsunami - an extensible network scanning engine for detecting high
+severity vulnerabilities with high confidence in an unauthenticated manner.
+
+## <a name="goal"></a>Goals and Philosophy
+
+*   Tsunami supports small manually curated set of vulnerabilities
+*   Tsunami detects high severity, RCE-like vulnerabilities, which often
+    actively exploited in the wild
+*   Tsunami generates scan results with high confidence and minimal
+    false-positive rate.
+*   Tsunami detectors are easy to implement.
+*   Tsunami is easy to scale, executes fast and scans non-intrusively.
+
+## <a name="naming"></a>Naming
+
+The name "Tsunami" comes from the fact that this scanner is meant be used as part of a larger system to warn owners about automated "attack waves". Automated attacks are similar to tsunamis in the way that they come suddenly, without prior warning and can cause a lot of damage to organizations if no precautions are taken. The term "Tsunami Early Warning System Security Scanning Engine" is quite long and thus the name got abbreviated to Tsunami Scanning Engine, or Tsunami. Hence, the name is not an analogy to tsunamis itself, but to a system that detects them and warns everyone about them.

docs/index.md

@@ -1,45 +1,17 @@
 # Tsunami
 
-## <a name="why_tsunami"></a>Why Tsunami?
-
-When security vulnerabilities or misconfigurations are actively exploited by
-attackers, organizations need to react quickly in order to protect potentially
-vulnerable assets. As attackers increasingly invest in automation, the time
-window to react to a newly released, high severity vulnerability is usually
-measured in hours. This poses a significant challenge for large organizations
-with thousands or even millions of internet-connected systems. In such
-hyperscale environments, security vulnerabilities must be detected and ideally
-remediated in a fully automated fashion. To do so, information security teams
-need to have the ability to implement and roll out detectors for novel security
-issues at scale in a very short amount of time. Furthermore, it is important
-that the detection quality is consistently very high. To solve these challenges,
-we created Tsunami - an extensible network scanning engine for detecting high
-severity vulnerabilities with high confidence in an unauthenticated manner.
-
-## <a name="goal"></a>Goals and Philosophy
-
-*   Tsunami supports small manually curated set of vulnerabilities
-*   Tsunami detects high severity, RCE-like vulnerabilities, which often
-    actively exploited in the wild
-*   Tsunami generates scan results with high confidence and minimal
-    false-positive rate.
-*   Tsunami detectors are easy to implement.
-*   Tsunami is easy to scale, executes fast and scans non-intrusively.
+{% include_relative about/index.md %}
 
 ## <a name="orchestration"></a>How Tsunami Scan Works
 
-See [Tsunami Scan Orchestration](orchestration.md).
+See [Tsunami Scan Orchestration](/docs/orchestration.md).
 
 ## <a name="howto"></a>How do I ...
 
-*   ... [build and execute the scanner?](howto.md#build_n_execute)
-*   ... [install Tsunami plugins?](howto.md#install_plugins)
-*   ... [create a new Tsunami plugin?](howto.md#create_plugins)
+*   ... [build and execute the scanner?](/docs/howto.md#build_n_execute)
+*   ... [install Tsunami plugins?](/docs/howto.md#install_plugins)
+*   ... [create a new Tsunami plugin?](/docs/howto.md#create_plugins)
 *   ...
-    [apply my plugins to certain types of services / software?](howto.md#filter_plugins)
-*   ... [add command line arguments for my plugin?](howto.md#command_line)
-*   ... [add configuration properties for my plugin?](howto.md#configuration)
-
-## <a name="naming"></a>Naming
-
-The name "Tsunami" comes from the fact that this scanner is meant be used as part of a larger system to warn owners about automated "attack waves". Automated attacks are similar to tsunamis in the way that they come suddenly, without prior warning and can cause a lot of damage to organizations if no precautions are taken. The term "Tsunami Early Warning System Security Scanning Engine" is quite long and thus the name got abbreviated to Tsunami Scanning Engine, or Tsunami. Hence, the name is not an analogy to tsunamis itself, but to a system that detects them and warns everyone about them.
+    [apply my plugins to certain types of services / software?](/docs/howto.md#filter_plugins)
+*   ... [add command line arguments for my plugin?](/docs/howto.md#command_line)
+*   ... [add configuration properties for my plugin?](/docs/howto.md#configuration)

docs/orchestration.md

@@ -2,12 +2,10 @@
 
 ## Overview
 
-As of today, Tsunami follows a hardcoded 2-step process when scanning a publicly
-exposed network endpoint (see
-[Future Work](future_work.md#dynamic_orchestration) on the potential
-improvement on the workflow):
+Tsunami follows a hardcoded 2-step process when scanning a publicly
+exposed network endpoint:
 
-*   **Reconnaissance**: In the first step, Tsunami identifies open ports and
+*   **Reconnaissance**: First, Tsunami identifies open ports and
     subsequently fingerprints protocols, services and other software running on
     the target host via a set of fingerprinting plugins. To not reinvent the
     wheel, Tsunami leverages existing tools such as [nmap](https://nmap.org/)
@@ -21,7 +19,7 @@ improvement on the workflow):
 
 Following diagram shows the overall workflow for a Tsunami scan.
 
-![orchestration](img/orchestration.svg)
+![orchestration](/docs/img/orchestration.svg)
 
 ## Reconnaissance
 
@@ -47,8 +45,8 @@ purpose. This allows users to swap the port scanning implementations. To not
 reinvent the wheel, users could choose a Tsunami plugin wrapper around existing
 tools like [nmap](https://nmap.org/) or
 [masscan](https://github.com/robertdavidgraham/masscan). You may find useful
-`PortScanner` implementations can be found in
-[tsunami-security-scanner-plugins](https://github.com/google/tsunami-security-scanner-plugins)
+`PortScanner` implementations in
+[tsunami-security-scanner-plugins](https://github.com/google/tsunami-security-scanner-plugins/tree/master/google/portscan)
 repo.
 
 ### Fingerprinting Phase
@@ -67,10 +65,15 @@ required to identify these applications.
 `ServiceFingerprinter` is a special type of Tsunami plugin that allows users to
 define fingerprinters for a specific network service. By using filtering
 annotations (see
-[how to apply my plugins to certain types of services / software?](howto.md#filter_plugins)),
+[how to apply my plugins to certain types of services / software?](/docs/howto.md#filter_plugins)),
 Tsunami will be able to automatically invoke appropriate `ServiceFingerprinter`s
 when it identifies matching network services.
 
+Tsunami only performs service fingerprinting for web services,
+using the
+[`WebServiceFingerprinter`](https://github.com/google/tsunami-security-scanner-plugins/blob/71c57f6bc151a3d97675d74c904a175172c77df4/google/fingerprinters/web/src/main/java/com/google/tsunami/plugins/fingerprinters/web/WebServiceFingerprinter.java)
+plugin.
+
 ### Reconnaissance Report
 
 At the end of the reconnaissance step, Tsunami compiles both the port scanner
@@ -85,16 +88,14 @@ on the information gathered in the Reconnaissance step. `VulnDetector`'s
 detection logic could either be implemented as plain Java code, or as a separate
 binary / script using a different language like python or go. External binaries
 and scripts have to be executed as separate processes outside of Tsunami using
-Tsunami's command execution util. See
-[Future Work](future_work.md#multi_lang_plugins) for our design ideas of
-making Tsunami plugins language agnostic.
+Tsunami's command execution util.
 
 ### Detector Selection
 
 Usually one `VulnDetector` only verifies one vulnerability and the vulnerability
 often only affects one type of network service or software. In order to avoid
 doing wasteful work, Tsunami allows plugins to be annotated by some filtering
-annotations (see [how-to guide](howto.md#filter_plugins) for details) to limit
+annotations (see [how-to guide](/docs/howto.md#filter_plugins) for details) to limit
 the scope of the plugin.
 
 Then before the Vulnerability Verification step starts, Tsunami will select