When creating documentation for your project, you should take advantage of some standards defined by the IETF for metasyntactic variables, domain names and IP addresses. Then, if people automatically copy and paste your examples, nothing harmful can (SHOULD!) happen.
RFC 3092 was created on April 1 as a joke (as most RFCs created on that day are). However, there is sane logic to using standardized variables in code examples when documenting an open source project, or providing examples of how or how not to do some concept.
The variables are listed as follows:
- foo
- bar
- baz
- qux
- quux
- corge
- grault
- garply
- waldo
- fred
- plugh
- xyzzy
- thud
An example of documenting how to sanitize input could say something like:
When sanitizing data, you could use:
- $FOO rules when inserting into a database,
- $BAR rules when outputting into a web page,
- $BAZ rules if you need to allow HTML,
- $QUX rules when in an HTML attribute context,
- ...
This a rut a lot of appsec folks find themselves in.
When using domains in your document, you should follow the standards defined in RFC 6761. These domains cannot be registered:
- example.org
- example.com
- example.net
Other example.* TLDs may or may not be available for registration. It's recommended you avoid using them, and stick with the three domains above.
An example of documenting an API to an HTTP service for an open source project could say something like this:
API requests must be sent over HTTP. This example would allow you to get the IP address of the user who submitted the pastebin in JSON format:
When using IPv4 addresses in your document, you should follow the standards defined in RFC 5737. These IPv4 addresses cannot (SHOULD NOT!) be routed:
- 192.0.2.0/24 (TEST-NET-1)
- 198.51.100.0/24 (TEST-NET-2)
- 203.0.113.0/24 (TEST-NET-3)
Note that 128.66.0.0/16 has been used for some documentation examples in the past. However, this block did not appear in the list of special prefixes in RFC 3330 nor its successors, and the block is therefore not reserved for any special purpose. The block sholud be avoided in documentation, and documents using it should be updated to those listed above.
An example of documenting how split DNS behaves could say something like:
If web.example.org is queried on the external Internet, it could return the address 192.0.2.53. However, if web.example.org is queried on the local network, it could return the address 198.51.100.106.
When using IPv4 addresses in your document, you should follow the standards defined in RFC 3849. These IPv6 addresses cannot (SHOULD NOT!) be routed:
- 2001:db8::/32
An example of documenting how networks could divide IPv6 address spaces could say something like:
A /64 is needed for point-to-point communication over IPv6. But logically separating networks may be needed. You could then give a /48 to different departments in your organization, while still assigning a /64 to individual employees.
For example:
- 2001:db8:1::/48 for human resources.
- 2001:db8:1:88::/64 for the human resource director.
- 2001:db8:2::/48 for sales.
- 2001:db8:2:1337::/64 for the sales and billing manager.
- 2001:db8:3::/48 for technical support.
- 2001:db8:3:beef::/64 for the CTO. etc.