vSphere Admin documentation presents security information in a fragmented way

[zjs]

The vSphere Admin documentation helpfully includes a "Security Reference" section (https://vmware.github.io/vic-product/assets/files/html/1.1/vic_vsphere_admin/security_reference.html).

It would be even better if:

1. All security-related information were included in that section.
2. Other sections referenced readers to the appropriate subsection of the "Security Reference" section when discussing security-related topics.

Some more specific feedback:

• "Networks Used by vSphere Integrated Containers" contains notes like "Because the management network provides access to your vSphere environment, and because container VMs use this network to communicate with the VCH, always use a secure network for the management network.", but does not link to the "Network Security" section of the Security Reference which provides a much more specific statement: "The container VMs communicate with the endpoint VM over the management network when an interactive shell is required. While the communication is encrypted, the public keys are not validated, which leaves scope for man-in-the-middle attacks. This connection is only used for the interactive console when enabled (stdin/out/err), and not for any other purpose."
• "ESXi Host Firewall Requirements" contains information about ports which must be open, and links to instructions for opening those ports, but neither of those sections references the "External Interfaces, Ports, and Services" section of the Security Reference.
• "Open the Required Ports on ESXi Hosts" contains inconsistent information about what --allow will do: will it open "all outbound TCP traffic" (as stated in the introduction) or "open the port" (as stated in the last bullet). If the former, the security considerations should be discussed in the Security Reference.
• The --force and --no-tlsverify options are mentioned in a few places with various amounts of commentary on the security impact, but not at all in the Security Reference. (Including mention in examples with no commentary other than "Disables the verification of clients that connect to this VCH" and "Disables the verification of the ESXi host certificate".) At the very least, all mentions of options like these should refer to a discussion of the security considerations, included in or referenced by the Security Reference.
• "vSphere Target Options " provides questionable instructions for getting the thumbprint; as far as I can tell, using the thumbprint from the error message does not protect against MITM attacks (and is no better than using --force).
• "Security Options" mentions 11 options. Only 2 of these are mentioned in the "Security Reference". There is no link between these sections, except for 2 options mentioned in both places.
• "Security Reference" does not include any discussion of the content from "Debugging the VCH".

[stuclem]

@zjs yes, the Security Reference is not much help. I will attempt to address the comments here in the contexts of #70 and #26.

[stuclem]

@zjs I have overhauled the Security Reference, attempting to address all of the points you made above. Because the Security Reference is for all of VIC, and because most of the security information elsewhere in the doc relates to VIC Engine and VCHs, I have inverted your suggestion of grouping all security information in the reference, and linking to it from the other parts of the doc. So, the Security Reference is now mostly a collection of links to other sections. However, as a part of a wider reorg of the vic-machine options docs, I have grouped all VCH security info into one section.

As a result we now have:

• VCH Security, which groups the docs for the vic-machine TLS options and --ops-user into sub-sections.
• vSphere Integrated Containers Security Reference, which is an overview of security matters for all of VIC (not just Engine).

Does this improve things?

[stuclem]

@zjs another question: how exactly does vic-machine debug affect security, beyond opening some additional ports?

[zjs]

Does this improve things?

Definitely!

how exactly does vic-machine debug affect security, beyond opening some additional ports?

I'm not sure I can provide a complete list, but enabling SSH and setting a root password would both seem to have security implications. I'm also not clear on exactly how the --debug argument to create and the debug command interact. @hickeng or @emlin might be better able to answer that.

[stuclem]

Thanks @zjs - as far as I am aware, vic-machine create --debug 3 activates SSH on the VCH, so in addition to doing a bunch of other stuff, it does the same as vic-machine debug --rootpw xxx --enable-ssh. Is it enough just to mention that as something to be aware of?