How-To Develop An Incident Response Report Journal Using GitHub, Sphinx, RTD

Documenting Incident Response Using GitHub, Sphinx, RTD

Prologue

GuardSight analysts use a systematic approach to achieve the objectives of containment, eradication, and recovery during its BreachMasters™ incident response. One component of this approach includes developing content iteratively, in the style of journaling, to describe the adversary compromise as well as the allied response. The aggregated journal content ultimately results in an after action report. Producing the report documentation while conducting the response activities has many benefits including memorializing in near real-time, the increased accuracy of observations and collections, and improved precision of knowledge transfers when transitioning between analysts to manage response fatigue. This document discusses a mechanism for developing the incident response content using the revision control hosting system Github, use of the Sphinx documentation generator, and the optional use of the software hosting system Read the Docs.

Prerequisites

1. Familiarity with contributing to Github

2. Authorized access to Github

3. Familiarity with publishing documentation using Sphinx

4. Sphinx software for Local builds (optional but recommended)

   pip install sphinx sphinx-autobuild

5. Authorized access to Read the Docs for business private hosting (optional)

   • Non-redacted public postings of after action reports is probably not smart - readthedocs.com is private - readthedocs.io is public

6. Github Settings

   vi ~/.gitconfig
   [user]
       name = myName
       email = myName@myEmailDomain
   

Instruction

Bootstrap

1. Create a new repo that will contain the after action report (notice the private key has its boolean value set to true)

   cd ~/sandbox/code/github
   MISSION=$(date +'MISSION-%Y%m%d-1')
   MYORG=guardsight # e.g. ==> https://github.com/${MYORG} <== assign MYORG=yourOrganization
   curl -u $(grep name ~/.gitconfig | awk '{print $NF}') -d '{ "name": "'${MISSION}'", "description": "Incident Response Journal", "private": true, "has_wiki": false }' https://api.github.com/orgs/${MYORG}/repos
   Enter host password for user 'myName':

2. Duplicate a template repo without forking it and mirror-push its contents into the new repo

   git clone --bare [email protected]:guardsight/gsvsoc_mission-model MISSION-BOOTSTRAP
   cd MISSION-BOOTSTRAP/
   git push --mirror [email protected]:${MYORG}/${MISSION}
   cd .. && rm -rf MISSION-BOOTSTRAP

3. Create a development branch and incorporate the remote repo into the local branch

   git clone [email protected]:${MYORG}/${MISSION} ${MISSION}
   cd ${MISSION}
   git checkout develop
   git pull origin develop
   cd docs

4. Replace some default content

   sed -i "s/MISSION-YYYYMMDD-n/${MISSION}/g" source/index.rst source/meta.txt source/conf.py

5. Replace the GuardSight copyright with ${MYORG} copyright
6. Replace docs/source/meta-logo.png with ${MYORG} logo

IT IS PERMISSABLE TO REPLACE THE LOGO AND COPYRIGHT NOTICE IN THE CLONED ${MISSION} AND THE GUARDSIGHT PERMISSION NOTICE IS NOT REQUIRED TO BE INCLUDED IN THE CLONED ${MISSION} OR ANY PORTION OF THE AFTER ACTION REPORT

Edit <=> Commit

1. Develop -> Commit -> Push

   cd ${MISSION}
   git checkout develop; git pull origin develop; cd docs
   gedit source/*.rst source/meta.txt # sudo apt install gedit-plugin-git; # this shows lines that have changed since last commit;
   # make some changes
   git commit -a -m "Mission update"
   git push --tags origin develop

2. Merge into Master -> Push

   git checkout master
   git merge develop
   git push --tags origin master
   git checkout develop
   

Local Build

1. Make up the build

   cd ${MISSION}/docs
   make singlehtml
   make latexpdf
   

2. View the document

   google-chrome build/singlehtml/index.html
   google-chrome build/latex/gsvsoc_mission-model.pdf
   

Read the Docs For Business Build (optional)

1. Import the repo into RTD

   google-chrome https://readthedocs.com/dashboard/import/?
   

2. View the document

   google-chrome https://${MYORG}-$(echo ${MISSION} | tr [[:upper:]] [[:lower:]]).readthedocs-hosted.com/en/latest/