move trojans (csd-post.sh, csd-wrapper.sh, hipreport.sh, tncc-wrapper…

….py) to trojans/ subdirectory and expand and clarify their documentation

Signed-off-by: Daniel Lenski <dlenski@gmail.com>

Makefile.am

@@ -130,7 +130,7 @@ pkgconfig_DATA = openconnect.pc
 
 EXTRA_DIST = version.sh README.TESTS COPYING.LGPL $(lib_srcs_openssl) $(lib_srcs_gnutls)
 EXTRA_DIST += $(shell cd "$(top_srcdir)" && \
-		git ls-tree HEAD -r --name-only -- android/ java/ 2>/dev/null)
+		git ls-tree HEAD -r --name-only -- android/ java/ trojans/ 2>/dev/null)
 
 DISTCLEANFILES = $(pkgconfig_DATA)
 

www/Makefile.am

@@ -3,7 +3,7 @@
 SUBDIRS = styles inc images
 CONV 	= "$(srcdir)/html.py"
 
-FTR_PAGES = csd.html charset.html token.html pkcs11.html tpm.html features.html gui.html nonroot.html hip.html
+FTR_PAGES = csd.html charset.html token.html pkcs11.html tpm.html features.html gui.html nonroot.html hip.html tncc.html
 START_PAGES = building.html connecting.html manual.html vpnc-script.html 
 INDEX_PAGES = changelog.html download.html index.html packages.html platforms.html licence.html
 PROTO_PAGES = anyconnect.html juniper.html globalprotect.html

www/anyconnect.xml

@@ -16,9 +16,16 @@
 HTTPS and <a href="http://www.rfc-editor.org/rfc/rfc4347.txt">DTLS</a>
 protocols. You connect to the secure web server, authenticate using
 certificates and/or arbitrary web forms, and you are rewarded with a
-standard HTTP cookie.</p>
+standard HTTP cookie named <tt>webvpn</tt>.</p>
 
-<p>You then use this cookie in an HTTP <tt>CONNECT</tt> request, and can
+<p>Some Cisco servers require you to execute a 'Cisco Secure Desktop'
+trojan binary (intended for security scanning of the client system)
+before authentication can complete; see <a href="csd.html">the CSD
+page</a> for information on how to comply with this requirement, or
+spoof it, with OpenConnect.</p>
+
+<p>After authentication, you use the <tt>webvpn</tt> cookie
+in an HTTP <tt>CONNECT</tt> request, and can
 then pass traffic over that connection. IP addresses and routing
 information are passed back and forth in the headers of that
 <tt>CONNECT</tt> request.</p>

www/csd.xml

@@ -10,6 +10,13 @@
 
 <h1>Cisco Secure Desktop</h1>
 
+<p>The CSD ('Cisco Secure Desktop') mechanism is a security scanner
+for the <a href="anyconnect.html">Cisco AnyConnect</a> VPNs, in the
+same vein as <a href="juniper.html">Juniper's Host Checker (tncc.jar)</a>
+and <a href="hip.html">GlobalProtect's HIP</a>.</p>
+
+<h2>Background</h2>
+
 <p>The 'Cisco Secure Desktop' is a bit of a misnomer &#8212; it works by
 downloading a trojan binary from the server and running it on your
 client machine to perform some kind of 'verification' and post its
@@ -27,5 +34,33 @@ option is used to handle the script in a 'safe' manner.</p>
 This support currently only works when the server has a Linux binary
 installed, and only when that Linux binary runs on the client machine.</p>
 
+<h2>CSD support in OpenConnect</h2>
+
+<p>OpenConnect supports running the CSD binary, or spoofing its
+behaviour, by passing the <tt>--csd-wrapper=SCRIPT</tt> argument
+with a shell script.</p>
+
+<p>The OpenConnect distribution includes <i>two</i> alternative
+scripts to support the execution or spoofing of the CSD behaviour, in
+the <tt>trojans/</tt> subdirectory:</p>
+
+<ul>
+  <li><tt>csd-wrapper.sh</tt>: This script accepts the same options as some versions of the CSD trojan binary,
+  (<tt>-ticket</tt>, <tt>-stub</tt>, <tt>-group</tt>, <tt>-certhash</tt>, <tt>-url</tt>, <tt>-langselen</tt>),
+  downloads the files required by the binary, and then wraps the execution of the <tt>cstub</tt> binary.
+  Because of the security dangers of executing a server-provided trojan binary, this script should ideally be executed
+  with the permissions of a low-privilege user (e.g. <tt>--csd-user=nobody --csd-wrapper=trojans/csd-wrapper.sh</tt>).
+  </li>
+
+  <li><tt>csd-post.sh</tt>: This script does <i>not</i> actually run the CSD trojan binary. Instead, it emulates
+  the behaviour of the CSD trojan, creating a plaintext report similar to the one that the CSD trojans build, and
+  uploading it to the server sent by the VPN gateway. It requires the <tt>xmlstarlet</tt> tool for parsing XML
+  sent by the server, to extract a token value. The report may need to be customized in order to be accepted by some
+  servers; the <a href="https://github.com/Gilks/hostscan-bypass">hostscan-bypass</a> tool may help with this.
+  Because this script does not actually execute a trojan binary, and because its complete output is easily visible
+  in the script, the security concerns are greatly alleviated.
+  </li>
+</ul>
+
 <INCLUDE file="inc/footer.tmpl" />
 </PAGE>

www/hip.xml

@@ -2,7 +2,7 @@
 	<INCLUDE file="inc/header.tmpl" />
 
 	<VAR match="VAR_SEL_FEATURES" replace="selected" />
-	<VAR match="VAR_SEL_FEATURE_CSD" replace="selected" />
+	<VAR match="VAR_SEL_FEATURE_HIP" replace="selected" />
 	<PARSE file="menu1.xml" />
 	<PARSE file="menu2-features.xml" />
 
@@ -27,9 +27,9 @@ the official GlobalProtect VPN client software), which generates an
 <ol>
   <li>Client authenticates and fetches the tunnel configuration from the GlobalProtect gateway.</li>
   <li>Client runs HIP report generator and computes MD5 digest of report.</li>
-  <li>Client checks whether a HIP report is required (<code>/ssl-vpn/hipreportcheck.esp</code>), including its MD5 digest and gateway-assigned IP address in the report.</li>
+  <li>Client checks whether a HIP report is required (<tt>/ssl-vpn/hipreportcheck.esp</tt>), including its MD5 digest and gateway-assigned IP address in the report.</li>
   <li>Gateway responds whether or not a HIP report is required (normally, it doesn't require a new one if a report with the same MD5 digest and same IP address have been submitted recently).</li>
-  <li>Client uploads the complete HIP report to (<code>/ssl-vpn/hipreport.esp</code>).</li>
+  <li>Client uploads the complete HIP report to (<tt>/ssl-vpn/hipreport.esp</tt>).</li>
   <li>Server confirms acceptance of HIP report with a success message.</li>
 </ol>
 
@@ -48,9 +48,9 @@ complete. However, two things can go wrong:</p>
   HIP report contents were not approved.</li>
 </ul>
 
-<h2>HIP support in openconnect</h2>
+<h2>HIP support in OpenConnect</h2>
 
-<p>OpenConnect supports HIP report generation and submission by passing the <code>--csd-wrapper=SCRIPT</code> argument with a shell script to generate a HIP report in the format expected by the
+<p>OpenConnect supports HIP report generation and submission by passing the <tt>--csd-wrapper=SCRIPT</tt> argument with a shell script to generate a HIP report in the format expected by the
 server. This shell script must output the HIP report to standard output and exit successfully (status code 0). The HIP script is called with the following command-line arguments:</p>
 
 <pre>
@@ -72,17 +72,17 @@ server. This shell script must output the HIP report to standard output and exit
 
 <h2>Generating/spoofing a HIP report</h2>
 
-<p>An example <code>hipreport.sh</code> script is included in the
-openconnect distribution.</p>
+<p>An example <tt>hipreport.sh</tt> script is included in the
+OpenConnect distribution, in the <tt>trojans/</tt> subdirectory.</p>
 
 <p>Depending on how picky your GlobalProtect
 VPN is, it may be necessary to spoof or alter some of the parameters
 of the HIP report to match the output of one of the official
 clients. In order to capture the contents of the official Windows
 client's HIP reports, enable the highest logging level for the "PanGPS
-Service", and then sift through the giant <code>PanGPS.log</code> file
+Service", and then sift through the giant <tt>PanGPS.log</tt> file
 (which should be in the same directory as the executables, normally
-<code>c:\Program Files\PaloAlto Networks\GlobalProtect</code>) to find
+<tt>c:\Program Files\PaloAlto Networks\GlobalProtect</tt>) to find
 the HIP report submission.</p>
 
 <INCLUDE file="inc/footer.tmpl" />

www/juniper.xml

@@ -65,23 +65,13 @@ pass the cookie to OpenConnect with its <tt>-C</tt> option, for example:
 </pre>
 </p>
 
-<a name="tncc"><h3>Host Checker (tncc.jar)</h3></a>
+<h3>Host Checker (tncc.jar)</h3>
 
 <p>Many sites require a Java applet to run certain tests as a precondition
-of authentication. This works by sending a <tt>DSPREAUTH</tt> cookie
-to the client which is attempting to authenticate, and the Java code
-in <tt>tncc.jar</tt> then runs and communicates with the server, handing
-back a new value for the <tt>DSPREAUTH</tt> cookie to be used when
-autnentication continues.</p>
-
-<p>OpenConnect supports this with a little assistance. There is a python
-script <tt>tncc-wrapper.py</tt> in the git repository which can be used
-along with the <tt>tncc-preload.so</tt> from
-<a href="https://github.com/russdill/ncsvc-socks-wrapper">this repository</a>.
-It may also be necessary to pass a Mozilla-compatible user agent string:
-<pre>
-  ./openconnect --protocol=nc --useragent 'Mozilla/5.0 (Linux) Firefox' --csd-wrapper=./tncc-wrapper.py vpn.example.com
-</pre>
+of authentication (similar to <a href="csd.html">CSD</a>
+for AnyConnect VPNs and <a href="hip.html">HIP</a> for GlobalProtect VPNs).
+See the <a href="tncc.html">Host Checker / TNCC page</a> for how to configure OpenConnect
+to wrap and run this applet.
 </p>
 
 <h2>Connectivity</h2>

www/menu2-features.xml

@@ -2,11 +2,13 @@
 	<STARTMENU level="2"/>
         <MENU topic="Feature list" link="features.html" mode="VAR_SEL_FEATURE_MAIN" />
 	<MENU topic="Running as non-root user" link="nonroot.html" mode="VAR_SEL_FEATURE_NONROOT" />
-	<MENU topic="Cisco Secure Desktop" link="csd.html" mode="VAR_SEL_FEATURE_CSD" />
 	<MENU topic="GUI" link="gui.html" mode="VAR_SEL_FEATURE_GUI" />
 	<MENU topic="Character sets" link="charset.html" mode="VAR_SEL_FEATURE_CHARSET" />
 	<MENU topic="One Time Passwords" link="token.html" mode="VAR_SEL_FEATURE_TOKEN" />
 	<MENU topic="Smart Cards / PKCS#11" link="pkcs11.html" mode="VAR_SEL_FEATURE_PKCS11" />
 	<MENU topic="Trusted Platform Module (TPM)" link="tpm.html" mode="VAR_SEL_FEATURE_TPM" />
+	<MENU topic="Cisco Secure Desktop (CSD)" link="csd.html" mode="VAR_SEL_FEATURE_CSD" />
+	<MENU topic="Juniper Host Checker (TNCC)" link="tncc.html" mode="VAR_SEL_FEATURE_TNCC" />
+	<MENU topic="Host Integrity Protection (HIP)" link="hip.html" mode="VAR_SEL_FEATURE_HIP" />
 	<ENDMENU />
 </PAGE>

www/tncc.xml

@@ -0,0 +1,55 @@
+<PAGE>
+	<INCLUDE file="inc/header.tmpl" />
+
+	<VAR match="VAR_SEL_FEATURES" replace="selected" />
+	<VAR match="VAR_SEL_FEATURE_TNCC" replace="selected" />
+	<PARSE file="menu1.xml" />
+	<PARSE file="menu2-features.xml" />
+
+	<INCLUDE file="inc/content.tmpl" />
+
+<h1>Juniper Host Checker (tncc.jar)</h1>
+
+<p>The Host Checker mechanism is a security scanner for the <a
+href="juniper.html">Juniper</a> VPNs, in the same vein as <a
+href="csd.html">Cisco's CSD</a> and <a href="hip.html">GlobalProtect's
+HIP</a>.</p>
+
+<h3>Background</h3>
+
+<p>Many sites require a Java applet to run certain tests as a precondition
+of authentication. This works by sending a <tt>DSPREAUTH</tt> cookie
+to the client which is attempting to authenticate, and the Java code
+in <tt>tncc.jar</tt> then runs and communicates with the server, handing
+back a new value for the <tt>DSPREAUTH</tt> cookie to be used when
+autnentication continues.</p>
+
+<p>This Java applet is a black-box binary provided by a server outside
+of the client's control, and therefore has similar security concerns to Cisco's CSD
+trojan.</p>
+
+<h2>TNCC support in OpenConnect</h2>
+
+<p>OpenConnect supports running the tncc.jar binary with a little assistance. A Python wrapper
+script, <tt>tncc-wrapper.py</tt>, is provided in the <tt>trojans/</tt> subdirectory of the
+OpenConnect distribution. It can be used
+along with the <tt>tncc-preload.so</tt> from
+<a href="https://github.com/russdill/ncsvc-socks-wrapper">this repository</a>.
+It may also be necessary to pass a Mozilla-compatible user agent string:
+<pre>
+  ./openconnect --protocol=nc --useragent 'Mozilla/5.0 (Linux) Firefox' --csd-wrapper=trojans/tncc-wrapper.py vpn.example.com
+</pre>
+Because of the security dangers of executing a server-provided trojan binary, this script should ideally be executed
+with the permissions of a low-privilege user (e.g. <tt>--csd-user=nobody</tt>).
+</p>
+
+<p>Alternatively, the <a href="https://github.com/russdill/juniper-vpn-py">juniper-vpn-py</a> project provides a
+<tt>tncc.py</tt> which <i>emulates</i> the behaviour of the <tt>tncc.jar</tt> binary, rather than actually
+executing it. Because this script does not actually execute a server-provided binary, security concerns are greatly
+alleviated. However, this alternative script may require customization to work with VPNs that have modified
+the behaviour of their Host Checker binaries in some way.
+</p>
+
+
+<INCLUDE file="inc/footer.tmpl" />
+</PAGE>