Security Issues in Documentation

It's obvious that documenting the security ramifications of using certain product features is important, especially if those features are disabled by default. However, users don't read the documentation until they have to. When you have locked down your product to work with minimal privileges and secure defaults, your users will find that many things that just worked before won't work anymore. Faced with this dilemma, they will turn to your documentation, which should be ready to guide them through using and deploying your code in as secure a manner as feasible.

The Basics

Fundamentally, writing secure documentation means writing good documentation: complete, clear, and concise.

Complete
Where security considerations need to be addressed, whether as a vulnerability in a product or as an administrative consideration, add an appropriate security subtopic or note to alert your reader of the potential concern and ways to handle the concerns. If your product moves unencrypted data across the network or stores a secret in a file, be up front about it so that your users can take appropriate actions to mitigate threats. If a feature's security concerns are extensive, add a high-level Security Considerations subtopic to the feature's documentation.

Remember that security through obscurity is not security. Intentionally omitting security documentation is not synonymous with mitigating that security vulnerability. Attackers will eventually locate the vulnerability whether or not it's documented. If the threat is so dire that documenting it would be tantamount to admitting the feature is insecure, the feature is insecure.

NOTE
From experience, users gravitate to a topic marked Security Considerations in the documentation because all the important advice is in one place.

Clear
Security information should be covered in the appropriate place and at the appropriate level in the table of contents. Be clear and straightforward about your product's known risks and ramifications. Don't bury all security-related information in an appendix. Instead, place notices on the security implications of a feature in the documentation of that feature, with a pointer or link to a more complete explanation, if necessary. Ensure that the documentation describes security concerns and tasks at the level an administrator of this feature is expected to be at. Assuming advanced understanding of security for an administrator who knows only the desired application defeats the purpose of clear documentation.
Concise
Give users step-by-step guides to employing your product securely. Don't give them lots of supplemental information on how public key encryption works or how hash functions can be inverted only in nonpolynomial time. They are usually more interested in the practice than the theory, and numerous excellent references are available for the theory. For completeness, offer references or a bibliography for background or nice-to-know information. In this way the documentation tells them what they need to know now to complete a task and where to get information later for better comprehension of the topic.

During the editorial process, editors and writers should always be aware of their responsibility to proactively encourage trustworthy documentation. Technical writers and editors should be knowledgeable about threat modeling and basic security issues as they write and review material. If they are writing programmer documentation, they should be familiar with all known-to-be-dangerous APIs and query them when they occur in the material.

Always ask your documentation's technical reviewers if there are known security issues in the product and verify that the new feature or API has been tested for security by the development team. These two items should be part of your standard tech review checklist.

Threat Mitigation Through Documentation

Technical writers and editors should participate in the threat-modeling phase of the product and take note of aspects of the product that might require specialized documentation. Sometimes the product team will decide that the appropriate mitigation for a particular threat is The product shouldn't be deployed in that configuration! or, dare I say it, The product cannot be deployed in a secure manner! Every such mitigation should become a very visible note in the appropriate place in your product documentation.

Remember that shipping an insecure default configuration and relying on users to read the documentation to make themselves secure is not a good idea. You should raise an alarm if you notice many threats mitigated by Read the documentation. While writing screeds of documentation may keep you in work, it's a disservice to your clients.

IMPORTANT
Shipping an insecure default configuration and relying on users to read the documentation to make themselves secure is not a good idea.

Documenting Security Best Practices

When documenting a product (or a subsystem of a large product), include a Security Best Practices topic that explains how to employ the product (or subsystem) securely as it relates to specific threats. It's worthwhile having the administrative users of your product think in terms of threats.

The following example addresses the security concerns surrounding the deployment of a mythical SOAP-Server product:

SOAP-Server allows code stored in SOAP scripts on your server to be executed remotely by clients.

By default, SOAP-Server executes your code within the security context of the server process. In some cases, this might be more privilege than you want to grant. (For example, the process can open network sockets.) In other cases, this might be less privilege than is required for successful operation. (For example, the process cannot read arbitrary users' files.) Always execute your code with the least possible privilege required to accomplish its task. For instructions on how to configure the identity with which a SOAP script executes, see Configuring the Execution Environment.

Data exchanged between SOAP-Server and a client might in some cases be sensitive and subject to information disclosure threats. If this is the case, consider activating the Encrypt Communications check box for the relevant script. Encrypt Communications uses Transport Layer Security (TLS) technology such that the communication channel between the client and SOAP-Server cannot be monitored. Other technologies, such as Internet Protocol Security (IPSec), can be used instead of or as a complement to this technology to provide additional security.

You might want to restrict access to SOAP scripts to certain clients. SOAP-Server allows you to restrict access based on IP address or identity as verified by an authentication scheme. For instructions on how to enable access restrictions, see Enabling Access Restrictions and Enabling Authentication.

Note: if you authenticate users, you could also have an extra layer of defense by employing access control lists (ACLs) on the SOAP scripts. For information about setting ACLs, search for Access Control Lists in the Windows .NET Server on-line help.

Clients access SOAP-Server on port 80 (for unencrypted sessions) or port 443 (for encrypted sessions) using TCP. If you want to make your SOAP scripts accessible only on your LAN, configure your LAN's firewall to drop TCP packets that originate from outside your LAN where the destination address is the SOAP-Server.

If the SOAP-Server manages sensitive data, you should consider installing only SOAP-Server on the computer, and turning off other nonessential services. This helps reduce the attack surface of the computer and minimizes the number of dependencies on other features over which you may have little control.

It might not be obvious, but this documentation was generated by reviewing a threat model. Here's a portion of the threat model. Each threat below matches a paragraph above.

Threat #4: ISOAP_xxx Account Has Many Privileges

The SOAP-Server process runs as the ISOAP_machinename account, which might have more capabilities and privileges than required by some applications, leading to potential elevation of privilege attacks. The threat is low but real.

Threat #13: Client <-- --> Server Communication Is Insecure

Data between the client and server is not secured from information disclosure or data-tampering threats. The administration tools allow the user to enable SSL/TLS, but it's not the default.

Threat #14: By Default, SOAP-Server Is Accessible to Everyone

For ease-of-use reasons, we do not require authentication to access a SOAP-Server, nor do we restrict access to the system to certain IP or DNS ranges. We simply cannot do this anyway; we don't know ahead of time what the user's policy is, and we don't know whether the user has a firewall. We should consider a setup wizard in the next version to ask the user.

Threat #19: Most of Our Testing Is with Single-Purpose Servers

We do not have the bandwidth to test SOAP-Server with every conceivable service and application that could run on a Microsoft Windows .NET Server 2003 computer. For all we know, some service could require a capability that would render a secured SOAP-Server horribly insecure.