Add documentation to the README file

README.md

@@ -124,6 +124,14 @@ A **Finding Group** is a collection of findings that are scored in the same way
 ### Page Template
 A **Page Template** lets you customize report background images and footers.  You can set one **Page Template** as the default, and it will be applied globally unless overridden at the **Engagement** or **Report** level.
 
+## Markdown placeholders
+You can automatically insert client-specific information such as the client name, URL, e-mail, etc. in your reports, by inserting
+`{Client<field>}` in the text. This is particularly useful for report templates.
+
+For example, if you want to refer to the client in your executive summary, you can insert `{ClientName}` in the text. For a specific
+list of fields you can insert, or to insert more, refer to [the markdown.py file](writehat/lib/markdown.py)
+
+Finally, please note that you can also use the editor's 🔗 icon to select these placeholders (and more!).
 
 ## Writing Custom Report Components
 
@@ -252,6 +260,82 @@ $ sudo tar --same-owner -xvpzf db_backup.tar.gz
 $ systemctl start writehat
 ~~~
 
+## Configuring LDAP
+
+Writehat integrates with both Active Directory and OpenLDAP. Your choice
+of technology will affect the two following files:
+
+**writehat/settings.py**
+
+```python
+# LDAP CONFIGURATION
+LDAP_AUTH_URL = writehat_config['ldap']['url']
+LDAP_AUTH_USE_TLS = writehat_config['ldap']['tls']
+LDAP_AUTH_SEARCH_BASE = writehat_config['ldap']['base']
+LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN = writehat_config['ldap']['domain']
+LDAP_AUTH_CONNECTION_USERNAME = writehat_config['ldap']['username']
+LDAP_AUTH_CONNECTION_PASSWORD = writehat_config['ldap']['password']
+
+# The LDAP class that represents a user.
+#LDAP_AUTH_OBJECT_CLASS = "user" --> Replace line below for AD
+LDAP_AUTH_OBJECT_CLASS = "posixAccount"
+
+# User model fields mapped to the LDAP
+# attributes that represent them.
+LDAP_AUTH_USER_FIELDS = {
+    # "username": "sAMAccountName", --> Replace line below for AD
+    "username": "uid",
+    "first_name": "givenName",
+    "last_name": "sn",
+    "email": "mail",
+}
+
+# A tuple of django model fields used to uniquely identify a user.
+LDAP_AUTH_USER_LOOKUP_FIELDS = ("username",)
+
+# Path to a callable that takes a dict of {model_field_name: value},
+# returning a dict of clean model data.
+# Use this to customize how data loaded from LDAP is saved to the User model.
+LDAP_AUTH_CLEAN_USER_DATA = "django_python3_ldap.utils.clean_user_data"
+
+# Path to a callable that takes a user model and a dict of {ldap_field_name: [value]},
+# and saves any additional user relationships based on the LDAP data.
+# Use this to customize how data loaded from LDAP is saved to User model relations.
+# For customizing non-related User model fields, use LDAP_AUTH_CLEAN_USER_DATA.
+LDAP_AUTH_SYNC_USER_RELATIONS = "django_python3_ldap.utils.sync_user_relations"
+
+# Path to a callable that takes a dict of {ldap_field_name: value},
+# returning a list of [ldap_search_filter]. The search filters will then be AND'd
+# together when creating the final search filter.
+LDAP_AUTH_FORMAT_SEARCH_FILTERS = "django_python3_ldap.utils.format_search_filters"
+
+# Path to a callable that takes a dict of {model_field_name: value}, and returns
+# a string of the username to bind to the LDAP server.
+# Use this to support different types of LDAP server.
+# LDAP_AUTH_FORMAT_USERNAME = "django_python3_ldap.utils.format_username_active_directory_principal" --> Replace line below for AD
+LDAP_AUTH_FORMAT_USERNAME = "django_python3_ldap.utils.format_username_openldap"
+
+# Set connection/receive timeouts (in seconds) on the underlying `ldap3` library.
+LDAP_AUTH_CONNECT_TIMEOUT = None
+LDAP_AUTH_RECEIVE_TIMEOUT = None
+```
+
+**writehat/config/writehat.conf**
+
+```
+[ldap]
+# The URL of the LDAP server
+url = 'ldap://your-ldap-server'
+# Domain
+domain = 'yourdomain.local'
+# Initiate TLS on connection
+tls = true
+# The LDAP search base for looking up users
+base = 'cn=users,cn=accounts,dc=yourdomain,dc=local'
+# The LDAP username and password for querying the LDAP database
+username = 'your-ldap-lookup-account'
+password = 'your-ldap-lookup-password'
+```
 
 ## Roadmap / *Potential* Future Developments:
 - Change tracking and revisions
@@ -262,6 +346,10 @@ $ systemctl start writehat
 - More advanced table creator with CSV upload feature
 - More granular permissions / ACLs (beyond just user + admin roles)
 
+## Starting afresh
+WriteHat stores your instance's data in the `/mongo` and `/mysql` directories. The easiest way to start from
+scratch is to run `git clean -f -d`.
+
 
 ## Known Bugs / Limitations:
 - Chrome or Chromium is the recommended browser.  Others are untested and may experience bugs.